/*
 * Created on 12-Jul-2005
 */

package comp303;

import java.io.IOException;
import java.util.List;

/**
 * Behavior to manage the storage, retrieval and computation of 
 * statistics relates to a game of blackjack.
 * 
 * @author Nomair A. Naeem and Martin P Robillard
 */

public interface IStats 
{
	int WIN 		= 0;
	int BLACKJACK 	= 1;
	int PUSH 		= 2;
	int LOSS 		= 3;
	int SURRENDER 	= 4;
	
	/**	
	 * Store the statistics into a file with the name provided.  
	 * 
	 * @param pFileName the name of the file in which to store the statistics
	 * @throws IOException if the statistics cannot be stored
	 * @precondition pFilename is non-null.
	 * @postcondition All statistics in memory are written onto file identified 
	 * by pFileName. Statistics just written remain in memory too.
	 */
	void save( String pFileName ) throws IOException;

	/**
	 * Load statistics by reading from a file with the given name. 
	 * 
	 * @param pFileName the name of the file from which statistics are 
	 * to be loaded
	 * @throws IOException if the statistics cannot be loaded
	 * @precondition The parameter <code>pFilename</code> is non-null.
	 * @postcondition All statistics in file identified by <code>pFilename</code> are
	 * read into memory. Any statistics previously in memory are overwritten.
	 */
	void load( String pFileName ) throws IOException;
	
	/**
	 * Clear any statistics present in memory.
	 *
	 * @postcondition All statistics in memory are purged. 
	 */
	void clearStats();
	
	/**
	 * Add a new hand to the statistics currently in memory.
	 * 
	 * @param pPlayerID the id of the player whose statstics is being stored
	 * @param pTotalBid the total bid made by this player, in cents
	 * @param pResult the result of the hand for this player
	 * @precondition pPlayerID is non-null.
	 * @precondition pTotalBid > 0
	 * @precondition pResult is one of the constants provided by the interface 
	 * @postcondition Statistics contains the added hand.
	 * @postcondition The number of hands in memory increases by one.
	 */
	void addHand( String pPlayerID, int pTotalBid, int pResult );

	/**
	 * Compute the number of hands played by all players.
	 * 
	 * @return the number of hands stored in the currently 
	 * 	       loaded statistics.
	 */
	int totalHands();
	
	/**
	 * Compute the number of hands played by a particular player.
	 * 
	 * @param pPlayerID the id of the player whose total Hands are to be 
	 *        computed
	 * 
	 * @return the number of hands stored for this player in the 
	 *         currently loaded statistics. If the playerId did not exist
	 *         return 0 
	 *@precondition pPlayerID is non-null.
	 */
	int totalHands( String pPlayerID );
	
	/**
	 * Compute the total amount of money won or lost by all players 
	 * combined. 
	 * 
	 * @return the amount of money won or lost by all the players combined
	 *         as indicated by the currently loaded statistics. A positive
	 *         number indicates players made money, negative means the players
	 *         lost money and zero if the players did not lose or win.
	 */
	int take();
	
	/**
	 * Compute the total amount of money won or lost by a certain player.
	 * 
	 * @param pPlayerID the id of the player whose take has to be computed
	 * @return the amount of money won or lost by this player as indicated
	 *          by the currently loaded statistics. A positive
	 *         number indicates player made money, negative means the player
	 *         lost money and zero if the player did not lose or win or 
	 *         was not found.
	 * @precondition pPlayerID != null
	 */
	int take( String pPlayerID );
	
	/**
	 * Compute the average amount of money won or lost by the players.
	 * 
	 * @return the average amount of money won or lost by all players
	 *         currently present in the loaded statistics
	 */
	int averageTake();
	
	/**
	 * Obtain a unique list of player names who have statistics stored
	 * in memory.
	 * 
	 * @return a unique list of players who have hands stored in memory, 
	 *         Empty list is returned if no player statistics are present
	 */
	List getPlayerNames();
}