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

/**
 * This interface provides the methods needed for the Boggle Model, that is,
 * methods to manipulate the board data, score data and dictionary model.
 * <br />
 * The constructor of BoggleModel must take exactly these four parameters:
 *   a String specifying the board file to be loaded initially (may be null).
 * 	 a String specifying the dictionary file to be loaded (may be null). 
 *   an int which specifies how many rows the board should be (>=4).
 *   an int which specifies how many cols the board be (>=4). * 
 * <br />
 * IMPORTANT NOTE #2 :
 * You must define these two public static fields to specify the author and a brief description.
 * as follows:<br />
 *	public static final String author = " ... ";<br />
 *  public static final String description = " ... ";
 * <br />
  "authors" should identify the authors in some fashion, but pseudonyms or
  nicknames are acceptable.  "description" should give a brief description
  of the module, especially if there are any unexpected or unique features 
  about it.  The information in both fields may be visible to the general
  public, indefinitely into the future, so do not place any information here
  which you do not wish to be publicly available.
 * @author xm
 *
 */
public interface IBoggleModel {

 /**
  * create a new board by loading from a resource (file)
  * if fileID is null, the board is created internally (for example, it
  *  randomly assigns the characters for each cell).
  * @param fileID a String specifies the resource (file) of a designed board;
  * or null if an internally generated board should be produced.
  * @return true, if the board successfully has been created;
  *			false, otherwise
  */
 public boolean createBoard(String fileID);

 
 /**
  * Retrive the character on the cell specified by col and row.
  * If the position is invalid, return -1.
  * @param col the column in the board
  * @param row the row in the board
  * @return the character at that position, or
  *    -1, if the position is invalid.
  */
 public int getLetter(int row, int col);


 /**
  * Tells the number of columns of the board.
  * @return the columns of the board.
  */
 public int getCols();


  /**
  * Tells the number of rows of the board
  * @return the rows of the board.
  */
 public int getRows();
 
  
 /**
  * Add to the score.
  * @param scoreAugment >=0, the value to be added to the total score.
  * @return the total score after modification.
  */
 public int addScore(int scoreAugment);


 /**
  * Tell the current score.
  * @return the current score.
  */
 public int getScore();


  /**
  * Reset the score to zero; for example, at the start of another game.
  *
  */
 public void resetScore();
 

/**
 * make the words model object visible to controller
 * @return the words model object used by this model.
 */
 public IBoggleWordsModel getWordsModel();
 
 
 /**
  * Perform cleanup when the application is about to end.  Should only
  * be called by the Controller.
  * (You don't neccessarily need to do anything, but it's an opportunity.)
  *
  */  
 public void terminate();
}