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);
}
