org.springframework.webflow.engine
Class ActionState

java.lang.Object
  org.springframework.webflow.engine.AnnotatedObject
      org.springframework.webflow.engine.State
          org.springframework.webflow.engine.TransitionableState
              org.springframework.webflow.engine.ActionState

All Implemented Interfaces:

Annotated, StateDefinition, TransitionableStateDefinition

public class ActionState
extends TransitionableState

A transitionable state that executes one or more actions when entered. When the action(s) are executed this state responds to their result(s) to decide what state to transition to next.

If more than one action is configured they are executed in an ordered chain until one returns a result event that matches a state transition out of this state. This is a form of the Chain of Responsibility (CoR) pattern.

The result of an action's execution is typically the criteria for a transition out of this state. Additional information in the current RequestContext may also be tested as part of custom transitional criteria, allowing for sophisticated transition expressions that reason on contextual state.

Each action executed by this action state may be provisioned with a set of arbitrary execution properties. These properties are made available to the action at execution time and may be used to influence action execution behavior.

Common action execution properties include:

Property	Description
name	The 'name' property is used as a qualifier for an action's result event, and is typically used to allow the flow to respond to a specific action's outcome within a larger action chain. For example, if an action named myAction returns a success result, a transition that matches on event myAction.success will be searched, and if found, executed. If this action is not assigned a name a transition for the base success event will be searched and if found, executed. This is useful in situations where you want to execute actions in an ordered chain as part of one action state, and wish to transition on the result of the last one in the chain. For example: <action-state id="setupForm"> <action name="setup" bean="myAction" method="setupForm"/> <action name="referenceData" bean="myAction" method="setupReferenceData"/> <transition on="referenceData.success" to="displayForm"/> </action-state> When the 'setupForm' state above is entered, the 'setup' action will execute, followed by the 'referenceData' action. After 'referenceData' execution, the flow will then respond to the 'referenceData.success' event by transitioning to the 'displayForm' state. The 'setup.success' event that was signaled by the 'setup' action will effectively be ignored.
method	The 'method' property is the name of a target method on a MultiAction to execute. In the MultiAction scenario the named method must have the signature public Event ${method}(RequestContext) throws Exception. As an example of this scenario, a method property with value setupForm would bind to a method on a MultiAction instance with the signature: public Event setupForm(RequestContext context). As an alternative to a MultiAction method binding, this action state may excute a bean invoking action that invokes a method on a POJO (Plain Old Java Object). If the method signature accepts arguments those arguments may be specified by using the format: methodName(${arg1}, ${arg2}, ...) Argument ${expressions} are evaluated against the current RequestContext, allowing for data stored in flow scope or request scope to be passed as arguments to the POJO. In addition, POJO return values may be exposed to the flow automatically. See the bean invoking action type hierarchy for more information.

Author:

Keith Donald, Erwin Vervaet

See Also:

Action, MultiAction, AbstractBeanInvokingAction

Field Summary

Fields inherited from class org.springframework.webflow.engine.State

logger

Fields inherited from class org.springframework.webflow.engine.AnnotatedObject

CAPTION_PROPERTY, DESCRIPTION_PROPERTY

Constructor Summary

ActionState(Flow flow, java.lang.String id)
Creates a new action state.

Method Summary

protected void	appendToString(org.springframework.core.style.ToStringCreator creator) Subclasses may override this hook method to stringify their internal state.
protected ViewSelection	doEnter(RequestControlContext context) Specialization of State's doEnter template method that executes behaviour specific to this state type in polymorphic fashion.
ActionList	getActionList() Returns the list of actions executable by this action state.
Transition	getRequiredTransition(RequestContext context) Get a transition in this state for given flow execution request context.

Methods inherited from class org.springframework.webflow.engine.TransitionableState

exit, getExitActionList, getTransitions, getTransitionSet, onEvent, reenter

Methods inherited from class org.springframework.webflow.engine.State

enter, equals, getEntryActionList, getExceptionHandlerSet, getFlow, getId, getOwner, handleException, hashCode, isStartState, toString

Methods inherited from class org.springframework.webflow.engine.AnnotatedObject

getAttributeMap, getAttributes, getCaption, getDescription, setCaption, setDescription

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.springframework.webflow.definition.StateDefinition

getId, getOwner

Methods inherited from interface org.springframework.webflow.definition.Annotated

getAttributes, getCaption, getDescription

Constructor Detail

ActionState

public ActionState(Flow flow,
                   java.lang.String id)
            throws java.lang.IllegalArgumentException

Creates a new action state.

Parameters:

flow - the owning flow

id - the state identifier (must be unique to the flow)

Throws:

java.lang.IllegalArgumentException - when this state cannot be added to given flow, e.g. beasue the id is not unique

See Also:

getActionList()

Method Detail

getActionList

public ActionList getActionList()

Returns the list of actions executable by this action state. The returned list is mutable.

Returns:

the state action list

getRequiredTransition

public Transition getRequiredTransition(RequestContext context)
                                 throws NoMatchingTransitionException

Description copied from class: TransitionableState

Get a transition in this state for given flow execution request context. Throws and exception when there is no corresponding transition.

Overrides:

getRequiredTransition in class TransitionableState

Throws:

NoMatchingTransitionException - when a matching transition cannot be found

doEnter

protected ViewSelection doEnter(RequestControlContext context)
                         throws FlowExecutionException

Specialization of State's doEnter template method that executes behaviour specific to this state type in polymorphic fashion.

This implementation iterates over each configured Action instance and executes it. Execution continues until an Action returns a result event that matches a transition in this request context, or the set of all actions is exhausted.

Specified by:

doEnter in class State

Parameters:

context - the control context for the currently executing flow, used by this state to manipulate the flow execution

Returns:

a view selection signaling that control should be returned to the client and a view rendered

Throws:

FlowExecutionException - if an exception occurs in this state

appendToString

protected void appendToString(org.springframework.core.style.ToStringCreator creator)

Description copied from class: State

Subclasses may override this hook method to stringify their internal state. This default implementation does nothing.

Overrides:

appendToString in class TransitionableState

Parameters:

creator - the toString creator, to stringify properties