From b22036c0417ee7bd040085538dc0f815edb8921f Mon Sep 17 00:00:00 2001 From: poixen Date: Sat, 28 Nov 2015 11:57:46 +0100 Subject: [PATCH] added javadoc and final modifiers --- Mage/src/mage/Mana.java | 411 +++++++++++++++++++++++++++++++++++----- 1 file changed, 365 insertions(+), 46 deletions(-) diff --git a/Mage/src/mage/Mana.java b/Mage/src/mage/Mana.java index 6738f17665..cde03cc10c 100644 --- a/Mage/src/mage/Mana.java +++ b/Mage/src/mage/Mana.java @@ -32,21 +32,21 @@ import java.util.Objects; import mage.constants.ColoredManaSymbol; import mage.constants.ManaType; + import static mage.constants.ManaType.COLORLESS; + import mage.filter.FilterMana; import mage.util.Copyable; import mage.util.ThreadLocalStringBuilder; import org.apache.log4j.Logger; /** - * * @author BetaSteward_at_googlemail.com */ public class Mana implements Comparable, Serializable, Copyable { private static final transient Logger logger = Logger.getLogger(Mana.class); - protected int red; protected int green; protected int blue; @@ -54,8 +54,9 @@ public class Mana implements Comparable, Serializable, Copyable { protected int black; protected int colorless; protected int any; - protected boolean flag = false; + protected boolean flag; + //TODO These are unsafe and mutable public static final Mana RedMana = RedMana(1); public static final Mana GreenMana = GreenMana(1); public static final Mana BlueMana = BlueMana(1); @@ -63,9 +64,43 @@ public class Mana implements Comparable, Serializable, Copyable { public static final Mana BlackMana = BlackMana(1); public static final Mana ColorlessMana = ColorlessMana(1); + + /** + * Default constructor. Creates a {@link Mana} object with 0 values. + */ public Mana() { } + + /** + * Creates a {@link Mana} object with the passed in values. Values can + * not be less than 0. Any values less than 0 will be logged and set to 0. + * + * @param red total Red mana to have. + * @param green total Green mana to have. + * @param blue total Blue mana to have. + * @param white total White mana to have. + * @param black total Black mana to have. + * @param colorless total Colorless mana to have. + * @param any total Any mana to have. + */ + public Mana(final int red, final int green, final int blue, final int white, + final int black, final int colorless, final int any) { + this.red = notNegative(red, "Red"); + this.green = notNegative(green, "Green"); + this.blue = notNegative(blue, "Blue"); + this.white = notNegative(white, "White"); + this.black = notNegative(black, "Black"); + this.colorless = notNegative(colorless, "Colorless"); + this.any = notNegative(any, "Any"); + } + + + /** + * Copy constructor. Creates a {@link Mana} object from existing {@link Mana} + * + * @param mana object to create copy from + */ public Mana(final Mana mana) { Objects.requireNonNull(mana, "The passed in mana can not be null"); this.red = mana.red; @@ -78,6 +113,13 @@ public class Mana implements Comparable, Serializable, Copyable { this.flag = mana.flag; } + + /** + * Creates {@link Mana} object from {@link ColoredManaSymbol}. + * Created {@link Mana} will have a single mana of the passed in {@link ColoredManaSymbol} color. + * + * @param color The color to create the {@link Mana} object with. + */ public Mana(final ColoredManaSymbol color) { Objects.requireNonNull(color, "The passed in ColoredManaSymbol can not be null"); switch (color) { @@ -96,44 +138,96 @@ public class Mana implements Comparable, Serializable, Copyable { case W: white = 1; break; + default: + throw new IllegalArgumentException("Unknown mana color: " + color); } } + + /** + * Creates a {@link Mana} object with the passed in {@code num} of Red mana. + * {@code num} can not be a negative value. Negative values will be logged + * and set to 0. + * + * @param num value of Red mana to create. + * @return a {@link Mana} object with the passed in {@code num} of Red mana. + */ public static Mana RedMana(int num) { return new Mana(notNegative(num, "Red"), 0, 0, 0, 0, 0, 0); } + + /** + * Creates a {@link Mana} object with the passed in {@code num} of Green mana. + * {@code num} can not be a negative value. Negative values will be logged + * and set to 0. + * + * @param num value of Green mana to create. + * @return a {@link Mana} object with the passed in {@code num} of Green mana. + */ public static Mana GreenMana(int num) { return new Mana(0, notNegative(num, "Green"), 0, 0, 0, 0, 0); } + + /** + * Creates a {@link Mana} object with the passed in {@code num} of Blue mana. + * {@code num} can not be a negative value. Negative values will be logged + * and set to 0. + * + * @param num value of Blue mana to create. + * @return a {@link Mana} object with the passed in {@code num} of Blue mana. + */ public static Mana BlueMana(int num) { return new Mana(0, 0, notNegative(num, "Blue"), 0, 0, 0, 0); } + + /** + * Creates a {@link Mana} object with the passed in {@code num} of White mana. + * {@code num} can not be a negative value. Negative values will be logged + * and set to 0. + * + * @param num value of White mana to create. + * @return a {@link Mana} object with the passed in {@code num} of White mana. + */ public static Mana WhiteMana(int num) { return new Mana(0, 0, 0, notNegative(num, "White"), 0, 0, 0); } + + /** + * Creates a {@link Mana} object with the passed in {@code num} of Black mana. + * {@code num} can not be a negative value. Negative values will be logged + * and set to 0. + * + * @param num value of Black mana to create. + * @return a {@link Mana} object with the passed in {@code num} of Black mana. + */ public static Mana BlackMana(int num) { return new Mana(0, 0, 0, 0, notNegative(num, "Black"), 0, 0); } + + /** + * Creates a {@link Mana} object with the passed in {@code num} of Colorless mana. + * {@code num} can not be a negative value. Negative values will be logged + * and set to 0. + * + * @param num value of Colorless mana to create. + * @return a {@link Mana} object with the passed in {@code num} of Colorless mana. + */ public static Mana ColorlessMana(int num) { return new Mana(0, 0, 0, 0, 0, notNegative(num, "Colorless"), 0); } - public Mana(int red, int green, int blue, int white, int black, int colorless, int any) { - this.red = notNegative(red, "Red"); - this.green = notNegative(green, "Green"); - this.blue = notNegative(blue, "Blue"); - this.white = notNegative(white, "White"); - this.black = notNegative(black, "Black"); - this.colorless = notNegative(colorless, "Colorless"); - this.any = notNegative(any, "Any"); - } - public void add(Mana mana) { + /** + * Adds mana from the passed in {@link Mana} object to this object. + * + * @param mana mana to add to this object. + */ + public void add(final Mana mana) { red += mana.getRed(); green += mana.getGreen(); blue += mana.getBlue(); @@ -143,37 +237,61 @@ public class Mana implements Comparable, Serializable, Copyable { any += mana.getAny(); } + + /** + * Increases the Red mana by one. + */ public void increaseRed() { red++; } + + /** + * Increases the Green mana by one. + */ public void increaseGreen() { green++; } + + /** + * Increases the Blue mana by one. + */ public void increaseBlue() { blue++; } + + /** + * Increases the White mana by one. + */ public void increaseWhite() { white++; } + + /** + * Increases the Black mana by one. + */ public void increaseBlack() { black++; } + + /** + * Increases the Colorless mana by one. + */ public void increaseColorless() { colorless++; } + /** - * Subtracts the passed in mana values from this instance. Will not - * reduce this instances mana below 0. + * Subtracts the passed in mana values from this instance. * * @param mana mana values to subtract */ - public void subtract(final Mana mana) throws ArithmeticException { + public void subtract(final Mana mana) { red -= mana.red; green -= mana.green; blue -= mana.blue; @@ -185,14 +303,13 @@ public class Mana implements Comparable, Serializable, Copyable { /** - * Subtracts the passed in mana values from this instance. Will not - * reduce this instances mana below 0. The difference between this and - * {@code subtract()} is that if we do not have the available colorlesss + * Subtracts the passed in mana values from this instance. The difference between this and + * {@code subtract()} is that if we do not have the available colorless * mana to pay, we take mana from our colored mana pools. * * @param mana mana values to subtract * @throws ArithmeticException thrown if there is not enough available - * colored mana to make up the negative colorless cost + * colored mana to pay the colorless cost */ public void subtractCost(final Mana mana) throws ArithmeticException { red -= mana.red; @@ -239,15 +356,35 @@ public class Mana implements Comparable, Serializable, Copyable { } } + + /** + * Returns the total count of all combined mana. + * + * @return the total count of all combined mana. + */ public int count() { return red + green + blue + white + black + colorless + any; } + + /** + * Returns the total count of all colored mana. + * + * @return the total count of all colored mana. + */ public int countColored() { return red + green + blue + white + black + any; } - public int count(FilterMana filter) { + + /** + * Returns the count of filtered mana provided by the passed in {@link FilterMana}. + * If {@link FilterMana} is null, the total mana count is returned via {@link #count() count}. + * + * @param filter the colors of mana to return the count for. + * @return the count of filtered mana provided by the passed in {@link FilterMana}. + */ + public int count(final FilterMana filter) { if (filter == null) { return count(); } @@ -273,6 +410,10 @@ public class Mana implements Comparable, Serializable, Copyable { return count; } + + /** + * Sets all mana to 0. + */ public void clear() { red = 0; green = 0; @@ -283,6 +424,12 @@ public class Mana implements Comparable, Serializable, Copyable { any = 0; } + + /** + * Returns this objects values as a {@link String}. + * + * @return this objects values as a {@link String}. + */ @Override public String toString() { StringBuilder sbMana = new StringBuilder(); @@ -310,22 +457,34 @@ public class Mana implements Comparable, Serializable, Copyable { return sbMana.toString(); } - private static final transient ThreadLocalStringBuilder threadLocalBuilder = new ThreadLocalStringBuilder(10); + /** + * Returns a deep copy of this object. + * + * @return a deep copy of this object. + */ @Override public Mana copy() { return new Mana(this); } - public boolean enough(Mana avail) { - Mana compare = avail.copy(); + + /** + * Returns if there is enough available mana to pay the mana provided by the + * passed in {@link Mana} object. + * + * @param cost the cost to compare too. + * @return if there is enough available mana to pay. + */ + public boolean enough(final Mana cost) { + Mana compare = cost.copy(); compare.subtract(this); if (compare.red < 0) { compare.any = compare.getAny() + compare.getRed(); if (compare.any < 0) { return false; } - compare.red =0; + compare.red = 0; } if (compare.green < 0) { compare.any = compare.getAny() + compare.getGreen(); @@ -364,8 +523,15 @@ public class Mana implements Comparable, Serializable, Copyable { return true; } - public Mana needed(Mana avail) { - Mana compare = avail.copy(); + + /** + * Returns the total mana needed to meet the passed in {@link Mana} object. + * + * @param cost the mana cost + * @return the total mana needed to meet the passes in {@link Mana} object. + */ + public Mana needed(final Mana cost) { + Mana compare = cost.copy(); compare.subtract(this); if (compare.red < 0 && compare.any > 0) { int diff = Math.min(compare.any, Math.abs(compare.red)); @@ -427,73 +593,173 @@ public class Mana implements Comparable, Serializable, Copyable { return needed; } + + /** + * Returns total Red mana. + * + * @return total Red mana. + */ public int getRed() { return red; } + + /** + * Sets the total Red mana. Can not be negative. + * Negative values will be logged and set to 0. + * + * @param red total Red mana. + */ public void setRed(int red) { this.red = notNegative(red, "Red"); } + + /** + * Returns total Green mana. + * + * @return total Green mana. + */ public int getGreen() { return green; } + + /** + * Sets the total Green mana. Can not be negative. + * Negative values will be logged and set to 0. + * + * @param green total Green mana. + */ public void setGreen(int green) { this.green = notNegative(green, "Green"); } + + /** + * Returns total Blue mana. + * + * @return total Blue mana. + */ public int getBlue() { return blue; } + + /** + * Sets the total Blue mana. Can not be negative. + * Negative values will be logged and set to 0. + * + * @param blue total Blue mana. + */ public void setBlue(int blue) { this.blue = notNegative(blue, "Blue"); } + + /** + * Returns total White mana. + * + * @return total White mana. + */ public int getWhite() { return white; } + + /** + * Sets the total White mana. Can not be negative. + * Negative values will be logged and set to 0. + * + * @param white total White mana. + */ public void setWhite(int white) { this.white = notNegative(white, "White"); } + + /** + * Returns total Black mana. + * + * @return total Black mana. + */ public int getBlack() { return black; } + + /** + * Sets the total Black mana. Can not be negative. + * Negative values will be logged and set to 0. + * + * @param black total Black mana. + */ public void setBlack(int black) { this.black = notNegative(black, "Black"); } + + /** + * Returns total Colorless mana. + * + * @return total Colorless mana. + */ public int getColorless() { return colorless; } + + /** + * Sets the total Colorless mana. Can not be negative. + * Negative values will be logged and set to 0. + * + * @param colorless total Colorless mana. + */ public void setColorless(int colorless) { this.colorless = notNegative(colorless, "Colorless"); } + + /** + * Returns total Any mana. + * + * @return total Any mana. + */ public int getAny() { return any; } + + /** + * Sets the total Any mana. Can not be negative. + * Negative values will be logged and set to 0. + * + * @param any total Any mana. + */ public void setAny(int any) { this.any = notNegative(any, "Any"); } + + /** + * Returns this objects total mana minus the passed in {@link Mana}'s mana. + * + * @param o the object to compare to. + * @return this objects total mana minus the passed in {@link Mana}'s mana. + */ @Override - public int compareTo(Mana o) { + public int compareTo(final Mana o) { return this.count() - o.count(); } + /** + * Returns if this objects mana contains any number of the passed in {@link Mana}'s mana. * - * @param mana + * @param mana the mana to check for * @return true if this contains any values that mana has */ - public boolean contains(Mana mana) { + public boolean contains(final Mana mana) { if (mana.black > 0 && this.black > 0) { return true; } @@ -516,26 +782,40 @@ public class Mana implements Comparable, Serializable, Copyable { return false; } - public int getColor(ColoredManaSymbol color) { + + /** + * Returns the total count of mana in this object as specified by the passed in {@link ColoredManaSymbol}. + * + * @param color the color to return the count for. + * @return the total count of mana in this object as specified by the passed in {@link ColoredManaSymbol}. + */ + public int getColor(final ColoredManaSymbol color) { if (color.equals(ColoredManaSymbol.G)) { - return getGreen(); + return green; } if (color.equals(ColoredManaSymbol.R)) { - return getRed(); + return red; } if (color.equals(ColoredManaSymbol.B)) { - return getBlack(); + return black; } if (color.equals(ColoredManaSymbol.U)) { - return getBlue(); + return blue; } if (color.equals(ColoredManaSymbol.W)) { - return getWhite(); + return white; } return 0; } - public int get(ManaType manaType) { + + /** + * Returns the total count of mana in this object as specified by the passed in {@link ManaType}. + * + * @param manaType the type to return the count for. + * @return the total count of mana in this object as specified by the passed in {@link ManaType}. + */ + public int get(final ManaType manaType) { switch (manaType) { case BLACK: return black; @@ -553,7 +833,14 @@ public class Mana implements Comparable, Serializable, Copyable { return 0; } - public void set(ManaType manaType, int amount) { + + /** + * Set the color of mana specified by the passed in {@link ManaType} to {@code amount} . + * + * @param manaType the color of the mana to set + * @param amount the value to set the mana too + */ + public void set(final ManaType manaType, final int amount) { switch (manaType) { case BLACK: black = amount; @@ -573,9 +860,12 @@ public class Mana implements Comparable, Serializable, Copyable { case COLORLESS: colorless = amount; break; + default: + throw new IllegalArgumentException("Unknown color: " + manaType); } } + public void setFlag(boolean flag) { this.flag = flag; } @@ -584,7 +874,13 @@ public class Mana implements Comparable, Serializable, Copyable { return flag; } - public void setToMana(Mana mana) { + + /** + * Sets this objects mana to that of the passed in {@link Mana} + * + * @param mana the mana to set this object to. + */ + public void setToMana(final Mana mana) { this.any = mana.any; this.red = mana.red; this.green = mana.green; @@ -594,7 +890,14 @@ public class Mana implements Comparable, Serializable, Copyable { this.colorless = mana.colorless; } - public boolean equalManaValue(Mana mana) { + + /** + * Returns if the passed in {@link Mana} values are equal to this objects. + * + * @param mana the {@link Mana} to compare to. + * @return if the passed in {@link Mana} values are equal to this object. + */ + public boolean equalManaValue(final Mana mana) { return this.any == mana.any && this.red == mana.red && this.green == mana.green @@ -604,12 +907,13 @@ public class Mana implements Comparable, Serializable, Copyable { && this.colorless == mana.colorless; } + /** - * Don't takes any mana into account to be usable in calculating available - * mana + * Returns if this {@link Mana} object has more than or equal values of mana + * as the passed in {@link Mana} object. * - * @param mana - * @return + * @param mana the mana to compare with + * @return if this object has more than or equal mana to the passed in {@link Mana}. */ public boolean includesMana(Mana mana) { return this.green >= mana.green @@ -622,6 +926,7 @@ public class Mana implements Comparable, Serializable, Copyable { } + /** * Returns the mana that is more colored or has a greater amount but does * not contain one less mana in any color but colorless if you call with @@ -633,7 +938,7 @@ public class Mana implements Comparable, Serializable, Copyable { * @param mana2 * @return */ - public static Mana getMoreValuableMana(Mana mana1, Mana mana2) { + public static Mana getMoreValuableMana(final Mana mana1, final Mana mana2) { Mana moreMana; Mana lessMana; if (mana2.countColored() > mana1.countColored() || mana2.getAny() > mana1.getAny() || mana2.count() > mana1.count()) { @@ -654,6 +959,12 @@ public class Mana implements Comparable, Serializable, Copyable { return moreMana; } + + /** + * Returns the total count of mana colors that have at least one. + * + * @return the total count of mana colors that have at least one. + */ public int getDifferentColors() { int count = 0; if (blue > 0) { @@ -706,12 +1017,20 @@ public class Mana implements Comparable, Serializable, Copyable { return result; } + /** + * Checks that the {@code value} passed in is not less than 0. + * If the value is negative, it is logged and 0 is returned. + * + * @param value the value to check. + * @param name the name of the value to check. Used to make logging of + * the {@code value} easier + * @return the {@code value} passed in, unless it is minus, in which case 0 is returned. + */ private static int notNegative(int value, final String name) { if (value < 0) { logger.info(name + " can not be less than 0. Passed in: " + value + " Defaulting to 0."); value = 0; } - return value; } }