org.springframework.webflow.engine
Class State

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

All Implemented Interfaces:

Annotated, StateDefinition

Direct Known Subclasses:

EndState, TransitionableState

public abstract class State
extends AnnotatedObject
implements StateDefinition

A point in a flow where something happens. What happens is determined by a state's type. Standard types of states include action states, view states, subflow states, and end states.

Each state is associated with exactly one owning flow definition. Specializations of this class capture all the configuration information needed for a specific kind of state.

Subclasses should implement the doEnter method to execute the processing that should occur when this state is entered, acting on its configuration information. The ability to plugin custom state types that execute different behaviour polymorphically is the classic GoF state pattern.

Equality: Two states are equal if they have the same id and are part of the same flow.

Author:

Keith Donald, Erwin Vervaet

See Also:

TransitionableState, ActionState, ViewState, SubflowState, EndState, DecisionState

Field Summary

protected org.apache.commons.logging.Log

logger Logger, for use in subclasses.

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

CAPTION_PROPERTY, DESCRIPTION_PROPERTY

Constructor Summary

protected

State(Flow flow, java.lang.String id) Creates a state for the provided flow identified by the provided id.

Method Summary

protected void	appendToString(org.springframework.core.style.ToStringCreator creator) Subclasses may override this hook method to stringify their internal state.
protected abstract ViewSelection	doEnter(RequestControlContext context) Hook method to execute custom behaviour as a result of entering this state.
ViewSelection	enter(RequestControlContext context) Enter this state in the provided flow control context.
boolean	equals(java.lang.Object o)
ActionList	getEntryActionList() Returns the list of actions executed by this state when it is entered.
FlowExecutionExceptionHandlerSet	getExceptionHandlerSet() Returns a mutable set of exception handlers, allowing manipulation of how exceptions are handled when thrown within this state.
Flow	getFlow() Returns the owning flow.
java.lang.String	getId() Returns this state's identifier, locally unique to is containing flow definition.
FlowDefinition	getOwner() Returns the flow definition this state belongs to.
ViewSelection	handleException(FlowExecutionException exception, RequestControlContext context) Handle an exception that occured in this state during the context of the current flow execution request.
int	hashCode()
boolean	isStartState() Returns a flag indicating if this state is the start state of its owning flow.
java.lang.String	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.Annotated

getAttributes, getCaption, getDescription

Field Detail

logger

protected final org.apache.commons.logging.Log logger

Logger, for use in subclasses.

Constructor Detail

State

protected State(Flow flow,
                java.lang.String id)
         throws java.lang.IllegalArgumentException

Creates a state for the provided flow identified by the provided id. The id must be locally unique to the owning flow. The state will be automatically added to the flow.

Parameters:

flow - the owning flow

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

Throws:

java.lang.IllegalArgumentException - if this state cannot be added to the flow, for instance when the provided id is not unique in the owning flow

See Also:

getEntryActionList(), getExceptionHandlerSet()

Method Detail

getOwner

public FlowDefinition getOwner()

Description copied from interface: StateDefinition

Returns the flow definition this state belongs to.

Specified by:

getOwner in interface StateDefinition

Returns:

the owning flow definition

getId

public java.lang.String getId()

Description copied from interface: StateDefinition

Returns this state's identifier, locally unique to is containing flow definition.

Specified by:

getId in interface StateDefinition

Returns:

the state identifier

getFlow

public Flow getFlow()

Returns the owning flow.

getEntryActionList

public ActionList getEntryActionList()

Returns the list of actions executed by this state when it is entered. The returned list is mutable.

Returns:

the state entry action list

getExceptionHandlerSet

public FlowExecutionExceptionHandlerSet getExceptionHandlerSet()

Returns a mutable set of exception handlers, allowing manipulation of how exceptions are handled when thrown within this state.

Exception handlers are invoked when an exception occurs when this state is entered, and can execute custom exception handling logic as well as select an error view to display.

Returns:

the state exception handler set

isStartState

public boolean isStartState()

Returns a flag indicating if this state is the start state of its owning flow.

Returns:

true if the flow is the start state, false otherwise

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

enter

public final ViewSelection enter(RequestControlContext context)
                          throws FlowExecutionException

Enter this state in the provided flow control context. This implementation just calls the doEnter(RequestControlContext) hook method, which should be implemented by subclasses, after executing the entry actions.

Parameters:

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

Returns:

a view selection containing model and view information needed to render the results of the state processing

Throws:

FlowExecutionException - if an exception occurs in this state

doEnter

protected abstract ViewSelection doEnter(RequestControlContext context)
                                  throws FlowExecutionException

Hook method to execute custom behaviour as a result of entering this state. By implementing this method subclasses specialize the behaviour of the state.

Parameters:

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

Returns:

a view selection containing model and view information needed to render the results of the state processing

Throws:

FlowExecutionException - if an exception occurs in this state

handleException

public ViewSelection handleException(FlowExecutionException exception,
                                     RequestControlContext context)

Handle an exception that occured in this state during the context of the current flow execution request.

Parameters:

exception - the exception that occured

context - the flow execution control context

Returns:

the selected error view, or null if no handler matched or returned a non-null view selection

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

appendToString

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

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

Parameters:

creator - the toString creator, to stringify properties