org.springframework.webflow.engine
Class State

java.lang.Object
  org.springframework.webflow.core.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 plug-in custom state types that execute different behaviors 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.core.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 print their internal state to a string.
protected abstract void	doEnter(RequestControlContext context) Hook method to execute custom behavior as a result of entering this state.
protected void	doPreEntryActions(RequestControlContext context) Hook method to execute before running state entry actions upon state entry.
void	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.
boolean	handleException(FlowExecutionException exception, RequestControlContext context) Handle an exception that occurred 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.
boolean	isViewState() Returns true if this state is a view state.
java.lang.String	toString()

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

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.core.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

isViewState

public boolean isViewState()

Description copied from interface: StateDefinition

Returns true if this state is a view state.

Specified by:

isViewState in interface StateDefinition

Returns:

true if a view state, false otherwise

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 void 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

Throws:

FlowExecutionException - if an exception occurs in this state

doPreEntryActions

protected void doPreEntryActions(RequestControlContext context)
                          throws FlowExecutionException

Hook method to execute before running state entry actions upon state entry. Does nothing by default. Subclasses may override.

Parameters:

context - the request control context

Throws:

FlowExecutionException - if an exception occurs

doEnter

protected abstract void doEnter(RequestControlContext context)
                         throws FlowExecutionException

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

Parameters:

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

Throws:

FlowExecutionException - if an exception occurs in this state

handleException

public boolean handleException(FlowExecutionException exception,
                               RequestControlContext context)

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

Parameters:

exception - the exception that occurred

context - the flow execution control context

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 print their internal state to a string. This default implementation does nothing.

Parameters:

creator - the toString creator, to print properties to string

See Also:

toString()