Added missing throws declarations and fixed javadoc to match what is actually thrown. JIRA: MATH-854.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1385386 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math3/stat/descriptive/DescriptiveStatistics.java

@@ -175,9 +175,15 @@ public class DescriptiveStatistics implements StatisticalSummary, Serializable {
 
     /**
      * Removes the most recent value from the dataset.
+     *
+     * @throws MathIllegalStateException if there are no elements stored
      */
-    public void removeMostRecentValue() {
+    public void removeMostRecentValue() throws MathIllegalStateException {
-        eDA.discardMostRecentElements(1);
+        try {
+            eDA.discardMostRecentElements(1);
+        } catch (MathIllegalArgumentException ex) {
+            throw new MathIllegalStateException(LocalizedFormats.NO_DATA);
+        }
     }
 
     /**
@@ -186,8 +192,9 @@ public class DescriptiveStatistics implements StatisticalSummary, Serializable {
      *
      * @param v the value to replace the most recent stored value
      * @return replaced value
+     * @throws MathIllegalStateException if there are no elements stored
      */
-    public double replaceMostRecentValue(double v) {
+    public double replaceMostRecentValue(double v) throws MathIllegalStateException {
         return eDA.substituteMostRecentElement(v);
     }
 
@@ -407,7 +414,7 @@ public class DescriptiveStatistics implements StatisticalSummary, Serializable {
      * </p><p>
      * <strong>Preconditions</strong>:<ul>
      * <li><code>0 &lt; p &le; 100</code> (otherwise an
-     * <code>IllegalArgumentException</code> is thrown)</li>
+     * <code>MathIllegalArgumentException</code> is thrown)</li>
      * <li>at least one value must be stored (returns <code>Double.NaN
      *     </code> otherwise)</li>
      * </ul></p>
@@ -416,8 +423,9 @@ public class DescriptiveStatistics implements StatisticalSummary, Serializable {
      * @return An estimate for the pth percentile of the stored data
      * @throws MathIllegalStateException if percentile implementation has been
      *  overridden and the supplied implementation does not support setQuantile
+     * @throws MathIllegalArgumentException if p is not a valid quantile
      */
-    public double getPercentile(double p) throws MathIllegalStateException {
+    public double getPercentile(double p) throws MathIllegalStateException, MathIllegalArgumentException {
         if (percentileImpl instanceof Percentile) {
             ((Percentile) percentileImpl).setQuantile(p);
         } else {
@@ -459,6 +467,7 @@ public class DescriptiveStatistics implements StatisticalSummary, Serializable {
         outBuffer.append("std dev: ").append(getStandardDeviation())
             .append(endl);
         try {
+            // No catch for MIAE because actual parameter is valid below
             outBuffer.append("median: ").append(getPercentile(50)).append(endl);
         } catch (MathIllegalStateException ex) {
             outBuffer.append("median: unavailable").append(endl);

src/main/java/org/apache/commons/math3/stat/descriptive/moment/SemiVariance.java

@@ -213,14 +213,15 @@ public class SemiVariance extends AbstractUnivariateStatistic implements Seriali
        * instance properties variancDirection and biasCorrection.</p>
        *
        * <p>Returns <code>NaN</code> if the array is empty and throws
-       * <code>IllegalArgumentException</code> if the array is null.</p>
+       * <code>MathIllegalArgumentException</code> if the array is null.</p>
        *
        * @param values the input array
        * @param cutoff the reference point
        * @return the SemiVariance
-       * @throws IllegalArgumentException if values is null
+       * @throws MathIllegalArgumentException if values is null
        */
-      public double evaluate(final double[] values, final double cutoff) {
+      public double evaluate(final double[] values, final double cutoff)
+      throws MathIllegalArgumentException {
           return evaluate(values, cutoff, varianceDirection, biasCorrected, 0, values.length);
       }
 
@@ -229,15 +230,16 @@ public class SemiVariance extends AbstractUnivariateStatistic implements Seriali
        * given direction, using the current value of the biasCorrection instance property.</p>
        *
        * <p>Returns <code>NaN</code> if the array is empty and throws
-       * <code>IllegalArgumentException</code> if the array is null.</p>
+       * <code>MathIllegalArgumentException</code> if the array is null.</p>
        *
        * @param values the input array
        * @param cutoff the reference point
        * @param direction the {@link Direction} of the semivariance
        * @return the SemiVariance
-       * @throws IllegalArgumentException if values is null
+       * @throws MathIllegalArgumentException if values is null
        */
-      public double evaluate(final double[] values, final double cutoff, final Direction direction) {
+      public double evaluate(final double[] values, final double cutoff, final Direction direction)
+      throws MathIllegalArgumentException {
           return evaluate(values, cutoff, direction, biasCorrected, 0, values.length);
       }
 

src/main/java/org/apache/commons/math3/stat/descriptive/moment/StandardDeviation.java

@@ -72,8 +72,9 @@ public class StandardDeviation extends AbstractStorelessUnivariateStatistic
      * to the {@code original}
      *
      * @param original the {@code StandardDeviation} instance to copy
+     * @throws NullArgumentException if original is null
      */
-    public StandardDeviation(StandardDeviation original) {
+    public StandardDeviation(StandardDeviation original) throws NullArgumentException {
         copy(original, this);
     }
 

src/main/java/org/apache/commons/math3/stat/descriptive/summary/Product.java

@@ -18,6 +18,7 @@ package org.apache.commons.math3.stat.descriptive.summary;
 
 import java.io.Serializable;
 
+import org.apache.commons.math3.exception.MathIllegalArgumentException;
 import org.apache.commons.math3.exception.NullArgumentException;
 import org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic;
 import org.apache.commons.math3.stat.descriptive.WeightedEvaluation;
@@ -64,8 +65,9 @@ public class Product extends AbstractStorelessUnivariateStatistic implements Ser
      * to the {@code original}
      *
      * @param original the {@code Product} instance to copy
+     * @throws NullArgumentException  if original is null
      */
-    public Product(Product original) {
+    public Product(Product original) throws NullArgumentException {
         copy(original, this);
     }
 
@@ -107,17 +109,18 @@ public class Product extends AbstractStorelessUnivariateStatistic implements Ser
      * the input array, or <code>Double.NaN</code> if the designated subarray
      * is empty.
      * <p>
-     * Throws <code>IllegalArgumentException</code> if the array is null.</p>
+     * Throws <code>MathIllegalArgumentException</code> if the array is null.</p>
      *
      * @param values the input array
      * @param begin index of the first array element to include
      * @param length the number of elements to include
      * @return the product of the values or 1 if length = 0
-     * @throws IllegalArgumentException if the array is null or the array index
+     * @throws MathIllegalArgumentException if the array is null or the array index
      *  parameters are not valid
      */
     @Override
-    public double evaluate(final double[] values, final int begin, final int length) {
+    public double evaluate(final double[] values, final int begin, final int length)
+    throws MathIllegalArgumentException {
         double product = Double.NaN;
         if (test(values, begin, length, true)) {
             product = 1.0;
@@ -133,7 +136,7 @@ public class Product extends AbstractStorelessUnivariateStatistic implements Ser
      * the input array, or <code>Double.NaN</code> if the designated subarray
      * is empty.</p>
      *
-     * <p>Throws <code>IllegalArgumentException</code> if any of the following are true:
+     * <p>Throws <code>MathIllegalArgumentException</code> if any of the following are true:
      * <ul><li>the values array is null</li>
      *     <li>the weights array is null</li>
      *     <li>the weights array does not have the same length as the values array</li>
@@ -153,11 +156,11 @@ public class Product extends AbstractStorelessUnivariateStatistic implements Ser
      * @param begin index of the first array element to include
      * @param length the number of elements to include
      * @return the product of the values or 1 if length = 0
-     * @throws IllegalArgumentException if the parameters are not valid
+     * @throws MathIllegalArgumentException if the parameters are not valid
      * @since 2.1
      */
     public double evaluate(final double[] values, final double[] weights,
-                           final int begin, final int length) {
+        final int begin, final int length) throws MathIllegalArgumentException {
         double product = Double.NaN;
         if (test(values, weights, begin, length, true)) {
             product = 1.0;
@@ -171,7 +174,7 @@ public class Product extends AbstractStorelessUnivariateStatistic implements Ser
     /**
      * <p>Returns the weighted product of the entries in the input array.</p>
      *
-     * <p>Throws <code>IllegalArgumentException</code> if any of the following are true:
+     * <p>Throws <code>MathIllegalArgumentException</code> if any of the following are true:
      * <ul><li>the values array is null</li>
      *     <li>the weights array is null</li>
      *     <li>the weights array does not have the same length as the values array</li>
@@ -188,10 +191,11 @@ public class Product extends AbstractStorelessUnivariateStatistic implements Ser
      * @param values the input array
      * @param weights the weights array
      * @return the product of the values or Double.NaN if length = 0
-     * @throws IllegalArgumentException if the parameters are not valid
+     * @throws MathIllegalArgumentException if the parameters are not valid
      * @since 2.1
      */
-    public double evaluate(final double[] values, final double[] weights) {
+    public double evaluate(final double[] values, final double[] weights)
+    throws MathIllegalArgumentException {
         return evaluate(values, weights, 0, values.length);
     }
 
@@ -202,6 +206,7 @@ public class Product extends AbstractStorelessUnivariateStatistic implements Ser
     @Override
     public Product copy() {
         Product result = new Product();
+        // No try-catch or advertised exception because args are valid
         copy(this, result);
         return result;
     }

src/main/java/org/apache/commons/math3/stat/descriptive/summary/Sum.java

@@ -18,6 +18,7 @@ package org.apache.commons.math3.stat.descriptive.summary;
 
 import java.io.Serializable;
 
+import org.apache.commons.math3.exception.MathIllegalArgumentException;
 import org.apache.commons.math3.exception.NullArgumentException;
 import org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic;
 import org.apache.commons.math3.util.MathUtils;
@@ -63,8 +64,9 @@ public class Sum extends AbstractStorelessUnivariateStatistic implements Seriali
      * to the {@code original}
      *
      * @param original the {@code Sum} instance to copy
+     * @throws NullArgumentException if original is null
      */
-    public Sum(Sum original) {
+    public Sum(Sum original) throws NullArgumentException {
         copy(original, this);
     }
 
@@ -106,17 +108,18 @@ public class Sum extends AbstractStorelessUnivariateStatistic implements Seriali
      * the input array, or 0 if the designated subarray
      * is empty.
      * <p>
-     * Throws <code>IllegalArgumentException</code> if the array is null.</p>
+     * Throws <code>MathIllegalArgumentException</code> if the array is null.</p>
      *
      * @param values the input array
      * @param begin index of the first array element to include
      * @param length the number of elements to include
      * @return the sum of the values or 0 if length = 0
-     * @throws IllegalArgumentException if the array is null or the array index
+     * @throws MathIllegalArgumentException if the array is null or the array index
      *  parameters are not valid
      */
     @Override
-    public double evaluate(final double[] values, final int begin, final int length) {
+    public double evaluate(final double[] values, final int begin, final int length)
+    throws MathIllegalArgumentException {
         double sum = Double.NaN;
         if (test(values, begin, length, true)) {
             sum = 0.0;
@@ -132,7 +135,7 @@ public class Sum extends AbstractStorelessUnivariateStatistic implements Seriali
      * the input array, or 0 if the designated subarray
      * is empty.
      * <p>
-     * Throws <code>IllegalArgumentException</code> if any of the following are true:
+     * Throws <code>MathIllegalArgumentException</code> if any of the following are true:
      * <ul><li>the values array is null</li>
      *     <li>the weights array is null</li>
      *     <li>the weights array does not have the same length as the values array</li>
@@ -151,11 +154,11 @@ public class Sum extends AbstractStorelessUnivariateStatistic implements Seriali
      * @param begin index of the first array element to include
      * @param length the number of elements to include
      * @return the sum of the values or 0 if length = 0
-     * @throws IllegalArgumentException if the parameters are not valid
+     * @throws MathIllegalArgumentException if the parameters are not valid
      * @since 2.1
      */
     public double evaluate(final double[] values, final double[] weights,
-                           final int begin, final int length) {
+        final int begin, final int length) throws MathIllegalArgumentException {
         double sum = Double.NaN;
         if (test(values, weights, begin, length, true)) {
             sum = 0.0;
@@ -169,7 +172,7 @@ public class Sum extends AbstractStorelessUnivariateStatistic implements Seriali
     /**
      * The weighted sum of the entries in the the input array.
      * <p>
-     * Throws <code>IllegalArgumentException</code> if any of the following are true:
+     * Throws <code>MathIllegalArgumentException</code> if any of the following are true:
      * <ul><li>the values array is null</li>
      *     <li>the weights array is null</li>
      *     <li>the weights array does not have the same length as the values array</li>
@@ -185,10 +188,11 @@ public class Sum extends AbstractStorelessUnivariateStatistic implements Seriali
      * @param values the input array
      * @param weights the weights array
      * @return the sum of the values or Double.NaN if length = 0
-     * @throws IllegalArgumentException if the parameters are not valid
+     * @throws MathIllegalArgumentException if the parameters are not valid
      * @since 2.1
      */
-    public double evaluate(final double[] values, final double[] weights) {
+    public double evaluate(final double[] values, final double[] weights)
+    throws MathIllegalArgumentException {
         return evaluate(values, weights, 0, values.length);
     }
 
@@ -198,6 +202,7 @@ public class Sum extends AbstractStorelessUnivariateStatistic implements Seriali
     @Override
     public Sum copy() {
         Sum result = new Sum();
+        // No try-catch or advertised exception because args are valid
         copy(this, result);
         return result;
     }

src/main/java/org/apache/commons/math3/stat/descriptive/summary/SumOfLogs.java

@@ -18,6 +18,7 @@ package org.apache.commons.math3.stat.descriptive.summary;
 
 import java.io.Serializable;
 
+import org.apache.commons.math3.exception.MathIllegalArgumentException;
 import org.apache.commons.math3.exception.NullArgumentException;
 import org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic;
 import org.apache.commons.math3.util.FastMath;
@@ -71,8 +72,9 @@ public class SumOfLogs extends AbstractStorelessUnivariateStatistic implements S
      * to the {@code original}
      *
      * @param original the {@code SumOfLogs} instance to copy
+     * @throws NullArgumentException if original is null
      */
-    public SumOfLogs(SumOfLogs original) {
+    public SumOfLogs(SumOfLogs original) throws NullArgumentException {
         copy(original, this);
     }
 
@@ -114,7 +116,7 @@ public class SumOfLogs extends AbstractStorelessUnivariateStatistic implements S
      * the input array, or <code>Double.NaN</code> if the designated subarray
      * is empty.
      * <p>
-     * Throws <code>IllegalArgumentException</code> if the array is null.</p>
+     * Throws <code>MathIllegalArgumentException</code> if the array is null.</p>
      * <p>
      * See {@link SumOfLogs}.</p>
      *
@@ -123,11 +125,12 @@ public class SumOfLogs extends AbstractStorelessUnivariateStatistic implements S
      * @param length the number of elements to include
      * @return the sum of the natural logs of the values or 0 if
      * length = 0
-     * @throws IllegalArgumentException if the array is null or the array index
+     * @throws MathIllegalArgumentException if the array is null or the array index
      *  parameters are not valid
      */
     @Override
-    public double evaluate(final double[] values, final int begin, final int length) {
+    public double evaluate(final double[] values, final int begin, final int length)
+    throws MathIllegalArgumentException {
         double sumLog = Double.NaN;
         if (test(values, begin, length, true)) {
             sumLog = 0.0;
@@ -144,6 +147,7 @@ public class SumOfLogs extends AbstractStorelessUnivariateStatistic implements S
     @Override
     public SumOfLogs copy() {
         SumOfLogs result = new SumOfLogs();
+        // No try-catch or advertised exception here because args are valid
         copy(this, result);
         return result;
     }

src/main/java/org/apache/commons/math3/stat/descriptive/summary/SumOfSquares.java

@@ -18,6 +18,7 @@ package org.apache.commons.math3.stat.descriptive.summary;
 
 import java.io.Serializable;
 
+import org.apache.commons.math3.exception.MathIllegalArgumentException;
 import org.apache.commons.math3.exception.NullArgumentException;
 import org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic;
 import org.apache.commons.math3.util.MathUtils;
@@ -62,8 +63,9 @@ public class SumOfSquares extends AbstractStorelessUnivariateStatistic implement
      * to the {@code original}
      *
      * @param original the {@code SumOfSquares} instance to copy
+     * @throws NullArgumentException if original is null
      */
-    public SumOfSquares(SumOfSquares original) {
+    public SumOfSquares(SumOfSquares original) throws NullArgumentException {
         copy(original, this);
     }
 
@@ -105,17 +107,18 @@ public class SumOfSquares extends AbstractStorelessUnivariateStatistic implement
      * the input array, or <code>Double.NaN</code> if the designated subarray
      * is empty.
      * <p>
-     * Throws <code>IllegalArgumentException</code> if the array is null.</p>
+     * Throws <code>MathIllegalArgumentException</code> if the array is null.</p>
      *
      * @param values the input array
      * @param begin index of the first array element to include
      * @param length the number of elements to include
      * @return the sum of the squares of the values or 0 if length = 0
-     * @throws IllegalArgumentException if the array is null or the array index
+     * @throws MathIllegalArgumentException if the array is null or the array index
      *  parameters are not valid
      */
     @Override
-    public double evaluate(final double[] values,final int begin, final int length) {
+    public double evaluate(final double[] values,final int begin, final int length)
+    throws MathIllegalArgumentException {
         double sumSq = Double.NaN;
         if (test(values, begin, length, true)) {
             sumSq = 0.0;
@@ -132,6 +135,7 @@ public class SumOfSquares extends AbstractStorelessUnivariateStatistic implement
     @Override
     public SumOfSquares copy() {
         SumOfSquares result = new SumOfSquares();
+        // no try-catch or advertised exception here because args are valid
         copy(this, result);
         return result;
     }