Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@commons.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r900451 -
 /commons/proper/math/trunk/src/main/java/org/apache/commons/math/ode/events/EventHandler.java
Date: Mon, 18 Jan 2010 16:31:19 -0000
To: commits@commons.apache.org
From: luc@apache.org
Message-Id: <20100118163119.51A5823888EC@eris.apache.org>

Author: luc
Date: Mon Jan 18 16:31:18 2010
New Revision: 900451

URL: http://svn.apache.org/viewvc?rev=900451&view=rev
Log:
improved javadoc

Modified:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math/ode/events/EventHandler.java

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/ode/events/EventHandler.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/ode/events/EventHandler.java?rev=900451&r1=900450&r2=900451&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math/ode/events/EventHandler.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/ode/events/EventHandler.java Mon Jan 18 16:31:18 2010
@@ -21,7 +21,7 @@
  * during ODE integration.
  *
  * <p>Some events can be triggered at discrete times as an ODE problem
- * is solved. These occurs for example when the integration process
+ * is solved. This occurs for example when the integration process
  * should be stopped as some state is reached (G-stop facility) when the
  * precise date is unknown a priori, or when the derivatives have
  * discontinuities, or simply when the user wants to monitor some
@@ -101,10 +101,10 @@
   /** Handle an event and choose what to do next.
 
    * <p>This method is called when the integrator has accepted a step
-   * ending exactly on a sign change of the function, just before the
-   * step handler itself is called. It allows the user to update his
-   * internal data to acknowledge the fact the event has been handled
-   * (for example setting a flag in the {@link
+   * ending exactly on a sign change of the function, just <em>before</em>
+   * the step handler itself is called (see below for scheduling). It
+   * allows the user to update his internal data to acknowledge the fact
+   * the event has been handled (for example setting a flag in the {@link
    * org.apache.commons.math.ode.FirstOrderDifferentialEquations
    * differential equations} to switch the derivatives computation in
    * case of discontinuity), or to direct the integrator to either stop
@@ -126,6 +126,30 @@
    *   will continue.</li>
    * </ul>
 
+   * <p>The scheduling between this method and the {@link
+   * org.apache.commons.math.ode.sampling.StepHandler StepHandler} method {@link
+   * org.apache.commons.math.ode.sampling.StepNormalizerStepHandler#handleStep(
+   * org.apache.commons.math.ode.sampling.StepInterpolator, boolean)
+   * handleStep(interpolator, isLast)} is to call this method first and
+   * <code>handleStep</code> afterwards. This scheduling allows the integrator to
+   * pass <code>true</code> as the <code>isLast</code> parameter to the step
+   * handler to make it aware the step will be the last one if this method
+   * returns {@link #STOP}. As the interpolator may be used to navigate back
+   * throughout the last step (as {@link
+   * org.apache.commons.math.ode.sampling.StepNormalizerStepNormalizer
+   * StepNormalizer} does for example), user code called by this method and user
+   * code called by step handlers may experience apparently out of order values
+   * of the independent time variable. As an example, if the same user object
+   * implements both this {@link EventHandler EventHandler} interface and the
+   * {@link org.apache.commons.math.ode.sampling.FixedStepHandler FixedStepHandler}
+   * interface, a <em>forward</em> integration may call its
+   * <code>eventOccurred</code> method with t = 10 first and call its
+   * <code>handleStep</code> method with t = 9 afterwards. Such out of order
+   * calls are limited to the size of the integration step for {@link
+   * org.apache.commons.math.ode.sampling.StepHandler variable step handlers} and
+   * to the size of the fixed step for {@link
+   * org.apache.commons.math.ode.sampling.FixedStepHandler fixed step handlers}.</p>
+
    * @param t current value of the independent <i>time</i> variable
    * @param y array containing the current value of the state vector
    * @param increasing if true, the value of the switching function increases