MATH-488

Removed occurrences of "MathException" in multidimensional interpolator.
Replaced "DimensionMismatchException" by its unchecked equivalent (MATH-491).
[I forgot to make those changes as part of MATH-458.]
Fixed Javadoc.


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

src/main/java/org/apache/commons/math/analysis/MultivariateRealFunction.java

@@ -17,10 +17,9 @@
 
 package org.apache.commons.math.analysis;
 
-import org.apache.commons.math.exception.MathUserException;
-
 /**
  * An interface representing a multivariate real function.
+ *
  * @version $Revision$ $Date$
  * @since 2.0
  */
@@ -28,12 +27,19 @@ public interface MultivariateRealFunction {
 
     /**
      * Compute the value for the function at the given point.
-     * @param point point at which the function must be evaluated
+     *
-     * @return function value for the given point
+     * @param point Point at which the function must be evaluated.
-     * @exception MathUserException if the function evaluation fails
+     * @return the function value for the given point.
-     * @exception IllegalArgumentException if points dimension is wrong
+     * @throws org.apache.commons.math.exception.MathUserException if
+     * the function evaluation fails.
+     * @throws org.apache.commons.math.exception.DimensionMismatchException
+     * if the parameter's dimension is wrong for the function being evaluated.
+     * @throws  org.apache.commons.math.exception.MathIllegalArgumentException
+     * when the activated method itself can ascertain that preconditions,
+     * specified in the API expressed at the level of the activated method,
+     * have been violated.  In the vast majority of cases where Commons Math
+     * throws this exception, it is the result of argument checking of actual
+     * parameters immediately passed to a method.
      */
-    double value(double[] point)
+    double value(double[] point);
-        throws MathUserException, IllegalArgumentException;
-
 }

src/main/java/org/apache/commons/math/analysis/interpolation/MicrosphereInterpolatingFunction.java

@@ -21,9 +21,10 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
-import org.apache.commons.math.DimensionMismatchException;
 import org.apache.commons.math.analysis.MultivariateRealFunction;
+import org.apache.commons.math.exception.DimensionMismatchException;
 import org.apache.commons.math.exception.NoDataException;
+import org.apache.commons.math.exception.NullArgumentException;
 import org.apache.commons.math.linear.ArrayRealVector;
 import org.apache.commons.math.linear.RealVector;
 import org.apache.commons.math.random.UnitSphereRandomVectorGenerator;
@@ -62,13 +63,10 @@ public class MicrosphereInterpolatingFunction
      * microsphere projection.
      */
     private static class MicrosphereSurfaceElement {
-
         /** Normal vector characterizing a surface element. */
         private final RealVector normal;
-
         /** Illumination received from the brightest sample. */
         private double brightestIllumination;
-
         /** Brightest sample. */
         private Map.Entry<RealVector, Double> brightestSample;
 
@@ -142,21 +140,27 @@ public class MicrosphereInterpolatingFunction
      * {@code xval} (equal to {@code n}, the number of interpolation points)
      * do not match, or the the arrays {@code xval[0]} ... {@code xval[n]},
      * have lengths different from {@code dimension}.
-     * @throws NoDataException if there are no data (xval null or zero length)
+     * @throws NoDataException if there an array has zero-length.
+     * @throws NullArgumentException if an argument is {@code null}.
      */
     public MicrosphereInterpolatingFunction(double[][] xval,
                                             double[] yval,
                                             int brightnessExponent,
                                             int microsphereElements,
-                                            UnitSphereRandomVectorGenerator rand)
+                                            UnitSphereRandomVectorGenerator rand) {
-        throws DimensionMismatchException, NoDataException {
+        if (xval == null ||
-        if (xval.length == 0 || xval[0] == null) {
+            yval == null) {
+            throw new NullArgumentException();
+        }
+        if (xval.length == 0) {
             throw new NoDataException();
         }
-
         if (xval.length != yval.length) {
             throw new DimensionMismatchException(xval.length, yval.length);
         }
+        if (xval[0] == null) {
+            throw new NullArgumentException();
+        }
         
         dimension = xval[0].length;
         this.brightnessExponent = brightnessExponent;
@@ -165,7 +169,10 @@ public class MicrosphereInterpolatingFunction
         samples = new HashMap<RealVector, Double>(yval.length);
         for (int i = 0; i < xval.length; ++i) {
             final double[] xvalI = xval[i];
-            if ( xvalI.length != dimension) {
+            if (xvalI == null) {
+                throw new NullArgumentException();
+            }
+            if (xvalI.length != dimension) {
                 throw new DimensionMismatchException(xvalI.length, dimension);
             }
 
@@ -178,7 +185,6 @@ public class MicrosphereInterpolatingFunction
         for (int i = 0; i < microsphereElements; i++) {
             microsphere.add(new MicrosphereSurfaceElement(rand.nextVector()));
         }
-
     }
 
     /**
@@ -186,7 +192,6 @@ public class MicrosphereInterpolatingFunction
      * @return the interpolated value.
      */
     public double value(double[] point) {
-
         final RealVector p = new ArrayRealVector(point);
 
         // Reset.
@@ -227,7 +232,6 @@ public class MicrosphereInterpolatingFunction
         }
 
         return value / totalWeight;
-
     }
 
     /**
@@ -235,7 +239,7 @@ public class MicrosphereInterpolatingFunction
      *
      * @param v Vector.
      * @param w Vector.
-     * @return cosine of the angle
+     * @return the cosine of the angle between {@code v} and {@code w}.
      */
     private double cosAngle(final RealVector v, final RealVector w) {
         return v.dotProduct(w) / (v.getNorm() * w.getNorm());

src/main/java/org/apache/commons/math/analysis/interpolation/MicrosphereInterpolator.java

@@ -16,7 +16,6 @@
  */
 package org.apache.commons.math.analysis.interpolation;
 
-import org.apache.commons.math.MathException;
 import org.apache.commons.math.analysis.MultivariateRealFunction;
 import org.apache.commons.math.exception.NotPositiveException;
 import org.apache.commons.math.exception.NotStrictlyPositiveException;
@@ -85,8 +84,7 @@ public class MicrosphereInterpolator
      * {@inheritDoc}
      */
     public MultivariateRealFunction interpolate(final double[][] xval,
-                                                final double[] yval)
+                                                final double[] yval) {
-        throws MathException, IllegalArgumentException {
         final UnitSphereRandomVectorGenerator rand
             = new UnitSphereRandomVectorGenerator(xval[0].length);
         return new MicrosphereInterpolatingFunction(xval, yval,

src/main/java/org/apache/commons/math/analysis/interpolation/MultivariateRealInterpolator.java

@@ -16,7 +16,6 @@
  */
 package org.apache.commons.math.analysis.interpolation;
 
-import org.apache.commons.math.MathException;
 import org.apache.commons.math.analysis.MultivariateRealFunction;
 
 /**
@@ -37,10 +36,15 @@ public interface MultivariateRealInterpolator {
      * point (where {@code d} is thus the dimension of the space).
      * @param yval the values for the interpolation points
      * @return a function which interpolates the data set
-     * @throws MathException if arguments violate assumptions made by the
+     * @throws org.apache.commons.math.exception.MathIllegalArgumentException
-     *         interpolation algorithm or some dimension mismatch occurs
+     * if the arguments violate assumptions made by the interpolation
-     * @throws IllegalArgumentException if there are no data (xval null or zero length)
+     * algorithm.
+     * @throws org.apache.commons.math.exception.DimensionMismatchException
+     * when the array dimensions are not consistent.
+     * @throws org.apache.commons.math.exception.NoDataException if an
+     * array has zero-length.
+     * @throws org.apache.commons.math.exception.NullArgumentException if
+     * the arguments are {@code null}.
      */
-    MultivariateRealFunction interpolate(double[][] xval, double[] yval)
+    MultivariateRealFunction interpolate(double[][] xval, double[] yval);
-        throws MathException, IllegalArgumentException;
 }