package com.pm.server.registry;

import com.pm.server.PmServerException;
import com.pm.server.datatype.Player;

public interface TagRegistry {

    /**
     * Registers a tag by one player to one player.
     *
     * <p>
     *     Has no effect if a player has already won.
     * </p>
     * <p>
     *     The tag will be removed after 15 seconds if not reciprocated.
     * </p>
     *
     * @param tagger Player who is tagging
     * @param taggee Player who is being tagged
     * @return Whether the tag reciprocates a previously registered tag
         from {@link #receiveTagFromPlayer(Player.Name, Player.Name)}
         (triggering a gamestate change)
     * @throws PmServerException if the tagger and taggee are the same
     *
     */
    Boolean tagPlayer(Player.Name tagger, Player.Name taggee) throws PmServerException;

    /**
     * Registers a tag by one player to one player.
     *
     * <p>
     *     Has no effect if a player has already won.
     * </p>
     * <p>
     *     The tag will be removed after 15 seconds if not reciprocated.
     * </p>
     *
     * @param taggee Player who is being tagged
     * @param tagger Player who is tagging
     * @return Whether the tag reciprocates a previously registered tag
         from {@link #tagPlayer(Player.Name, Player.Name)}
         (triggering a gamestate change)
     * @throws PmServerException if the tagger and taggee are the same
     *
     */
    Boolean receiveTagFromPlayer(Player.Name taggee, Player.Name tagger)
            throws PmServerException;

    /**
     * @return The player who has successfully tagged another player, or null
         if the game has not ended yet
     */
    Player.Name getWinner();

    /**
     * Removes all tags and recorded winners.
     */
    void clearTagsAndWinner();

}

@@ -187,32 +187,52 @@
 er to one player
+, sent by the tagger
 .%0A     *%0A     * 
@@ -438,32 +438,59 @@
 r who is tagging
+ (and registering this tag)
 %0A     * @param t
@@ -852,16 +852,28 @@
  taggee)
+%0A           
  throws 
@@ -950,16 +950,36 @@
 e player
+, sent by the taggee
 .%0A     *
@@ -1198,32 +1198,59 @@
  is being tagged
+ (and registering this tag)
 %0A     * @param t

Clarify difference between the two tag methods