/** This interface encapsulate all responsibilites of
    a Backgammon game. Please consult the book's
    project part for further descriptions.
 
   This source code is from the book 
     "Flexible, Reliable Software:
       Using Patterns and Agile Development"
     published 2010 by CRC Press.
   Author: 
     Henrik B Christensen 
     Department of Computer Science
     Aarhus University
   
   Please visit http://www.baerbak.com/ for further information.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

*/

public interface Game {

  // == mutator methods ==

  /** Reset the entire game to start from scratch. 
   * No player is in turn, and the game awaits a
   * call to nextTurn to start a game.
   */
  public void newGame();

  /** Tell the game instance that the user wants the game to
   * progress after the 'turn has finished' i.e. the player in
   * turn has exhausted his/her abilities for moving checkers.
   * The game responds by changing to the other player and rolling
   * the dice. At the beginning of the game (after 'newGame')
   * the dice are rolled and depending on the roll, the game
   * progresses. NOTE that if the dice rolled are equal in
   * value (like 1,1) then the game state is STILL in the
   * initialisation phase (no player is in turn); thus
   * you must repeatedly invoke nextTurn() until the
   * dice rolled are not equal. The first non-equal valued
   * dice rolled results in a player being defined as the
   * player to move first. If die 1 > die 2 then red starts;
   * otherwise it is black that moves first.
   * 
   * PRECONDITION: The player in turn has indeed exhausted the
   * his/her ability to make moves.
   */
  public void nextTurn();

  /** move one checker from one location to another. If the move is
   * invalid, then no change is made on the board. If moving to a
   * location occupied by a single opponent checke (standard
   * backgammon rules) then the opponent checker is moved to the bar.
   * @param from the location to move the checker from
   * @param to the location to move the checker to
   * @return false if the indicated move is illegal 
   */
  public boolean move(Location from, Location to);


  // accessor methods

  /** return the color of the player that is in turn i.e. is allowed
   *  to make a move.
   * @return the color of the player to move next. If no player is in
   * turn (before the game is started), NONE is returned.
   */
  public Color getPlayerInTurn();

  /** return the number of moves left in the current turn. I.e. if a
   * new turn has just begun and the dice rolled are [1,2] the return
   * value is 2. If dice rolled are [3,3] then the return value is 4
   * (if using standard backgammon rules). The number of moves left
   * are subject to the backgammon rules, that is if the player that
   * has just rolled cannot use the dice values at all (for instance
   * in situations where a checker is in the bar and the points are
   * blocked for the given rolled dice) then the return value is 0.
   * @return the number of moves left for the player-in-turn subject
   * to the rules of backgammon.
  */
  public int getNumberOfMovesLeft();

  /** return an integer array of size exactly 2 containing the
    * values of the dice thrown.
    * @return array of two integers defining the dice values rolled last.
    */
  public int[] diceThrown();

  /** return an integer array of size in range [0;4] containing
   * die values that have not yet been used to move a checker.
   * POSTCONDITION: The array is sorted so the largest die value
   * is first in the array.
   * @return int array of unused die values.
   */
  public int[] diceValuesLeft();

  /** return the winner of this game. 
   * @return the winner of the game; if game is still in progress, then
   * Color.NONE is returned.
   */
  public Color winner();

  // == ACCESSORS to the board 

  /** get the colour of the checkers on a given location.
   * @param location the location on the board to access
   * @return the color of the checkers on this location
   */
  public Color getColor(Location location);
  
  /** get the count of checkers of this location.
   * @param location the location to inspect
   * @return a integer value showing the number of checkers on this location.
   */
  public int getCount(Location location);
  
}