package comp303;

/**
 * Supports the game logic for blackjack.  The game of blackjack is turn-
 * based and requires the maintenance of game state.  The IDealer interface
 * provides methods for altering the state of the game based on actions of the
 * players and for querying the state of the game (e.g., what's in each player's hand,
 * including the dealer).  It is important that implementations of this interface do
 * not allow clients to modify the state of the game in a way that is unknown by
 * IDealer.  This interface must be completed with contracts and additional methods
 * to query the state of the game.
 * @author Nomair A. Naeem and Martin Robillard
 */
public interface IDealer 
{
	/**
	 *  Used to register a player with the dealer. Simulates the 
	 *  process of a player coming to sit in on a blackJack game and cashing
	 *  some money for chips.
	 * 
	 * @param pPlayerID The name of the player who is registering
	 * @param pMoney  The amount of money the player is buying chips from
	 * @precondition No Hand is in play
	 * @precondition pPlayerID != null
	 * @precondition pMoney > 0 
	 * @precondition pPlayerID is not already registered 
	 * @postcondition The number of registered Players is greater by one.
	 */
	void register( String pPlayerID, int pMoney  );

	/**
	 * In order to be involved in a hand being played players need to place
	 * bids using this method. Any player who does not place a bid will not
	 * be dealt cards and hence will not be part of the hand.
	 * 
	 * @param pPlayerID The ID of the player who is placing a bid
	 * @param pBid The amound of bid made by player
	 * @precondition The player is already registered 
	 * @precondition The player has enough money to cover the bid 
	 * @precondition A hand is not already in play 
	 * @precondition Player hasn't already placed a bid 
	 */
	void placeBid( String pPlayerID, int pBid );

	/**
	 * Once all the bids are in place invoking this method results
	 * in cards dealt to the players and the dealer.
	 *
	 * @precondition At least one registered player has placed a bid 
	 * @precondition Another hand is not already in play 
	 * @postcondition Each player who had made a bid has been dealt
	 * two randomly chosen cards. 
	 */
	void dealCards();
 
	/**
	 * To give a player an additional card.
	 * @param pPlayerID The player to hit
	 * @param pHandNumber The hand number on which the player wants a hit. 
	 * This is usually 0 unless the hand was split by the player.
	 * 
	 * @precondition pPlayerID should be registered and should have bidded 
	 * @precondition It should be this player's turn 
	 * @precondition pHandNumber should be a valid hand for this player 
	 * @precondition Cards must have been dealt 
	 * @precondition Hand should not be a BLACKJACK
	 * 
	 * @postcondition A new Card has been dealt to the players specified hand. 
	 * @postcondition If the player busts the player's turn is finished provided there are no more
	 * hands for this player. 
	 * @postcondition If the hand was a split hand the player might have gotten a blackjack and the
	 * hand is marked as blackjack and play moves to next hand/player.
	 */		
	void hit( String pPlayerID, int pHandNumber );

	/**
	 * To have a player stand on a hand.
	 * @param pPlayerID The player whose has asked to stand
	 * @param pHandNumber The hand number on which the player wants to stand. 
	 * This is usually 0 unless the hand was split by the player
	 * 
	 * @precondition Player should be registered and should have bidded 
	 * @precondition It should be this player's turn 
	 * @precondition pHandNumber should be a valid hand for this player 
	 * @precondition Cards must have been dealt
	 */
	void stand( String pPlayerID, int pHandNumber );
	
	/**
	 * To surrender a hand.
	 * @param pPlayerID The player whose has asked to surrender
	 * @param pHandNumber The hand number which the player wants to surrender.
	 * This is usually 0 unless the hand was split by the player
	 * 
	 * @precondition pPlayerID should be registered and should have bidded. 
	 * @precondition It should be this player's turn. 
	 * @precondition pHandNumber should be a valid hand for this player. 
	 * @precondition Cards must have been dealt. 
	 * @precondition The hand shoud not be a blackjack
	 * @precondition The hand was not already surrendered
	 * 
	 * @postcondition The player loses half his bid money. 
	 */
	void surrender( String pPlayerID, int pHandNumber );

	/**
	 * Used to ask for one final hidden card. The bid is doubled.
	 *  
	 * @param pPlayerID The player whose has asked to double
	 * @param pHandNumber The hand number which the player wants to double. 
	 * This is usually 0 unless the hand was split by the player
	 * 
	 * @precondition pPlayer should be registered and should have bidded. 
	 * @precondition Cards must have been dealt.
	 * @precondition It should be this player's turn. 
	 * @precondition pHandNumber should be a valid hand for this player. 
	 * @precondition The hand is not a blackjack
	 * @precondition The hand is not surrendered
	 * @precondition Enough money should be available to cover increase in bid
	 * 
	 * @postcondition Players bid doubles 
	 * @postcondition player gets one hidden card
.	 */
	void doubleHand( String pPlayerID, int pHandNumber );
	
	/**
	 * Used to split a hand into two.
	 *  
	 * @param pPlayerID The player whose has asked to split
	 * @param pHandNumber The hand number which the player wants to split. 
	 * This is usually 0 unless the hand was split by the player
	 * 
	 * @precondition pPlayerID should be registered and should have bidded.
	 * @precondition Cards must have been dealt.
	 * @precondition It should be this player's turn. 
	 * @precondition pHandNumber should be a valid hand for this player. 
	 * @precondition The hand is not a blackjack
	 * @precondition The hand is not surrendered
	 * @precondition The hand is not doubled
	 * @precondition The hand should splittable
	 * @precondition There is enough money should be available to cover increase in bid
	 * 
	 * @postcondition Players bid doubles 
	 * @postcondition player gets two hands to play
.	 */
	void split( String pPlayerID, int pHandNumber );

	/**
	 * Restarts the dealer for a new game.
	 */
	void refresh();
}