Javadocs.

This commit is contained in:
maurer.it 2011-06-11 21:53:17 -04:00
parent f5b08fcaed
commit 2384d8e5a2

View file

@ -37,26 +37,198 @@ import mage.abilities.keyword.ProtectionAbility;
import mage.abilities.mana.ManaAbility;
import mage.filter.FilterAbility;
/**
* Represents a collection of {@link Ability Abilities}. This is the top most
* interface for this.
*
* @param <T> The ability type this collection will hold.
*
* @see mage.abilities.AbilitiesImpl
* @see mage.abilities.DelayedTriggeredAbilities
* @see mage.abilities.SpecialActions
* @see mage.abilities.TriggeredAbilities
*/
public interface Abilities<T extends Ability> extends List<T>, Serializable {
/**
* Retrieves a {@link List}&lt;{@link String}&gt; of ability texts for the
* given source.
*
* @param source The source to retrieve ability texts.
* @return the {@link List}&lt;{@link String}&gt; of ability texts.
*
* @see mage.cards.CardImpl#getRules()
* @see mage.abilities.keyword.LevelAbility#getRule()
*/
public List<String> getRules(String source);
/**
* Retrieves all activated abilities for the given {@link Zone}.
*
* @param zone The {@link Zone} for which abilities should be retrieved.
* @return All abilities for the given {@link Zone}
*
* @see mage.cards.CardImpl#getSpellAbility()
*/
public Abilities<ActivatedAbility> getActivatedAbilities(Zone zone);
/**
* Retrieves all activated abilities for the given {@link Zone} that match
* the given {@link FilterAbility}.
*
* @param zone The {@link Zone} for which abilities should be retrieved.
* @param filter The {@link FilterAbility} to apply to the result.
* @return The {@link ActivatedAbility activated abilities} matching the {@link Zone} and {@link FilterAbility}.
*
* @see mage.players.PlayerImpl#getPlayable(mage.game.Game, mage.filter.FilterAbility, mage.abilities.mana.ManaOptions, boolean)
*/
public Abilities<ActivatedAbility> getActivatedAbilities(Zone zone, FilterAbility filter);
/**
* Retrieves all {@link ManaAbility mana abilities} in the given {@link Zone}.
*
* @param zone The {@link Zone} to search for {@link ManaAbility mana abilities}.
* @return All {@link ManaAbility mana abilities} for the given {@link Zone}.
*
* @see mage.cards.CardImpl#getMana()
* @see mage.players.PlayerImpl#getManaAvailable(mage.game.Game)
* @see mage.players.PlayerImpl#getAvailableManaProducers(mage.game.Game)
*/
public Abilities<ManaAbility> getManaAbilities(Zone zone);
/**
* Retrieves all {@link StaticAbility static abilities} in the given {@link Zone}.
*
* @param zone The {@link Zone} to search for {@link StaticAbility}
* @return All {@link StaticAbility static abilities} in the given {@link Zone}
*
* @see mage.abilities.effects.ContinuousEffects#getLayeredEffects(mage.game.Game)
* @see mage.abilities.effects.ContinuousEffects#getApplicableRequirementEffects(mage.game.permanent.Permanent, mage.game.Game)
* @see mage.abilities.effects.ContinuousEffects#getApplicableRestrictionEffects(mage.game.permanent.Permanent, mage.game.Game)
* @see mage.abilities.effects.ContinuousEffects#getApplicableReplacementEffects(mage.game.events.GameEvent, mage.game.Game)
* @see mage.abilities.effects.ContinuousEffects#asThough(java.util.UUID, mage.Constants.AsThoughEffectType, mage.game.Game)
* @see mage.abilities.effects.ContinuousEffects#costModification(mage.abilities.Ability, mage.game.Game)
*/
public Abilities<StaticAbility> getStaticAbilities(Zone zone);
/**
* Retrieves all {@link EvasionAbility evasion abilities}.
*
* @return The {@link EvasionAbility evasion abilities}.
*/
public Abilities<EvasionAbility> getEvasionAbilities();
/**
* Retrieves all {@link TriggeredAbility triggered abilities} for the given
* {@link Zone}.
*
* @param zone The {@link Zone} to search for {@link TriggeredAbility triggered abilities}
* @return All found {@link TriggeredAbility triggered abilities}.
*
* @see mage.cards.CardImpl#checkTriggers(mage.Constants.Zone, mage.game.events.GameEvent, mage.game.Game)
* @see mage.game.permanent.PermanentImpl#checkTriggers(mage.game.events.GameEvent, mage.game.Game)
* @see mage.game.permanent.PermanentCard#checkPermanentOnlyTriggers(mage.game.events.ZoneChangeEvent, mage.game.Game)
*/
public Abilities<TriggeredAbility> getTriggeredAbilities(Zone zone);
/**
* Retrieves all {@link ProtectionAbility protection abilities}.
*
* @return All found {@link ProtectionAbility protection abilities}.
*
* @see mage.game.permanent.PermanentImpl#hasProtectionFrom(mage.MageObject)
* @see mage.players.PlayerImpl#hasProtectionFrom(mage.MageObject)
* @see mage.players.PlayerImpl#canDamage(mage.MageObject)
*/
public Abilities<ProtectionAbility> getProtectionAbilities();
/**
* Retrieves all {@link KickerAbility kicker abilities}.
*
* @return All found {@link KickerAbility kicker abilities}.
*
* @see mage.players.PlayerImpl#cast(mage.abilities.SpellAbility, mage.game.Game, boolean)
* @see mage.game.stack.Spell#resolveKicker(mage.game.Game)
*/
public Abilities<KickerAbility> getKickerAbilities();
/**
* TODO Method is unused, keep it around?
*
* The only implementation seems to want to use this for totally a set of
* abilities by some arbitrary numeral value. Possibly a good method to be
* used by the AI's?
*
* @return A numeral value representing the 'strength' or effectiveness of the abilities?
*/
public int getOutcomeTotal();
/**
* Sets the controller of this set of abilities.
*
* @param controllerId
*
* @see mage.cards.CardImpl#setControllerId(java.util.UUID)
* @see mage.cards.CardImpl#setOwnerId(java.util.UUID)
* @see mage.game.permanent.PermanentImpl#changeControllerId(java.util.UUID, mage.game.Game)
* @see mage.game.permanent.PermanentCard#copyFromCard(mage.cards.Card)
*/
public void setControllerId(UUID controllerId);
/**
* Sets the source of this set of abilities.
*
* @param sourceId
*
* @see mage.cards.CardImpl#assignNewId()
*/
public void setSourceId(UUID sourceId);
/**
* Searches this set of abilities to see if the ability represented by the abilityId
* is contained within. Can be used to find usages of singleton abilities.
*
* @param abilityId
* @return
*/
public boolean containsKey(UUID abilityId);
/**
* TODO Method is unused, keep it around?
*
* Gets the ability represented by the given abilityId.
*
* @param abilityId
* @return
*/
public T get(UUID abilityId);
/**
* TODO The usage of this method seems redundant to that of {@link #containsKey(java.util.UUID)}
* minus the fact that it searches for exact instances instead of id's of
* singleton Abilities.
*
* Searches for the exact instance of the passed in ability.
*
* @param ability
* @return
*/
public boolean contains(T ability);
/**
* Searches this set of abilities for the existence of each of the passed in
* set of abilities.
*
* @param abilities
* @return True if the passed in set of abilities is also in this set of abilities.
*/
public boolean containsAll(Abilities<T> abilities);
/**
* Copies this set of abilities. This copy should be new instances of all
* the contained abilities.
*
* @return
*/
public Abilities<T> copy();
}