/*
 * Created on 2004-7-29
 *
 */
package mvc143;

import java.util.Collection;
import java.util.List;

/**
 * An aspect of the Model. This inferface provides the methods neccessary to 
 * manipulate the dictionary data and word history data.  The interface could
 * be implemented by the same concrete class that implements IBoggleModel,
 * or it could be a separate class.  For use with the 143 Mix Matcher, a separate class
 * would have to be inside the same compilation unit, i.e., .java file, as
 * the main Model class.
 * <br />
 * @author xm
 *
 */
public interface IBoggleWordsModel {
	/**
	  * Load a dictionary from a resource (file).
      * if file load failed or no file specified, create an empty dictionary.
  	  * Never leave the dictionary null.  Matching of words from
   * the dictionary is supposed to be case-insensitive.  Although this
   * method is not responsible for matching, it may wish to convert all words
   * to upper case before storing them.
	  * @param fileID a String which specifies the place to load the resource from.
	  * @return true if successfully loaded.
	  *         false if load failed or no file specified.
	  */
	 public boolean loadDictionary(String fileID);
 
	 /**
	  * set the dictionary to be a given one.  It is expected that each
	  * entry in the collection would be a single, trimmed string,
	  * representing a word to be considered valid for the game.
	  * 
	  * @param dict a non-null collection used to set the dictionary
	  * to an external source.
	  */
	 public void setDictionary(Collection dict);
 
	 /**
	  * Add new words to dictionary, without changing what was already there.
	  
	  *  Matching of words from
   * the dictionary is supposed to be case-insensitive.  Although this
   * method is not responsible for matching, it may wish to convert all words
   * to upper case before storing them.
	  * @param words an array of strings to store in dictionary; each string
	  * should be non-null and non-empty.
	  */
	 public void addToDictionary(String[] words);
 
	 /**
	  * Determine if the selected square of the board is a legal position
	  * for the next letter of the word being developed.  According to the
	  * rules, the letters must be adjacent; this is the method that checks
	  * that constraint.  [Implementation hint: to make this method word,
	  * you will have to know the row and column of the previous letter, too, 
	  * if there was a previous letter.]
	  * @param row specify the row of the letter selected.
	  * @param col specify the column of the letter selected.
	  * @return true if it is valid; otherwise false.
	  */
	 public boolean isValidPosition(int row, int col);
 
	 /**
	  * Determine if the word proposed is valid or not.
	  * 
	  *    check if the word is in the dictionary (case-insensitive).<br />
	  *    check if the word has already been proposed(in the history) before.
	  *    ...   
	  * @param proposal a String contains the word being proposed.
	  * @return 0 if the word is valid; 1 if the word if not in the 
	 * dictionary; 2 if the word is a duplicate.  Other values also
	 * indicate failure but are not defined.
	  */
	 public int isValidWord(String proposal);
 


	 /**
	  * get a history (list) of all accepted words in the current game. 
      * @return a List containing all the accepted words.
	  * 		empty List if no history or not supported/implemented (don't 
	  * return null).
	  */
	 public List getHistory(); 

	 /**
	  * Clear the history list.
	  * 
	  */
	 public void emptyHistory();
	 
	 /**
	  * Add the accepted proposal to the history.
	  *@param acceptedProposal a string that to be added to the history
	  */
 	 public void addToHistory(String acceptedProposal);

}