Package org.apache.struts2

# Interface ActionInvocation

All Known Implementing Classes:
  `DefaultActionInvocation`, `MockActionInvocation`

public interface ActionInvocation
An `ActionInvocation` represents the execution state of an `Action`. It holds the Interceptors and the Action instance. By repeated re-entrant execution of the `invoke()` method, initially by the `ActionProxy`, then by the Interceptors, the Interceptors are all executed, and then the `Action` and the `Result`.

Author:
  Jason Carreira
See Also:
  - `ActionProxy`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addPreResultListener(PreResultListener listener)`
  Register a `PreResultListener` to be notified after the Action is executed and before the Result is executed.
  `Object`
  `getAction()`
  Get the Action associated with this ActionInvocation.
  `ActionContext`
  `getInvocationContext()`
  Gets the ActionContext associated with this ActionInvocation.
  `ActionProxy`
  `getProxy()`
  Get the ActionProxy holding this ActionInvocation.
  `Result`
  `getResult()`
  If the ActionInvocation has been executed before and the Result is an instance of `ActionChainResult`, this method will walk down the chain of `ActionChainResult`s until it finds a non-chain result, which will be returned.
  `String`
  `getResultCode()`
  Gets the result code returned from this ActionInvocation.
  `ValueStack`
  `getStack()`
  Gets the ValueStack associated with this ActionInvocation.
  `void`
  `init(ActionProxy proxy)`
  `String`
  `invoke()`
  Invokes the next step in processing this ActionInvocation.
  `String`
  `invokeActionOnly()`
  Invokes only the Action (not Interceptors or Results).
  `boolean`
  `isExecuted()`
  Gets whether this ActionInvocation has executed before.
  `void`
  `setActionEventListener(ActionEventListener listener)`
  Sets the action event listener to respond to key action events.
  `void`
  `setResultCode(String resultCode)`
  Sets the result code, possibly overriding the one returned by the action.

- ## Method Details

  - ### getAction

    Object getAction()
    Get the Action associated with this ActionInvocation.
    Returns:
      the Action

  - ### isExecuted

    boolean isExecuted()
    Gets whether this ActionInvocation has executed before. This will be set after the Action and the Result have executed.
    Returns:
      `true` if this ActionInvocation has executed before.

  - ### getInvocationContext

    ActionContext getInvocationContext()
    Gets the ActionContext associated with this ActionInvocation. The ActionProxy is responsible for setting this ActionContext onto the ThreadLocal before invoking the ActionInvocation and resetting the old ActionContext afterwards.
    Returns:
      the ActionContext.

  - ### getProxy

    ActionProxy getProxy()
    Get the ActionProxy holding this ActionInvocation.
    Returns:
      the ActionProxy.

  - ### getResult

    Result getResult() throws Exception
    If the ActionInvocation has been executed before and the Result is an instance of `ActionChainResult`, this method will walk down the chain of `ActionChainResult`s until it finds a non-chain result, which will be returned. If the ActionInvocation's result has not been executed before, the Result instance will be created and populated with the result params.
    Returns:
      the result.
    Throws:
      `Exception` - can be thrown.

  - ### getResultCode

    String getResultCode()
    Gets the result code returned from this ActionInvocation.
    Returns:
      the result code

  - ### setResultCode

    void setResultCode(String resultCode)
    Sets the result code, possibly overriding the one returned by the action.

    The "intended" purpose of this method is to allow PreResultListeners to override the result code returned by the Action.

    If this method is used before the Action executes, the Action's returned result code will override what was set. However the Action could (if specifically coded to do so) inspect the ActionInvocation to see that someone "upstream" (e.g. an Interceptor) had suggested a value as the result, and it could therefore return the same value itself.

    If this method is called between the Action execution and the Result execution, then the value set here will override the result code the action had returned. Creating an Interceptor that implements `PreResultListener` will give you this opportunity.

    If this method is called after the Result has been executed, it will have the effect of raising an IllegalStateException.

    Parameters:
      `resultCode` - the result code.
    Throws:
      `IllegalStateException` - if called after the Result has been executed.
    See Also:
      - `isExecuted()`

  - ### getStack

    ValueStack getStack()
    Gets the ValueStack associated with this ActionInvocation.
    Returns:
      the ValueStack

  - ### addPreResultListener

    void addPreResultListener(PreResultListener listener)
    Register a `PreResultListener` to be notified after the Action is executed and before the Result is executed.

    The ActionInvocation implementation must guarantee that listeners will be called in the order in which they are registered.

    Listener registration and execution does not need to be thread-safe.

    Parameters:
      `listener` - the listener to add.

  - ### invoke

    String invoke() throws Exception
    Invokes the next step in processing this ActionInvocation.

    If there are more Interceptors, this will call the next one. If Interceptors choose not to short-circuit ActionInvocation processing and return their own return code, they will call invoke() to allow the next Interceptor to execute. If there are no more Interceptors to be applied, the Action is executed. If the `ActionProxy.getExecuteResult()` method returns `true`, the Result is also executed.

    Returns:
      the return code.
    Throws:
      `Exception` - can be thrown.

  - ### invokeActionOnly

    String invokeActionOnly() throws Exception
    Invokes only the Action (not Interceptors or Results).

    This is useful in rare situations where advanced usage with the interceptor/action/result workflow is being manipulated for certain functionality.

    Returns:
      the return code.
    Throws:
      `Exception` - can be thrown.

  - ### setActionEventListener

    void setActionEventListener(ActionEventListener listener)
    Sets the action event listener to respond to key action events.
    Parameters:
      `listener` - the listener.

  - ### init

    void init(ActionProxy proxy)