diff --git a/forge-gui/src/main/java/forge/view/Cache.java b/forge-gui/src/main/java/forge/view/Cache.java index 816f558b7bd..449c6c09ac4 100644 --- a/forge-gui/src/main/java/forge/view/Cache.java +++ b/forge-gui/src/main/java/forge/view/Cache.java @@ -5,28 +5,63 @@ import java.util.Map; import com.google.common.collect.Maps; +/** + * Implementation of a two-way cache, containing bidirectional mappings from + * keys of type {@code K} to values of type {@code V}. + * + * Keys and values are checked for equality using the + * {@link Object#equals(Object)} method. + * + * @author elcnesh + * + * @param + * the type of this Cache's keys. + * @param + * the type of this Cache's values. + */ public class Cache { private final Map cache; private final Map inverseCache; + + /** + * Create a new, empty Cache instance. + */ public Cache() { this.cache = Maps.newHashMap(); this.inverseCache = Maps.newHashMap(); } + /** + * @param key + * a key. + * @return {@code true} if and only if this Cache contains the specified + * key. + */ public boolean containsKey(final K key) { return cache.containsKey(key); } /** + * Get the value associated to a key. + * * @param key - * @return - * @see java.util.Map#get(java.lang.Object) + * a key. + * @return the value associated to key, or {@code null} if no such value + * exists. */ public V get(final K key) { return cache.get(key); } + /** + * Get the key associated to a value. + * + * @param value + * a value. + * @return the key associated to value, or {@code null} if no such key + * exists. + */ public K getKey(final V value) { return inverseCache.get(value); } @@ -36,7 +71,8 @@ public class Cache { * method. * * @param value - * @return a value equal to value, if such a value is present in the Cache. + * @return a value equal to value, if such a value is present in the Cache; + * {@code null} otherwise. */ public synchronized V getValue(final V value) { for (final V currentValue : inverseCache.keySet()) { @@ -48,9 +84,17 @@ public class Cache { } /** + * Add a mapping to this Cache. + * + * If either argument is {@code null}, this method silently returns. + * Otherwise, any existing mapping from the provided key to the provided + * value is removed, as well as its inverse. After that, the provided + * mapping and its inverse are added to this Cache. + * * @param key + * the key of the new mapping. * @param value - * @return + * the value to map to. * @see java.util.Map#put(java.lang.Object, java.lang.Object) */ public void put(final K key, final V value) { @@ -70,6 +114,13 @@ public class Cache { } } + /** + * Clear all the mappings in this Cache, except for any key that exists in + * the argument. + * + * @param keys + * the keys to retain. + */ public synchronized void retainAllKeys(final Collection keys) { cache.keySet().retainAll(keys); inverseCache.values().retainAll(keys); diff --git a/forge-gui/src/main/java/forge/view/CardView.java b/forge-gui/src/main/java/forge/view/CardView.java index e3cf6101650..ea4a665abfa 100644 --- a/forge-gui/src/main/java/forge/view/CardView.java +++ b/forge-gui/src/main/java/forge/view/CardView.java @@ -24,6 +24,14 @@ import forge.card.mana.ManaCost; import forge.game.card.CounterType; import forge.game.zone.ZoneType; +/** + * Representation of a {@link forge.game.card.Card}, containing only the + * information relevant to a user interface. + * + * Conversion from and to Cards happens through {@link LocalGameView}. + * + * @author elcnesh + */ public class CardView extends GameEntityView { private static final List randomInts = Lists.newArrayListWithCapacity(1000); diff --git a/forge-gui/src/main/java/forge/view/CombatView.java b/forge-gui/src/main/java/forge/view/CombatView.java index 4e311efe2d0..d8d4c6c23f0 100644 --- a/forge-gui/src/main/java/forge/view/CombatView.java +++ b/forge-gui/src/main/java/forge/view/CombatView.java @@ -9,6 +9,14 @@ import com.google.common.collect.Lists; import com.google.common.collect.Maps; import com.google.common.collect.Sets; +/** + * Representation of a {@link forge.game.combat.Combat}, containing only the + * information relevant to a user interface. + * + * Conversion from and to Combat happens through {@link LocalGameView}. + * + * @author elcnesh + */ public class CombatView { private Map attackersWithDefenders = Maps.newHashMap(); diff --git a/forge-gui/src/main/java/forge/view/GameEntityView.java b/forge-gui/src/main/java/forge/view/GameEntityView.java index 48063ca270f..e0142eb2645 100644 --- a/forge-gui/src/main/java/forge/view/GameEntityView.java +++ b/forge-gui/src/main/java/forge/view/GameEntityView.java @@ -1,5 +1,12 @@ package forge.view; +/** + * Representation of a {@link forge.game.GameEntity}. Contains no methods, but + * {@link toString} may be assumed to be overridden in subclasses to provide a + * user-friendly string representation of the object. + * + * @author elcnesh + */ public abstract class GameEntityView { } diff --git a/forge-gui/src/main/java/forge/view/IGameView.java b/forge-gui/src/main/java/forge/view/IGameView.java index dc03285d338..4a0f3127551 100644 --- a/forge-gui/src/main/java/forge/view/IGameView.java +++ b/forge-gui/src/main/java/forge/view/IGameView.java @@ -4,22 +4,29 @@ import java.util.List; import java.util.Observer; import forge.LobbyPlayer; +import forge.card.MagicColor; import forge.deck.Deck; +import forge.game.GameLog; import forge.game.GameLogEntry; import forge.game.GameLogEntryType; import forge.game.GameOutcome; import forge.game.GameType; import forge.game.phase.PhaseType; -import forge.game.player.RegisteredPlayer; +import forge.match.input.Input; +import forge.match.input.InputConfirm; import forge.util.ITriggerEvent; +/** + * Interface providing access to a game from a client. The access is assumed to + * be based on a single player. + * + * @author elcnesh + */ public interface IGameView { - public abstract boolean isCommander(); - - public abstract GameType getGameType(); - // Game-related methods + public abstract boolean isCommander(); + public abstract GameType getGameType(); public abstract int getTurnNumber(); public abstract boolean isCommandZoneNeeded(); public abstract boolean isWinner(LobbyPlayer p); @@ -44,42 +51,184 @@ public interface IGameView { public abstract void subscribeToEvents(Object subscriber); + /** + * Get the game's current combat. + * + * @return a representation of the combat, or {@code null} if there is + * currently no ongoing combat. + */ public abstract CombatView getCombat(); + /** + * Add an observer to the game log. + * + * @param o + * the {@link Observer} to be sent log updates. + * @see GameLog + */ public abstract void addLogObserver(Observer o); + + /** + * Get all log entries up to a certain level. + * + * @param maxLogLevel + * the maximum {@link GameLogEntryType} of log entries to return. + * @return a list of {@link GameLogEntry}. + * @see GameLog + * @see GameLogEntry + * @see GameLogEntryType + */ public abstract List getLogEntries(GameLogEntryType maxLogLevel); + + /** + * Get all log entries of a certain level. + * + * @param logLevel + * the {@link GameLogEntryType} of log entries to return. + * @return a list of {@link GameLogEntry}, each of which is of type + * logLevel. + * @see GameLog + * @see GameLogEntry + * @see GameLogEntryType + */ public abstract List getLogEntriesExact(GameLogEntryType logLevel); // Input controls + /** + * @return {@code true} if and only if the last action performed by this + * player can be undone. + */ public abstract boolean canUndoLastAction(); + + /** + * Try to undo the last action performed by this player. + * + * @return {@code true} if and only if the action was successfully reverted. + * @see IGameView#canUndoLastAction() + */ public abstract boolean tryUndoLastAction(); + /** + * Have this player perform the action currently associated with pressing + * the "OK" button. + */ public abstract void selectButtonOk(); + + /** + * Have this player perform the action currently associated with pressing + * the "Cancel" button. + */ public abstract void selectButtonCancel(); + + /** + * Have this player press the "OK" button if and only if the top + * {@link Input} is an instance of {@link InputConfirm}. + */ public abstract void confirm(); + + /** + * Have this player pass priority. + * @return whether priority was successfully passed. + */ public abstract boolean passPriority(); + + /** + * Have this player silently pass priority until the end of the current + * turn, unless an event occurs. + * + * @return whether priority was successfully passed. + */ public abstract boolean passPriorityUntilEndOfTurn(); + + /** + * If possible, have this player use one mana of the specified kind. + * + * @param mana + * the mana to spend. + * @see MagicColor + */ public abstract void useMana(byte mana); + + /** + * If possible, have this player select a player. + * + * @param player + * the player to select. + * @param triggerEvent + * the event used to select the player. + */ public abstract void selectPlayer(PlayerView player, ITriggerEvent triggerEvent); + + /** + * If possible, have this player select a card. + * + * @param card + * the card to select. + * @param triggerEvent + * the event used to select the card. + */ public abstract boolean selectCard(CardView card, ITriggerEvent triggerEvent); + + /** + * If possible, have this player select a spellability. + * + * @param sa + * the spellability to select. + * @param triggerEvent + * the event used to select the spellability. + */ public abstract void selectAbility(SpellAbilityView sa); + + /** + * If possible, have this player attack with as many creatures that can do + * so. + */ public abstract void alphaStrike(); - // the following method should eventually be replaced by methods returning - // View classes - @Deprecated - public abstract RegisteredPlayer getGuiRegisteredPlayer(LobbyPlayer p); - + /** + * Ask for a list containing the players involved in this game. + * + * @return a list of players. + */ public abstract List getPlayers(); + /** + * Get the player whose turn it currently is. + * + * @return the player whose turn it is, or {@code null} if it is no-one's + * turn (eg. because the current player has lost the game this + * turn). + */ public abstract PlayerView getPlayerTurn(); + /** + * @return the current phase the game is in. + */ public abstract PhaseType getPhase(); + /** + * @return a list of items currently on the stack. + */ public abstract List getStack(); + + /** + * @return the top item on the stack, or {@code null} if the stack is empty. + */ public abstract StackItemView peekStack(); + /** + * @param c + * a card. + * @return whether this player may view the specified card. + */ public abstract boolean mayShowCard(CardView c); + + /** + * @param c + * a card. + * @return whether this player may view the front card face of the specified + * card. + */ public abstract boolean mayShowCardFace(CardView c); // Auto-yield related methods @@ -97,6 +246,10 @@ public interface IGameView { public abstract void setShouldAlwaysDeclineTrigger(Integer trigger); public abstract void setShouldAlwaysAskTrigger(Integer trigger); + /** + * Request cancellation of a previous request to pass priority + * automatically. + */ public abstract void autoPassCancel(); public abstract void devTogglePlayManyLands(boolean b); diff --git a/forge-gui/src/main/java/forge/view/LocalGameView.java b/forge-gui/src/main/java/forge/view/LocalGameView.java index 767ffef456c..302ddc4f588 100644 --- a/forge-gui/src/main/java/forge/view/LocalGameView.java +++ b/forge-gui/src/main/java/forge/view/LocalGameView.java @@ -200,19 +200,6 @@ public abstract class LocalGameView implements IGameView { return game.getGameLog().getLogEntriesExact(logLevel); } - /* (non-Javadoc) - * @see forge.view.IGameView#getGuiRegisteredPlayer(forge.LobbyPlayer) - */ - @Override - public RegisteredPlayer getGuiRegisteredPlayer(final LobbyPlayer p) { - for (final RegisteredPlayer player : game.getMatch().getPlayers()) { - if (player.getPlayer() == p) { - return player; - } - } - return null; - } - /* (non-Javadoc) * @see forge.view.IGameView#getRegisteredPlayers() */ diff --git a/forge-gui/src/main/java/forge/view/PlayerView.java b/forge-gui/src/main/java/forge/view/PlayerView.java index b0964f83865..cbe6b3c4bc1 100644 --- a/forge-gui/src/main/java/forge/view/PlayerView.java +++ b/forge-gui/src/main/java/forge/view/PlayerView.java @@ -13,6 +13,14 @@ import forge.LobbyPlayer; import forge.card.MagicColor; import forge.game.zone.ZoneType; +/** + * Representation of a {@link forge.game.player.Player}, containing only the + * information relevant to a user interface. + * + * Conversion from and to Players happens through {@link LocalGameView}. + * + * @author elcnesh + */ public class PlayerView extends GameEntityView { private final LobbyPlayer lobbyPlayer; diff --git a/forge-gui/src/main/java/forge/view/SpellAbilityView.java b/forge-gui/src/main/java/forge/view/SpellAbilityView.java index 6d7a0c687e1..1d2d329df8e 100644 --- a/forge-gui/src/main/java/forge/view/SpellAbilityView.java +++ b/forge-gui/src/main/java/forge/view/SpellAbilityView.java @@ -1,5 +1,13 @@ package forge.view; +/** + * Representation of a {@link forge.game.spellability.SpellAbility}, containing + * only the information relevant to a user interface. + * + * Conversion from and to SpellAbilities happens through {@link LocalGameView}. + * + * @author elcnesh + */ public class SpellAbilityView { private CardView hostCard; diff --git a/forge-gui/src/main/java/forge/view/StackItemView.java b/forge-gui/src/main/java/forge/view/StackItemView.java index 32047188c3e..405e3b2e67e 100644 --- a/forge-gui/src/main/java/forge/view/StackItemView.java +++ b/forge-gui/src/main/java/forge/view/StackItemView.java @@ -1,5 +1,14 @@ package forge.view; +/** + * Representation of a {@link forge.game.spellability.SpellAbilityStackInstance} + * , containing only the information relevant to a user interface. + * + * Conversion from and to SpellAbilityStackInstances happens through + * {@link LocalGameView}. + * + * @author elcnesh + */ public class StackItemView { private final String key; diff --git a/forge-gui/src/main/java/forge/view/ViewUtil.java b/forge-gui/src/main/java/forge/view/ViewUtil.java index 4fdee06dba9..877af946463 100644 --- a/forge-gui/src/main/java/forge/view/ViewUtil.java +++ b/forge-gui/src/main/java/forge/view/ViewUtil.java @@ -14,6 +14,11 @@ import forge.game.card.CardCharacteristics; import forge.item.IPaperCard; import forge.view.CardView.CardStateView; +/** + * Static class providing utility methods to the view classes. + * + * @author elcnesh + */ public final class ViewUtil { private ViewUtil() {