package de.lmu.ifi.pp.player;

import java.util.regex.Pattern;

import de.lmu.ifi.pp.model.Coord;
import de.lmu.ifi.pp.model.PieceColor;
import de.lmu.ifi.pp.player.action.LobbyAction;
import de.lmu.ifi.pp.util.net.ProtocolConstants;

/**
 * Basic idea:
 * <ul>
 * <li> The server always calls the player (and never vice-versa): The player
 * connects to the server (via a socket) and then waits for its "procedures" to
 * be invoked by the server via "remote procedure calls" (RPCs). The available
 * procedures are the methods of this interface, the RPC conventions are
 * outlined below.
 * </ul>
 * 
 * RPC conventions:
 * <ul>
 * <li> Caller: Sends method name and arguments, separated by tab, terminated by
 * newline
 * <li> Callee: Sends return value, terminated by newline
 * </ul>
 * 
 * Tournament versus Lobby:
 * <ul>
 * <li> Player closes the socket
 * <ul>
 * <li> Tournament: can reconnect later.
 * <li> Lobby: leaves the lobby.
 * </ul>
 * </ul>
 * 
 * Serialization of types:
 * <ul>
 * <li> void: "OK"
 * <li> boolean: "true" bzw. "false"
 * <li> PieceColor: "BLACK", "WHITE", "null"
 * <li> Coord: "0,2" // x,y, coordinate system starts in the upper left corner
 * at (0,0)
 * <li> String: strings with tab are not allowed as arguments
 * <li> String[] (as single arguments and return values): transmitted as one
 * string, separated by {@link #SEP}.
 * </ul>
 * 
 * History:
 * <ul>
 * <li> V1.0: First public version.
 * <li> V1.1: Additional argument for openGame(), new method error(), removed
 * one argument from closeGame()
 * <li> V1.2: trackAndComputeMove(), changed legal names, separate
 * {@link ProtocolConstants}
 * <li> V1.3: lobby mode
 * <li> V1.4: ACTION_PLAY extended to include a choice of color,
 * <code>getRules()</code> changed to {@link #setRuleKind(String)}
 * <li> V1.5: More comments to clarify the specification
 * </ul>
 */
public interface PlayerInterface extends ProtocolConstants {
    /**
     * Used by the server to check for legal names.
     */
    public static final Pattern LEGAL_NAME = Pattern.compile("^[0-9][0-9] ([A-ZÄÖÜa-zäöü0-9 !?.-]+)$");

    public static final String RULES_MODE_TOURNAMENT = "Tournament";
    public static final String RULES_MODE_LOBBY = "Lobby";
    public static final String RULES_GAME_TICTACTOE = "TicTacToe";
    public static final String RULES_GAME_REVERSI = "Reversi";
    public static final String RULES_SEP = "-";
    public static final String RULES_KIND_REVERSI_TOURNAMENT = RULES_GAME_REVERSI+RULES_SEP+RULES_MODE_TOURNAMENT;
    public static final String RULES_KIND_REVERSI_LOBBY = RULES_GAME_REVERSI+RULES_SEP+RULES_MODE_LOBBY;
    public static final String RULES_KIND_TICTACTOE_TOURNAMENT = RULES_GAME_TICTACTOE+RULES_SEP+RULES_MODE_TOURNAMENT;
    public static final String RULES_KIND_TICTACTOE_LOBBY = RULES_GAME_TICTACTOE+RULES_SEP+RULES_MODE_LOBBY;

    public static final String GET_NAME = "getName";
    public static final String SET_RULE_KIND = "setRuleKind";

    public static final String OPEN_GAME = "openGame";
    public static final String TRACK_MOVE = "trackMove";
    public static final String COMPUTE_MOVE = "computeMove";
    public static final String TRACK_AND_COMPUTE_MOVE = "trackAndComputeMove";
    public static final String CLOSE_GAME = "closeGame";
    public static final String ERROR = "error";

    public static final String WAITING_PLAYERS_CHANGED = "waitingPlayersChanged";
    public static final String GET_LOBBY_ACTION = "getLobbyAction";

    public static final String NAME_IN_USE_PREFIX = "Name already in use: ";
    
    //----------------------------- Basics

    /**
     * Invoked at least once (and possibly several times) at the beginning of
     * this protocol. Invoked together with {@link #getName()}, but we don't
     * specify in which order.
     * 
     * @param ruleKind
     *            what kind of rules does the server follow? Example:
     *            {@link #RULES_KIND_REVERSI_TOURNAMENT}
     * @return <code>true</code> if the player knows how to handle the rules
     *         dictated by the server.
     */
    public boolean setRuleKind(String ruleKind);

    /**
     * Invoked once at the beginning of this protocol. Invoked together with
     * {@link #setRuleKind(String)}, but we don't specify in which order.
     * 
     * @return Only the following characters are allowed: {@link #LEGAL_NAME}}
     */
    public String getName();

    /**
     * Start a new game.
     * 
     * @param color what is the color of the implementor of this interface?
     * @param opponentName the name of the opponent
     */
    public void openGame(PieceColor color, String opponentName);

    /**
     * Track a move of the opponent
     */
    public void trackMove(Coord coord);

    /**
     * Compute your own move.
     * 
     * @param timeLimit
     *            in milliseconds
     */
    public Coord computeMove(long timeLimit);

    /**
     * Compute your own move.
     * 
     * @param timeLimit
     *            in milliseconds
     */
    public Coord trackAndComputeMove(Coord coord, long timeLimit);

    /**
     * @param winner
     *            Who won the game? <code>null</code> is used for a tie.
     */
    public void closeGame(PieceColor winner);

    /**
     * Feedback from the server. Mainly interesting for human users. Often sent
     * just prior to closing a socket in reaction to a mistake the player made.
     */
    public void error(String message);

    //----------------------------- Lobby

    /**
     * Definition <i>available</i> players: A player becomes unavailable when
     * it takes part in a game or leaves the lobby (by disconnecting or
     * quitting). It becomes available when entering the lobby.
     * <p>
     * This method is only invoked on available players in the lobby, whenever
     * one of the following two things happen:
     * <ul>
     * <li> A player has just logged in. Thus she needs to know what players are
     * available.
     * <li> The available players change.
     * </ul>
     * 
     * @see String#split(String) for parsing
     */
    public void waitingPlayersChanged(String[] playerNames);

    /** Do nothing */
    public static final String ACTION_WAIT = "!wait";
    
    /** Leave the lobby */
    public static final String ACTION_QUIT = "!quit";
    
    /**
     * Signature:
     * <blockquote>
     * ActionPlay(PieceColor ownColor, String opponentName, [long computationTimeout, boolean forceTimeout])
     * </blockquote>
     * Comments:
     * <ul>
     * <li> If ownColor is <code>null</code>, it means that the choice of color
     * should be randomized by the server.
     * <li> We add the network latency to the computationTimeout! How the server determines
     * that latency is unspecified.
     * </ul>
     */
    public static final String ACTION_PLAY = "!play";
    
    /**
     * Time interval for polling the client can be freely determined by the
     * server. The return data written to the socket here can be seen as a
     * remote procedure call in the opposite direction (when compared to all
     * other RPC in this interface).
     * 
     * @return an object representing one of the constants {@link #ACTION_WAIT},
     *         {@link #ACTION_QUIT} or {@value #ACTION_PLAY}. The complete line sent
     *         depends on the ACTION_* that is involved example:
     *         <pre>
     *         ACTION_PLAY+SEP+ownColor.toProtocolString()+SEP+...
     *         </pre>
     */
    public LobbyAction getLobbyAction(); 
}