This is an automated email from the ASF dual-hosted git repository.
robertlazarski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-java-core.git
The following commit(s) were added to refs/heads/master by this push:
new c016d8f3ed AXIS2-5862 Document misleading currentPhaseIndex /
currentHandlerIndex naming
c016d8f3ed is described below
commit c016d8f3ed57dc0dc97d2f158a7f857d0d41f5ed
Author: Robert Lazarski <[email protected]>
AuthorDate: Mon Apr 13 09:05:06 2026 -1000
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.
---
.../org/apache/axis2/context/MessageContext.java | 43 +++++++++++++++++++++-
.../kernel/src/org/apache/axis2/engine/Phase.java | 10 ++++-
2 files changed, 50 insertions(+), 3 deletions(-)
diff --git a/modules/kernel/src/org/apache/axis2/context/MessageContext.java
b/modules/kernel/src/org/apache/axis2/context/MessageContext.java
index 80f981b477..e03368de48 100644
--- a/modules/kernel/src/org/apache/axis2/context/MessageContext.java
+++ b/modules/kernel/src/org/apache/axis2/context/MessageContext.java
@@ -346,12 +346,29 @@ public class MessageContext extends AbstractContext
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 class MessageContext extends AbstractContext
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 class MessageContext extends AbstractContext
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;
}
diff --git a/modules/kernel/src/org/apache/axis2/engine/Phase.java
b/modules/kernel/src/org/apache/axis2/engine/Phase.java
index f780dfc022..2364c9dcdc 100644
--- a/modules/kernel/src/org/apache/axis2/engine/Phase.java
+++ b/modules/kernel/src/org/apache/axis2/engine/Phase.java
@@ -342,7 +342,15 @@ public class Phase implements Handler {
}
// 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();
