mvc143
Interface IBoggleController


public interface IBoggleController

This interface provides the methods for overall control of a Boggle Game. For CSE143, the concrete Controller classes must be located in boggle.controller.BoggleController.java
The constructor must take NO parameters. The constructor must create the Model and View.
The class must have a main method which simply creates an instance of the Controller. After that, once the View is in execution, things should run on their own. There are no defined command-line arguments for main.
IMPORTANT NOTE #1! : Many of the methods are simply "pass-throughs" to the Model. Don't keep duplicate information in both modules. For example: what characters are on the board; how many rows and columns there are, etc. all are part of the Model, even though this Controller interface has methods which allow the Controller to be queried for them. Before implementing any Controller methods, it is recommended that you be thoroughly familiar with what is in the other two modules to avoid duplication.
The necessary resource files (if any), like dictionary and boards, are recommended to be located in the directory of the controller.
IMPORTANT NOTE #2 : You must define these two public static fields to specify the author and a brief description. as follows:
public static final String author = " ... ";
public static final String description = " ... ";
"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.


Method Summary
 void addToDictionary(String[] words)
          Add new words to dictionary without changing what was already there.
 boolean addToProposal(int row, int col)
          This method will add the letter specified by row and col to the proposal string.
 void endGame()
          End the current running game.
 int getBoardCols()
          Get the number of columns in the board.
 int getBoardRows()
          get the number of rows in the board.
 long getGameTime()
          Get the total time duration of a game in milliseconds.
 int getLetterInBoard(int row, int col)
          return the character at the position specified by row and col.
 long getMillisRemaining()
          Get the remaining left in the current game.
 int getScore()
          Get the score for the current game.
 String getStatus()
          Return a message which this components wants to be visible to the user.
 List getWordsHistory()
          Get the words history from the Model.
 boolean isNewProposal()
          Determine if the current word proposal is empty or not, i.e., whether any letters have been added to it.
 boolean isRunning()
          This method will tell if the game is ended or not.
 boolean loadDictionary(String fileID)
          Load a dictionary from a resource (file).
 void newProposal()
          The current word proposal will be cleared.
 boolean removeLetterFromProposal()
          Remove the last character in the proposed word.
 void setGameTime(long gametime)
          Set the time duration of one game.
 void startGame()
          Start a new game, with a new internally generated board.
 void startGame(String fileID)
          Start a new game, intializing the board from the file given.
 void startTimer()
          Start the timer, if the timer is stopped (create a new timer and start it, if there wasn't already a timer)
 int submitProposal()
          When the user submits the proposed word, this method will check if the word is valid or not.
 void terminateApplication()
          Terminate the application.
 

Method Detail

addToProposal

public boolean addToProposal(int row,
                             int col)
This method will add the letter specified by row and col to the proposal string. It will check if the position is valid or not before adding.

Parameters:
row - the row from which the letter comes.
col - the column from which the letter comes.
Returns:
true, if the letter is successfully added; false, otherwise .

removeLetterFromProposal

public boolean removeLetterFromProposal()
Remove the last character in the proposed word.

Returns:
true, if succeessful, false, if not successful, or of the remove operation is not suported by the implemention.

submitProposal

public int submitProposal()
When the user submits the proposed word, this method will check if the word is valid or not. The score will be updated then.

Returns:
-1 means the word was invalid. All other return values should indicate success, but no meaning is defined for them.

newProposal

public void newProposal()
The current word proposal will be cleared.


isNewProposal

public boolean isNewProposal()
Determine if the current word proposal is empty or not, i.e., whether any letters have been added to it. It may or may not be useful in your implementation, but keep it for someone's need.

Returns:
true if the proposal is empty false otherwise

getBoardCols

public int getBoardCols()
Get the number of columns in the board.

Returns:
the cols of the boggle board

getBoardRows

public int getBoardRows()
get the number of rows in the board.

Returns:
the rows of the boggle board

getLetterInBoard

public int getLetterInBoard(int row,
                            int col)
return the character at the position specified by row and col. (Implement this by asking the model for the information).

Parameters:
row - an integer specifying the row in the board
col - an integer specifying the col in the board
Returns:
the character, or -1, if the position is not valid

setGameTime

public void setGameTime(long gametime)
Set the time duration of one game. If no time is ever set, then the default of three minutes (as specified by official Boggle rules) should be used.

Parameters:
gametime - the long type integer to specify the duration in milliseconds.

getGameTime

public long getGameTime()
Get the total time duration of a game in milliseconds.

Returns:
a long type integer to specify the time duration of one game.

getMillisRemaining

public long getMillisRemaining()
Get the remaining left in the current game.

Returns:
the time remained for one game in milliseconds, if a game is in progress; return 0 if no game is in progress.

startTimer

public void startTimer()
Start the timer, if the timer is stopped (create a new timer and start it, if there wasn't already a timer)


startGame

public void startGame()
Start a new game, with a new internally generated board. Starting a game may involve inititalizing or reinitializing various other parameters and features of the board.


startGame

public void startGame(String fileID)
Start a new game, intializing the board from the file given. Starting a new game may also involve inititalizing or reinitializing various other parameters and features of the game. If the fileID is null or the file read fails, leave the board unchanged, supposing we have already have one.

Parameters:
fileID - the location of the board to use.

endGame

public void endGame()
End the current running game.


isRunning

public boolean isRunning()
This method will tell if the game is ended or not. Typically when the time is up, the game should be ended by controller automatically; everything will be stopped and waiting for start again

Returns:
return true, if the game is still running false, if a game is not in progress.

getScore

public int getScore()
Get the score for the current game.

Returns:
the current score

getStatus

public String getStatus()
Return a message which this components wants to be visible to the user. It is strongly encouraged that this message contain the current status of the proposal (for example, the proposal itself; a message indicating rejection or acceptance if the proposal was recently submitted, etc.) For example, the View might choose to periodically display the message.

Returns:
a string containing the status message

getWordsHistory

public List getWordsHistory()
Get the words history from the Model. The idea of "history" is to let the model keep track of all the words the user has already got correct in the current game.

Returns:
a list of history information; if there is no history or a history is simly not implemented, should return empty List; should not return null.

loadDictionary

public boolean loadDictionary(String fileID)
Load a dictionary from a resource (file).

Parameters:
fileID - a string to specify the place to load the resource from.
Returns:
true if succeed false if not succeed or no file specified

addToDictionary

public void addToDictionary(String[] words)
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.

Parameters:
words - an array of strings to store in the dictionary

terminateApplication

public void terminateApplication()
Terminate the application. Among other things, call the terminate methods of the Model and the View so that they can perform any required clean-up.