/*
 * ITicTacToeModel.java
 *
 * Created on December 4, 2002, 5:39 PM
 */

package TicTacToe;

/** A model of the game TicTacToe.
 * The two players are identified as A and B in the documentation, and as the
 * characters 'A' and 'B' (case-sensitive) in the code.
 * A always makes the first move.
 * No move can be made until the game is placed in the "started" state.
 * The game continues, with players taking alternate turns, until the game enters
 * the "stopped" state.  This can happen when 1) a player wins 2) there is a draw
 * (the player whose turn it is cannot make any move) or 3) a "stop" request is
 * received.  While stopped, game state doesn't change, but remains available for
 * querying.  (Note: "stop" is permanent, not a pause).
 *
 * Winning is determined by the customary rules for TicTacToe (three marks in a row
  in any direction).
 *
 * The game can only be started and stopped once.
 *
 * The game board positions are identified externally by row and column numbers, 
    1..3, with row first.
 *
 * The implementor should provide one constructor, with no arguments, which
 * places the game in a not-yet-started stated.  In that state, the model is not
 * required to maintain any infomration, except "started" or "not started".
 *
 * The model keeps track of how many moves have been made.
 *
 * "Player names" are recorded by the model so they can be passed through to a
 * viewer, but are otherwise ignored.  The internal names remain A and B.
 *
 */
public interface ITicTacToeModel {
    
    void setPlayerAName(String name);
    
    void setPlayerBName(String name);
    
    String getPlayerAName();
    
    String getPlayerBName();
    
    /** Signal that the game is starting. 
     Precondition: the game has not been started
     *  Postcondition: the game is in the started state, with a blank gameboard.
     */
    void startGame();
    
    /** Signal the the game is to stop. 
     Precondition: the game has been started, but is not yet stopped
     *  Postcondition: the game is in the stopped state
     */
    void stopGame();
    
    /** Signal that the application is finished.  After a finish, the model
     * is not required to maintain board or player state.  Any viewers or
     * listeners are free to wrap up or terminate.
     * The Controller should call this method before terminating its own
     * execution.  Viewers should not call this method, except to signal
     * some extraordinary condition which requires immediate termination.
     Precondition: none
     *  Postcondition: regardless of previous state, the game is placed in
     * the started and stopped states.
     *
     */
    void terminateGame();
    
    /** Process a move by a player.
     * Pre: the game is started and not stopped, and it is the player's turn.
     * Post: the game board reflects the change.  If the move causes one player 
     * to win, the status changes to "stopped".  If the move is legal, the move count 
     * in increased by 1
     
     This method is the only place in the model where the move count
     * is increased.  It is also the only place (except the constructor) where
     * the marks on the gameboard are changed.
     *
     * @return true if the move is carried out, false if the move is not
     * carried out (probably because it was to a space already marked).
     * @throws IllegalArgumentExeception if any argument value is illegal,
            or if it is not the player's turn.
     */
    boolean makeMove(char player, int row, int col);
    
    /** Answer, what mark is on the board position indicated?
     * Pre: the state is "started"; row and col are valid
     * @return one of the character values 'X', 'O', or ' ' (case-sensitive)
     */
    char getPositionMark(int row, int col);
    
    /** Answer, has A won?
     * If A has won, that implies that B has not won.
     * However, if A has not won, that does not imply that B has won.  It might
     * be that no one has won.
     * Pre: none
     * @return true iff the game is stopped and A is the winner.
     *
     */
    boolean AhasWon();
    
    /** Answer, has B won?
     * Pre: none
     * @return true iff the game is stopped and B is the winner.
     */
    boolean BhasWon();
    
    /** Answer, is the game in the stopped state?
     */
    boolean isGameOver();
    
    boolean isGameStarted();
    
    boolean isGameTerminated();

    
//end ITicTacToeModel    
}