Merge pull request #1392 from poixen/mana

Final mana cleanup

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<Mana>, Serializable, Copyable<Mana> {
 
     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<Mana>, Serializable, Copyable<Mana> {
     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<Mana>, Serializable, Copyable<Mana> {
     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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
             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<Mana>, Serializable, Copyable<Mana> {
         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
+     * Subtracts the passed in mana values from this instance.
-     * reduce this instances mana below 0.
      *
      * @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<Mana>, Serializable, Copyable<Mana> {
 
 
     /**
-     * Subtracts the passed in mana values from this instance. Will not
+     * Subtracts the passed in mana values from this instance. The difference between this and
-     * reduce this instances mana below 0. The difference between this and
+     * {@code subtract()} is that if we do not have the available colorless
-     * {@code subtract()} is that if we do not have the available colorlesss
      * 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<Mana>, Serializable, Copyable<Mana> {
         }
     }
 
+
+    /**
+     * 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<Mana>, Serializable, Copyable<Mana> {
         return count;
     }
 
+
+    /**
+     * Sets all mana to 0.
+     */
     public void clear() {
         red = 0;
         green = 0;
@@ -283,6 +424,12 @@ public class Mana implements Comparable<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
             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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
                 && this.colorless == mana.colorless;
     }
 
+
     /**
-     * Don't takes any mana into account to be usable in calculating available
+     * Returns if this {@link Mana} object has more than or equal values of mana
-     * mana
+     * as the passed in {@link Mana} object.
      *
-     * @param mana
+     * @param mana the mana to compare with
-     * @return
+     * @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<Mana>, Serializable, Copyable<Mana> {
 
     }
 
+
     /**
      * 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<Mana>, Serializable, Copyable<Mana> {
      * @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<Mana>, Serializable, Copyable<Mana> {
         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<Mana>, Serializable, Copyable<Mana> {
         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;
     }
 }