org.springframework.webflow.engine.impl
Class FlowExecutionImpl

java.lang.Object
  org.springframework.webflow.engine.impl.FlowExecutionImpl

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, FlowExecution, FlowExecutionContext

public class FlowExecutionImpl
extends java.lang.Object
implements FlowExecution, java.io.Externalizable

Default implementation of FlowExecution that uses a stack-based data structure to manage spawned flow sessions. This class is closely coupled with package-private FlowSessionImpl and RequestControlContextImpl. The three classes work together to form a complete flow execution implementation based on a finite state machine.

This implementation of FlowExecution is serializable so it can be safely stored in an HTTP session or other persistent store such as a file, database, or client-side form field. Once deserialized, the FlowExecutionImplStateRestorer strategy is expected to be used to restore the execution to a usable state.

Author:

Keith Donald, Erwin Vervaet, Ben Hale

See Also:

FlowExecutionImplFactory, FlowExecutionImplStateRestorer, Serialized Form

Constructor Summary

FlowExecutionImpl()
Default constructor required for externalizable serialization.

FlowExecutionImpl(Flow flow)
Create a new flow execution executing the provided flow.

FlowExecutionImpl(Flow flow, FlowExecutionListener[] listeners, AttributeMap attributes)
Create a new flow execution executing the provided flow.

Method Summary

protected FlowSession	activateSession(Flow flow) Activate a new FlowSession for the flow definition.
protected RequestControlContext	createControlContext(ExternalContext externalContext) Create a flow execution control context.
FlowSession	endActiveFlowSession() End the active flow session, popping it of the stack.
FlowSession	getActiveSession() Returns the active flow session of this flow execution.
AttributeMap	getAttributes() Returns runtime execution attributes that may influence the behavior of flow artifacts, such as states and actions.
java.lang.String	getCaption()
MutableAttributeMap	getConversationScope() Returns a mutable map for data held in "conversation scope".
FlowDefinition	getDefinition() Returns the root flow definition associated with this executing flow.
protected ViewSelection	handleException(FlowExecutionException exception, RequestControlContext context) Handles an exception that occured performing an operation on this flow execution.
boolean	isActive() Is the flow execution active?
protected ViewSelection	pause(RequestControlContext context, ViewSelection selectedView) Pause this flow execution.
void	readExternal(java.io.ObjectInput in)
ViewSelection	refresh(ExternalContext externalContext) Refresh this flow execution, asking the current view selection to be reconstituted to support reissuing the last response.
protected void	resume(RequestControlContext context) Resume this flow execution.
protected void	setCurrentState(State newState) Set the state that is currently active in this flow execution.
ViewSelection	signalEvent(java.lang.String eventId, ExternalContext externalContext) Signal an occurrence of the specified user event in the current state of this executing flow.
ViewSelection	start(MutableAttributeMap input, ExternalContext externalContext) Start this flow execution, transitioning it to the root flow's start state and returning the starting view selection needed to issue an initial user response.
java.lang.String	toString()
void	writeExternal(java.io.ObjectOutput out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FlowExecutionImpl

public FlowExecutionImpl()

Default constructor required for externalizable serialization. Should NOT be called programmatically.

FlowExecutionImpl

public FlowExecutionImpl(Flow flow)

Create a new flow execution executing the provided flow. This constructor is mainly used for testing.

Parameters:

flow - the root flow of this flow execution

FlowExecutionImpl

public FlowExecutionImpl(Flow flow,
                         FlowExecutionListener[] listeners,
                         AttributeMap attributes)

Create a new flow execution executing the provided flow.

Parameters:

flow - the root flow of this flow execution

listeners - the listeners interested in flow execution lifecycle events

attributes - flow execution system attributes

Method Detail

getCaption

public java.lang.String getCaption()

getDefinition

public FlowDefinition getDefinition()

Description copied from interface: FlowExecutionContext

Returns the root flow definition associated with this executing flow.

A call to this method always returns the same flow definition -- the top-level "root" -- no matter what flow may actually be active (for example, if subflows have been spawned).

Specified by:

getDefinition in interface FlowExecutionContext

Returns:

the root flow definition

isActive

public boolean isActive()

Description copied from interface: FlowExecutionContext

Is the flow execution active?

All methods on an active flow execution context can be called successfully. If the flow execution is not active, a caller cannot access some methods such as FlowExecutionContext.getActiveSession().

Specified by:

isActive in interface FlowExecutionContext

Returns:

true if active, false if the flow execution has terminated

getActiveSession

public FlowSession getActiveSession()

Description copied from interface: FlowExecutionContext

Returns the active flow session of this flow execution. The active flow session is the currently executing session -- it may be the "root flow" session, or it may be a subflow session if this flow execution has spawned a subflow.

Specified by:

getActiveSession in interface FlowExecutionContext

Returns:

the active flow session

getConversationScope

public MutableAttributeMap getConversationScope()

Description copied from interface: FlowExecutionContext

Returns a mutable map for data held in "conversation scope". Conversation scope is a data structure that exists for the life of this flow execution and is accessible to all flow sessions.

Specified by:

getConversationScope in interface FlowExecutionContext

Returns:

conversation scope

getAttributes

public AttributeMap getAttributes()

Description copied from interface: FlowExecutionContext

Returns runtime execution attributes that may influence the behavior of flow artifacts, such as states and actions.

Specified by:

getAttributes in interface FlowExecutionContext

Returns:

execution attributes

start

public ViewSelection start(MutableAttributeMap input,
                           ExternalContext externalContext)
                    throws FlowExecutionException

Description copied from interface: FlowExecution

Start this flow execution, transitioning it to the root flow's start state and returning the starting view selection needed to issue an initial user response. Typically called by a flow executor on behalf of a browser client, but also from test code.

This will start the entire flow execution from scratch.

Specified by:

start in interface FlowExecution

Parameters:

input - input attributes to pass to the flow, which the flow may choose to map into its scope

externalContext - the external context in which the starting event occured

Returns:

the starting view selection, a value object to be used to issue a suitable response to the caller

Throws:

FlowExecutionException - if an exception was thrown within a state of the flow execution during request processing

signalEvent

public ViewSelection signalEvent(java.lang.String eventId,
                                 ExternalContext externalContext)
                          throws FlowExecutionException

Description copied from interface: FlowExecution

Signal an occurrence of the specified user event in the current state of this executing flow. The event will be processed in full and control will be returned once event processing is complete.

Specified by:

signalEvent in interface FlowExecution

Parameters:

eventId - the identifier of the user event that occured

externalContext - the external context in which the event occured

Returns:

the next view selection to render, used by the calling executor to issue a suitable response to the client

Throws:

FlowExecutionException - if an exception was thrown within a state of the resumed flow execution during event processing

refresh

public ViewSelection refresh(ExternalContext externalContext)
                      throws FlowExecutionException

Description copied from interface: FlowExecution

Refresh this flow execution, asking the current view selection to be reconstituted to support reissuing the last response. This is an idempotent operation that may be safely called on a paused execution.

Specified by:

refresh in interface FlowExecution

Parameters:

externalContext - the externa context in which the refresh event occured

Returns:

the current view selection for this flow execution

Throws:

FlowExecutionException - if an exception was thrown within a state of the resumed flow execution during event processing

resume

protected void resume(RequestControlContext context)

Resume this flow execution.

Parameters:

context - the state request context

pause

protected ViewSelection pause(RequestControlContext context,
                              ViewSelection selectedView)

Pause this flow execution.

Parameters:

context - the request control context

selectedView - the initial selected view to render

Returns:

the selected view to render

handleException

protected ViewSelection handleException(FlowExecutionException exception,
                                        RequestControlContext context)
                                 throws FlowExecutionException

Handles an exception that occured performing an operation on this flow execution. First trys the set of exception handlers associated with the offending state, then the handlers at the flow level.

Parameters:

exception - the exception that occured

context - the request control context the exception occured in

Returns:

the selected error view, never null

Throws:

FlowExecutionException - rethrows the exception if it was not handled at the state or flow level

createControlContext

protected RequestControlContext createControlContext(ExternalContext externalContext)

Create a flow execution control context.

Parameters:

externalContext - the external context triggering this request

setCurrentState

protected void setCurrentState(State newState)

Set the state that is currently active in this flow execution.

Parameters:

newState - the new current state

activateSession

protected FlowSession activateSession(Flow flow)

Activate a new FlowSession for the flow definition. Creates the new flow session and pushes it onto the stack.

Parameters:

flow - the flow definition

Returns:

the new flow session

endActiveFlowSession

public FlowSession endActiveFlowSession()

End the active flow session, popping it of the stack.

Returns:

the ended session

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException

Specified by:

readExternal in interface java.io.Externalizable

Throws:

java.io.IOException

java.lang.ClassNotFoundException

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException

Specified by:

writeExternal in interface java.io.Externalizable

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object