commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From er...@apache.org
Subject svn commit: r1175588 - /commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/UnivariateRealFunction.java
Date Sun, 25 Sep 2011 21:44:13 GMT
Author: erans
Date: Sun Sep 25 21:44:13 2011
New Revision: 1175588

URL: http://svn.apache.org/viewvc?rev=1175588&view=rev
Log:
MATH-674
Moved part of the Javadoc for the "value" method over to the interface
section.

Modified:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/UnivariateRealFunction.java

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/UnivariateRealFunction.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/UnivariateRealFunction.java?rev=1175588&r1=1175587&r2=1175588&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/UnivariateRealFunction.java
(original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/analysis/UnivariateRealFunction.java
Sun Sep 25 21:44:13 2011
@@ -18,6 +18,50 @@ package org.apache.commons.math.analysis
 
 /**
  * An interface representing a univariate real function.
+ * <br/>
+ * When a <em>user-defined</em> function encounters an error during
+ * evaluation, the {@link #value(double) value} method should throw a
+ * <em>user-defined</em> unchecked exception.
+ * <br/>
+ * The following code excerpt shows the recommended way to do that using
+ * a root solver as an example, but the same construct is applicable to
+ * ODE integrators or optimizers.
+ *
+ * <pre>
+ * private static class LocalException extends RuntimeException {
+ *     // The x value that caused the problem.
+ *     private final double x;
+ *
+ *     public LocalException(double x) {
+ *         this.x = x;
+ *     }
+ *
+ *     public double getX() {
+ *         return x;
+ *     }
+ * }
+ *
+ * private static class MyFunction implements UnivariateRealFunction {
+ *     public double value(double x) {
+ *         double y = hugeFormula(x);
+ *         if (somethingBadHappens) {
+ *           throw new LocalException(x);
+ *         }
+ *         return y;
+ *     }
+ * }
+ *
+ * public void compute() {
+ *     try {
+ *         solver.solve(maxEval, new MyFunction(a, b, c), min, max);
+ *     } catch (LocalException le) {
+ *         // Retrieve the x value.
+ *     }
+ * }
+ * </pre>
+ *
+ * As shown, the exception is local to the user's code and it is guaranteed
+ * that Apache Commons Math will not catch it.
  *
  * @version $Id$
  */
@@ -25,60 +69,14 @@ public interface UnivariateRealFunction 
     /**
      * Compute the value of the function.
      *
-     * <p>
-     * For user-defined functions, when the method encounters an error
-     * during evaluation, users must use their <em>own</em> unchecked exceptions.
-     * The following example shows the recommended way to do that, using root
-     * solving as the example (the same construct should be used for ODE
-     * integrators or for optimizations).
-     * </p>
-     * <pre>
-     * private static class LocalException extends RuntimeException {
-     *
-     *   // the x value that caused the problem
-     *   private final double x;
-     *
-     *   public LocalException(double x) {
-     *     this.x = x;
-     *   }
-     *
-     *   public double getX() {
-     *     return x;
-     *   }
-     *
-     * }
-     *
-     * private static class MyFunction implements UnivariateRealFunction {
-     *   public double value(double x) {
-     *     double y = hugeFormula(x);
-     *     if (somethingBadHappens) {
-     *       throw new LocalException(x);
-     *     }
-     *     return y;
-     *   }
-     * }
-     *
-     * public void compute() {
-     *   try {
-     *     solver.solve(maxEval, new MyFunction(a, b, c), min, max);
-     *   } catch (LocalException le) {
-     *     // retrieve the x value
-     *   }
-     * }
-     * </pre>
-     *
-     * <p>
-     * As shown in this example the exception is really something local to user code
-     * and there is a guarantee Apache Commons Math will not mess with it. The user is safe.
-     * </p>
      * @param x Point at which the function value should be computed.
-     * @return the value.
+     * @return the value of the function.
      * @throws IllegalArgumentException 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 IllegalArgumentException,
-     * it is the result of argument checking of actual parameters immediately
-     * passed to a method.
+     * ascertain that a precondition, specified in the API expressed at the
+     * level of the activated method, has been violated.
+     * When Commons Math throws an {@code IllegalArgumentException}, it is
+     * usually the consequence of checking the actual parameters passed to
+     * the method.
      */
     double value(double x);
 }



Mime
View raw message