Patch for bug 21516 from Brent Worden. Fixed checkstyle bugs and added maven.javadoc.links to project.properties

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

project.properties

@@ -11,3 +11,11 @@ maven.xdoc.date=left
 maven.xdoc.version=${pom.currentVersion}
 maven.xdoc.developmentProcessUrl=http://jakarta.apache.org/commons/charter.html
 
+maven.javadoc.links = http://java.sun.com/j2se/1.4.1/docs/api/,\
+                      http://jakarta.apache.org/commons/collections/api/,\
+                      http://jakarta.apache.org/commons/beanutils/api/,\
+                      http://jakarta.apache.org/commons/logging/api/
+maven.javadoc.links = http://java.sun.com/j2se/1.4.1/docs/api/,\
+                      http://jakarta.apache.org/commons/collections/api/,\
+                      http://jakarta.apache.org/commons/beanutils/api/,\
+                      http://jakarta.apache.org/commons/logging/api/

src/java/org/apache/commons/math/analysis/BrentSolver.java

@@ -61,7 +61,7 @@ import org.apache.commons.math.MathException;
  * It will only search for one zero in the given interval.
  * The function is supposed to be continuous but not necessarily smooth.
  *  
- * @version $Revision: 1.3 $ $Date: 2003/07/09 20:02:43 $
+ * @version $Revision: 1.4 $ $Date: 2003/07/11 15:59:14 $
  */
 public class BrentSolver extends UnivariateRealSolverImpl {
     /**
@@ -136,8 +136,8 @@ public class BrentSolver extends UnivariateRealSolverImpl {
                 setResult(x1, i);
                 return result;
             }
-            if (Math.abs(oldDelta) < tolerance
+            if ((Math.abs(oldDelta) < tolerance) ||
-                || Math.abs(y0) <= Math.abs(y1)) {
+                    (Math.abs(y0) <= Math.abs(y1))) {
                 // Force bisection.
                 delta = 0.5 * dx;
                 oldDelta = delta;
@@ -161,8 +161,8 @@ public class BrentSolver extends UnivariateRealSolverImpl {
                 } else {
                     p = -p;
                 }
-                if (2.0 * p >= 1.5 * dx * p1 - Math.abs(tolerance * p1)
+                if (2.0 * p >= 1.5 * dx * p1 - Math.abs(tolerance * p1) ||
-                    || p >= Math.abs(0.5 * oldDelta * p1)) {
+                        p >= Math.abs(0.5 * oldDelta * p1)) {
                     // Inverse quadratic interpolation gives a value
                     // in the wrong direction, or progress is slow.
                     // Fall back to bisection.

src/java/org/apache/commons/math/analysis/CubicSplineFunction.java

@@ -64,30 +64,42 @@ import org.apache.commons.math.MathException;
  * polynominal coefficents are used.
  * Arguments outside of the domain cause an IllegalArgumentException.
  * 
- * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $
+ * @version $Revision: 1.3 $ $Date: 2003/07/11 15:59:14 $
- *
  */
 public class CubicSplineFunction implements UnivariateRealFunction {
-    // Spline segment interval delimiters.
+    /** Spline segment interval delimiters. Size is N+1 for N segments. */
-    // Size is N+1 for N segments.
     private double xval[];
 
-    // The spline segment's polynominal coefficients.
+    /**
-    // The first index runs over the intervals, size is N.
+     * The spline segment's polynominal coefficients.
-    // The second index adresses the coefficients in the segment, with
+     * The first index runs over the intervals, size is N.
-    // index 0 being the absolute coefficient and index 3 the coefficient
+     * The second index adresses the coefficients in the segment, with
-    // for the third power.
+     * index 0 being the absolute coefficient and index 3 the coefficient
-    // The coefficients are setup so that x runs from 0 to xval[i+1]-xval[i].
+     * for the third power.
+     * The coefficients are setup so that x runs from 0 to xval[i+1]-xval[i].
+     */
     private double c[][];
 
+    /**
+     * Construct a function with the given segment delimiters and polynomial
+     * coefficients.
+     * @param xval Spline segment interval delimiters
+     * @param c spline segment's polynominal coefficients
+     */
     public CubicSplineFunction(double xval[], double c[][]) {
+        super();
         // TODO: should copy the arguments here, for safety. This could be a major overhead.
         this.xval = xval;
         this.c = c;
     }
 
-    /* (non-Javadoc)
+    /**
-     * @see org.apache.commons.math.UnivariateRealFunction#value(double)
+     * Compute the value for the function.
+     * @param x the point for which the function value should be computed
+     * @return the value
+     * @throws MathException if the function couldn't be computed due to
+     *  missing additional data or other environmental problems.
+     * @see UnivariateRealFunction#value(double)
      */
     public double value(double x) throws MathException {
         if (x < xval[0] || x > xval[xval.length - 1]) {
@@ -101,8 +113,16 @@ public class CubicSplineFunction implements UnivariateRealFunction {
         return ((c[i][3] * x + c[i][2]) * x + c[i][1]) * x + c[i][0];
     }
 
-    /* (non-Javadoc)
+    /**
-     * @see org.apache.commons.math.UnivariateRealFunction#firstDerivative(double)
+     * Compute the value for the first derivative of the function.
+     * It is recommended to provide this method only if the first derivative is
+     * analytical. Numerical derivatives may be acceptable in some cases.
+     * An implementation should throw an UnsupportedOperationException if
+     * this method is not implemented.
+     * @param x the point for which the first derivative should be computed
+     * @return the value
+     * @throws MathException if the derivative couldn't be computed.
+     * @see UnivariateRealFunction#firstDerivative(double)
      */
     public double firstDerivative(double x) throws MathException {
         if (x < xval[0] || x > xval[xval.length - 1]) {
@@ -116,8 +136,16 @@ public class CubicSplineFunction implements UnivariateRealFunction {
         return (3 * c[i][3] * x + 2 * c[i][2]) * x + c[i][1];
     }
 
-    /* (non-Javadoc)
+    /**
-     * @see org.apache.commons.math.UnivariateRealFunction#secondDerivative(double)
+     * Compute the value for the second derivative of the function.
+     * It is recommended to provide this method only if the second derivative is
+     * analytical. Numerical derivatives may be acceptable in some cases.
+     * An implementation should throw an UnsupportedOperationException if
+     * this method is not implemented.
+     * @param x the point for which the first derivative should be computed
+     * @return the value
+     * @throws MathException if the second derivative couldn't be computed.
+     * @see UnivariateRealFunction#secondDerivative(double)
      */
     public double secondDerivative(double x) throws MathException {
         if (x < xval[0] || x > xval[xval.length - 1]) {

src/java/org/apache/commons/math/analysis/SecantSolver.java

@@ -63,7 +63,7 @@ import org.apache.commons.math.MathException;
  * It will only search for one zero in the given interval.
  * The function is supposed to be continuous but not necessarily smooth.
  *  
- * @version $Revision: 1.3 $ $Date: 2003/07/09 20:02:43 $
+ * @version $Revision: 1.4 $ $Date: 2003/07/11 15:59:14 $
  */
 public class SecantSolver extends UnivariateRealSolverImpl {
     /**
@@ -128,8 +128,8 @@ public class SecantSolver extends UnivariateRealSolverImpl {
                 setResult(x1, i);
                 return result;
             }
-            if (Math.abs(oldDelta)
+            if (Math.abs(oldDelta) <
-                < Math.max(relativeAccuracy * Math.abs(x1), absoluteAccuracy)) {
+                Math.max(relativeAccuracy * Math.abs(x1), absoluteAccuracy)) {
                 setResult(x1, i);
                 return result;
             }

src/java/org/apache/commons/math/analysis/UnivariateFunction.java

@@ -1,66 +0,0 @@
-/* ====================================================================
- * The Apache Software License, Version 1.1
- *
- * Copyright (c) 2003 The Apache Software Foundation.  All rights
- * reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- *    notice, this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in
- *    the documentation and/or other materials provided with the
- *    distribution.
- *
- * 3. The end-user documentation included with the redistribution, if
- *    any, must include the following acknowlegement:
- *       "This product includes software developed by the
- *        Apache Software Foundation (http://www.apache.org/)."
- *    Alternately, this acknowlegement may appear in the software itself,
- *    if and wherever such third-party acknowlegements normally appear.
- *
- * 4. The names "The Jakarta Project", "Commons", and "Apache Software
- *    Foundation" must not be used to endorse or promote products derived
- *    from this software without prior written permission. For written
- *    permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache"
- *    nor may "Apache" appear in their names without prior written
- *    permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation.  For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- */
-package org.apache.commons.math.analysis;
-
-/**
- * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $
- */
-public interface UnivariateFunction {
-    // TODO: More documentation
-
-    /**
-     * 
-     */
-    double evaluate(double x);
-}

src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java

@@ -62,10 +62,9 @@ import org.apache.commons.math.MathException;
  * that derivatives are evaluated after the value, the evaluation algorithm
  * should throw an InvalidStateException if it can't cope with this.
  *  
- * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $
+ * @version $Revision: 1.3 $ $Date: 2003/07/11 15:59:14 $
  */
 public interface UnivariateRealFunction {
-
     /**
      * Compute the value for the function.
      * @param x the point for which the function value should be computed
@@ -74,7 +73,6 @@ public interface UnivariateRealFunction {
      *  missing additional data or other environmental problems.
      * @throws RuntimeException if the operation isn't supported, the argument
      *  was outside the supported domain or any other problem.
-     * 
      */
     public double value(double x) throws MathException;
 
@@ -89,7 +87,6 @@ public interface UnivariateRealFunction {
      * @throws MathException if the derivative couldn't be computed.
      * @throws RuntimeException if the operation isn't supported, the argument
      *  was outside the supported domain or any other problem.
-     * 
      */
     public double firstDerivative(double x) throws MathException;
 
@@ -104,7 +101,6 @@ public interface UnivariateRealFunction {
      * @throws MathException if the second derivative couldn't be computed.
      * @throws RuntimeException if the operation isn't supported, the argument
      *  was outside the supported domain or any other problem.
-     * 
      */
     public double secondDerivative(double x) throws MathException;
 }

src/java/org/apache/commons/math/analysis/UnivariateRealInterpolator.java

@@ -58,7 +58,7 @@ import org.apache.commons.math.MathException;
 /**
  * Interface for interpolating a data set.
  *  
- * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $
+ * @version $Revision: 1.3 $ $Date: 2003/07/11 15:59:14 $
  */
 public interface UnivariateRealInterpolator {
 
@@ -67,7 +67,8 @@ public interface UnivariateRealInterpolator {
      * @param xval the arguments for the interpolation points
      * @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 interpolationg algorithm
+     * @throws MathException if arguments violate assumptions made by the
+     *         interpolationg algorithm
      */
     public UnivariateRealFunction interpolate(double xval[], double yval[])
         throws MathException;

src/java/org/apache/commons/math/analysis/UnivariateRealSolver.java

@@ -60,7 +60,7 @@ import org.apache.commons.math.MathException;
  * functions.
  * An implementation will only search for one zero in the given interval.
  *  
- * @version $Revision: 1.3 $ $Date: 2003/07/09 20:02:43 $
+ * @version $Revision: 1.4 $ $Date: 2003/07/11 15:59:14 $
  */
 public interface UnivariateRealSolver {
 
@@ -184,7 +184,7 @@ public interface UnivariateRealSolver {
      * A solver may require that the interval brackets a single zero root.
      * @param min the lower bound for the interval.
      * @param max the upper bound for the interval.
-     * @return the value where the function is zero
+     * @return a value where the function is zero
      * @throws MathException if the iteration count was exceeded or the
      *  solver detects convergence problems otherwise.
      */
@@ -196,7 +196,7 @@ public interface UnivariateRealSolver {
      * @param min the lower bound for the interval.
      * @param max the upper bound for the interval.
      * @param startValue the start value to use
-     * @return the value where the function is zero
+     * @return a value where the function is zero
      * @throws MathException if the iteration count was exceeded or the
      *  solver detects convergence problems otherwise.
      */

src/java/org/apache/commons/math/analysis/UnivariateRealSolverFactory.java

@@ -66,12 +66,29 @@ import org.apache.commons.math.MathException;
  * (this may be controversial, because the configuration data
  * may also be used for the default solver used by the static
  * solve() method). 
- * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $
+ * @version $Revision: 1.3 $ $Date: 2003/07/11 15:59:14 $
  */
 public class UnivariateRealSolverFactory {
-    protected UnivariateRealSolverFactory() {
+    /**
+     * Default constructor.
+     */
+    private UnivariateRealSolverFactory() {
     }
 
+    /**
+     * Create a new {@link UnivariateRealSolver} for the given function.  The
+     * actual solver returned can be controlled by defining the
+     * <code>org.apache.commons.math.analysis.UnivariateRealSolver</code>
+     * property on the JVM command-line (<code>
+     * -Dorg.apache.commons.math.analysis.UnivariateRealSolver=
+     * <i>class name</i></code>).  The value of the property should be any,
+     * fully qualified class name for a type that implements the
+     * {@link UnivariateRealSolver} interface.  By default, an instance of
+     * {@link BrentSolver} is returned.
+     * @param f the function.
+     * @return the new solver.
+     * @throws MathConfigurationException if a
+     */
     public static UnivariateRealSolver newSolver(UnivariateRealFunction f)
         throws MathConfigurationException {
         String solverClassName =
@@ -81,8 +98,7 @@ public class UnivariateRealSolverFactory {
         try {
             Class clazz = Class.forName(solverClassName);
             Class paramClass[] = new Class[1];
-            paramClass[0] =
+            paramClass[0] = UnivariateRealFunction.class;
-                Class.forName("org.apache.commons.math.analysis.UnivariateRealFunction");
             Object param[] = new Object[1];
             param[0] = f;
             return (UnivariateRealSolver)clazz.getConstructor(
@@ -110,17 +126,38 @@ public class UnivariateRealSolverFactory {
             throw new MathConfigurationException(e);
         } catch (NoSuchMethodException e) {
             throw new MathConfigurationException(
-                "No constructor with UnivariateRealFunction in "
+                "No constructor with UnivariateRealFunction in " +
-                    + solverClassName,
+                solverClassName,
                 e);
         }
     }
 
+    /**
+     * Convience method to solve for zeros of real univariate functions.  A
+     * default solver is created and used for solving. 
+     * @param f the function.
+     * @param x0 the lower bound for the interval.
+     * @param x1 the upper bound for the interval.
+     * @return a value where the function is zero.
+     * @throws MathException if the iteration count was exceeded or the
+     *         solver detects convergence problems otherwise.
+     */
     public static double solve(UnivariateRealFunction f, double x0, double x1)
         throws MathException {
         return newSolver(f).solve(x0, x1);
     }
 
+    /**
+     * Convience method to solve for zeros of real univariate functions.  A
+     * default solver is created and used for solving. 
+     * @param f the function.
+     * @param x0 the lower bound for the interval.
+     * @param x1 the upper bound for the interval.
+     * @param absoluteAccuracy the accuracy to be used by the solver.
+     * @return a value where the function is zero.
+     * @throws MathException if the iteration count was exceeded or the
+     *         solver detects convergence problems otherwise.
+     */
     public static double solve(
         UnivariateRealFunction f,
         double x0,