AXIS2-5862 Document misleading currentPhaseIndex / currentHandlerIndex naming

The two index fields on MessageContext are named opposite to what the
names imply, and that confusion is what led the AXIS2-5862 reporter
to propose a patch that would have regressed the engine:

  * currentHandlerIndex indexes the MessageContext.executionChain, whose
    elements are Phase objects (Phase implements Handler). So it is
    effectively "index of the current Phase within the execution chain."
    AxisEngine.invoke walks the chain via get/setCurrentHandlerIndex.

  * currentPhaseIndex indexes the handlers list INSIDE the Phase that is
    currently executing. So it is effectively "index of the current
    Handler within the current Phase." Phase.invoke and
    Phase.flowComplete walk that list via get/setCurrentPhaseIndex.

Renaming the fields would be a semver-major break (public getters/
setters, Externalizable wire format, downstream module code, etc.),
so the fields keep their historical names. This commit adds the
explanation directly to the fields' Javadoc, the four accessor
methods' Javadoc, and the confusing local-variable reassignment in
Phase.flowComplete where we read getCurrentPhaseIndex() into a local
called currentHandlerIndex.

No functional change.

Author: robertlazarski

modules/kernel/src/org/apache/axis2/context/MessageContext.java

@@ -346,12 +346,29 @@ public static void setCurrentMessageContext(MessageContext ctx) {
     private transient ConfigurationContext configurationContext;
 
     /**
-     * @serial Index into the executuion chain of the currently executing handler
+     * @serial Index into the execution chain of the currently executing handler.
+     * <p>
+     * NOTE on naming (see AXIS2-5862 for history): the execution chain stored
+     * on this MessageContext is a {@code List<Handler>} whose elements are
+     * actually {@link org.apache.axis2.engine.Phase} objects (Phase implements
+     * Handler). So despite the field name, {@code currentHandlerIndex} is
+     * effectively "index of the current Phase within the execution chain."
+     * {@link org.apache.axis2.engine.AxisEngine#invoke} walks the chain using
+     * this field and {@link #setCurrentHandlerIndex(int)}.
      */
     private int currentHandlerIndex;
 
     /**
-     * @serial Index into the current Phase of the currently executing handler (if any)
+     * @serial Index into the current Phase of the currently executing handler (if any).
+     * <p>
+     * NOTE on naming (see AXIS2-5862 for history): despite the field name,
+     * {@code currentPhaseIndex} does NOT index the chain of phases --
+     * {@link #currentHandlerIndex} does that. This field indexes the
+     * {@code handlers} list INSIDE the Phase that is currently executing,
+     * so it is effectively "index of the current Handler within the current
+     * Phase." {@link org.apache.axis2.engine.Phase#invoke} and
+     * {@link org.apache.axis2.engine.Phase#flowComplete} use this field
+     * via {@link #getCurrentPhaseIndex()} / {@link #setCurrentPhaseIndex(int)}.
      */
     private int currentPhaseIndex;
 
@@ -625,10 +642,21 @@ public ConfigurationContext getConfigurationContext() {
         return configurationContext;
     }
 
+    /**
+     * @return The index of the current Phase within the execution chain.
+     *         See the note on {@link #currentHandlerIndex} for why the
+     *         field is named the way it is.
+     */
     public int getCurrentHandlerIndex() {
         return currentHandlerIndex;
     }
 
+    /**
+     * @return The index of the currently executing Handler within the
+     *         current Phase's handlers list. See the note on
+     *         {@link #currentPhaseIndex} for why the field is named the
+     *         way it is.
+     */
     public int getCurrentPhaseIndex() {
         return currentPhaseIndex;
     }
@@ -1272,10 +1300,21 @@ public void setConfigurationContext(ConfigurationContext context) {
         configurationContext = context;
     }
 
+    /**
+     * Sets the index of the current Phase within the execution chain.
+     * See the note on {@link #currentHandlerIndex} for why the field
+     * is named the way it is.
+     */
     public void setCurrentHandlerIndex(int currentHandlerIndex) {
         this.currentHandlerIndex = currentHandlerIndex;
     }
 
+    /**
+     * Sets the index of the currently executing Handler within the
+     * current Phase's handlers list. See the note on
+     * {@link #currentPhaseIndex} for why the field is named the way
+     * it is.
+     */
     public void setCurrentPhaseIndex(int currentPhaseIndex) {
         this.currentPhaseIndex = currentPhaseIndex;
     }

modules/kernel/src/org/apache/axis2/engine/Phase.java

@@ -342,7 +342,15 @@ public void flowComplete(MessageContext msgContext) {
         }
 
         // This will be non-zero if we failed during execution of one of the
-        // handlers in this phase
+        // handlers in this phase.
+        //
+        // Naming note: the local is called "currentHandlerIndex" because that
+        // is what the value *semantically* is -- the index of the handler
+        // within this Phase at which the fault was raised. The getter is
+        // called getCurrentPhaseIndex() because that is the MessageContext
+        // field name, but despite the name the field holds a handler-within-
+        // phase index, not a phase-within-chain index. See the Javadoc on
+        // MessageContext.currentPhaseIndex and AXIS2-5862.
         int currentHandlerIndex = msgContext.getCurrentPhaseIndex();
         if (currentHandlerIndex == 0) {
             currentHandlerIndex = handlers.size();