org.springframework.webflow.execution
Class FlowExecutionManager

java.lang.Object
  org.springframework.webflow.execution.FlowExecutionManager

All Implemented Interfaces:

org.springframework.beans.factory.BeanFactoryAware, FlowExecutionListenerLoader

Direct Known Subclasses:

ServletFlowExecutionManager

public class FlowExecutionManager
extends java.lang.Object
implements org.springframework.beans.factory.BeanFactoryAware, FlowExecutionListenerLoader

A manager for the executing flows of the application. This object is responsible for creating new flow executions as requested by the client, as well as signaling events for processing by existing, paused executions (that are waiting to be resumed in response to a user event).

The onEvent(Event) method implements the following algorithm:

1. Look for a flow execution id in the event (in a parameter named "_flowExecutionId").
2. If no flow execution id is found, a new flow execution is created. The top-level flow for which the execution is created is determined by first looking for a flow id specified in the event using the "_flowId" parameter. If this parameter is present the specified flow will be used, after lookup using a flow locator. If no "_flowId" parameter is present, the default top-level flow configured for this manager is used.
3. If a flow execution id is found, the previously saved flow execution with that id is loaded from the storage.
4. If a new flow execution was created in the previous steps, it is started.
5. If an existing flow execution was loaded from storage, the current state id ("_currentStateId") and event id ("_eventId") parameter values are extracted from the event. The event is then signaled in that state, and the executing flow is resumed in that state.
6. If the flow execution is still active after event processing, it is saved in storage. This process generates a unique flow execution id that will be exposed to the caller for reference on subsequent events. The caller will also be given access to the flow execution context and any data placed in request or flow scope.

By default, this class will use the flow execution implementation provided by the FlowExecutionImpl class. If you would like to use a different implementation, just override the createFlowExecution(Flow) method in a subclass.

Author:

Erwin Vervaet, Keith Donald

See Also:

FlowExecution, FlowExecutionStorage

Field Summary

static java.lang.String	CURRENT_STATE_ID_ATTRIBUTE The current state of the flow execution will be exposed to the view in a model attribute with this name ("currentStateId").
static java.lang.String	FLOW_EXECUTION_CONTEXT_ATTRIBUTE The flow context itself will be exposed to the view in a model attribute with this name ("flowExecutionContext").
static java.lang.String	FLOW_EXECUTION_ID_ATTRIBUTE The id of the flow execution will be exposed to the view in a model attribute with this name ("flowExecutionId").
static java.lang.String	FLOW_EXECUTION_ID_PARAMETER Clients can send the flow execution id using an event parameter with this name ("_flowExecutionId").
static java.lang.String	FLOW_ID_PARAMETER Clients can send the id (name) of the flow to be started using an event parameter with this name ("_flowId").
protected org.apache.commons.logging.Log	logger
static java.lang.String	NOT_SET_EVENT_ID Event id value indicating that the event has not been set ("@NOT_SET@").

Constructor Summary

FlowExecutionManager()
Create a new flow execution manager.

Method Summary

void	addListener(FlowExecutionListener listener) Add a listener that will listen to executions for all flows.
void	addListener(FlowExecutionListener listener, FlowExecutionListenerCriteria criteria) Add a listener that wil listen to executions to flows matching the specified criteria
protected FlowExecution	createFlowExecution(Flow flow) Create a new flow execution for given flow.
protected org.springframework.beans.factory.BeanFactory	getBeanFactory() Returns this flow execution manager's bean factory.
org.springframework.binding.convert.ConversionService	getConversionService() Returns the conversion service used by this flow execution manager.
protected Flow	getFlow() Returns the flow whose executions are managed by this manager.
protected Flow	getFlow(Event event) Obtain a flow to use from given event.
protected java.lang.String	getFlowExecutionId(Event event) Obtain a unique flow execution id from given event.
protected java.lang.String	getFlowExecutionIdParameterName() Returns the name of the flow execution id parameter in the event ("_flowExecutionId").
protected java.lang.String	getFlowIdParameterName() Returns the name of the flow id parameter in the event ("_flowId").
protected FlowLocator	getFlowLocator() Returns the flow locator to use for lookup of flows specified using the "_flowId" event parameter.
FlowExecutionListener[]	getListeners(Flow flow) Returns the array of flow execution listeners for specified flow.
protected java.lang.String	getNotSetEventIdParameterMarker() Returns the marker value indicating that the event id parameter was not set properly in the event because of a view configuration error ("@NOT_SET@").
protected FlowExecutionStorage	getStorage() Returns the storage strategy used by the flow execution manager.
protected TransactionSynchronizer	getTransactionSynchronizer() Return the application transaction synchronization strategy to use.
ViewDescriptor	onEvent(Event event) Signal the occurence of the specified event - this is the entry point into the webflow system for managing all executing flows.
ViewDescriptor	onEvent(Event event, FlowExecutionListener listener) Signal the occurence of the specified event - this is the entry point into the webflow system for managing all executing flows.
protected ViewDescriptor	prepareViewDescriptor(ViewDescriptor viewDescriptor, java.io.Serializable flowExecutionId, FlowExecutionContext flowExecutionContext) Do any processing necessary before given view descriptor can be returned to the client of the flow execution manager.
void	removeListener(FlowExecutionListener listener) Remove the flow execution listener from the listener list.
void	setBeanFactory(org.springframework.beans.factory.BeanFactory beanFactory)
void	setConversionService(org.springframework.binding.convert.ConversionService conversionService) Set the conversion service used by this flow execution manager.
void	setFlow(Flow flow) Set the flow whose executions will be managed if there is no alternate flow id specified in a "_flowId" event parameter.
void	setFlowLocator(FlowLocator flowLocator) Set the flow locator to use for lookup of flows specified using the "_flowId" event parameter.
void	setListener(FlowExecutionListener listener) Set the flow execution listener that will be notified of managed flow executions.
void	setListener(FlowExecutionListener listener, FlowExecutionListenerCriteria criteria) Set the flow execution listener that will be notified of managed flow executions for the flows that match given criteria.
void	setListenerMap(java.util.Map listenerCriteriaMap) Sets the flow execution listeners that will be notified of managed flow executions.
void	setListeners(java.util.Collection listeners) Sets the flow execution listeners that will be notified of managed flow executions.
void	setListeners(java.util.Collection listeners, FlowExecutionListenerCriteria criteria) Sets the flow execution listeners that will be notified of managed flow executions for flows that match given criteria.
void	setStorage(FlowExecutionStorage storage) Set the storage strategy used by the flow execution manager.
void	setTransactionSynchronizer(TransactionSynchronizer transactionSynchronizer) Set the application transaction synchronization strategy to use.

Methods inherited from class java.lang.Object

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

Field Detail

FLOW_ID_PARAMETER

public static final java.lang.String FLOW_ID_PARAMETER

Clients can send the id (name) of the flow to be started using an event parameter with this name ("_flowId").

See Also:

Constant Field Values

FLOW_EXECUTION_ID_PARAMETER

public static final java.lang.String FLOW_EXECUTION_ID_PARAMETER

Clients can send the flow execution id using an event parameter with this name ("_flowExecutionId").

See Also:

Constant Field Values

FLOW_EXECUTION_ID_ATTRIBUTE

public static final java.lang.String FLOW_EXECUTION_ID_ATTRIBUTE

The id of the flow execution will be exposed to the view in a model attribute with this name ("flowExecutionId").

See Also:

Constant Field Values

FLOW_EXECUTION_CONTEXT_ATTRIBUTE

public static final java.lang.String FLOW_EXECUTION_CONTEXT_ATTRIBUTE

The flow context itself will be exposed to the view in a model attribute with this name ("flowExecutionContext").

See Also:

Constant Field Values

CURRENT_STATE_ID_ATTRIBUTE

public static final java.lang.String CURRENT_STATE_ID_ATTRIBUTE

The current state of the flow execution will be exposed to the view in a model attribute with this name ("currentStateId").

See Also:

Constant Field Values

NOT_SET_EVENT_ID

public static final java.lang.String NOT_SET_EVENT_ID

Event id value indicating that the event has not been set ("@NOT_SET@").

See Also:

Constant Field Values

logger

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

Constructor Detail

FlowExecutionManager

public FlowExecutionManager()

Create a new flow execution manager. Before use, the manager should be appropriately configured using setter methods. At least the flow execution storage strategy should be set!

See Also:

setFlow(Flow), setFlowLocator(FlowLocator), setListener(FlowExecutionListener), setListener(FlowExecutionListener, FlowExecutionListenerCriteria), setListenerMap(Map), setListeners(Collection), setListeners(Collection, FlowExecutionListenerCriteria), setStorage(FlowExecutionStorage), setTransactionSynchronizer(TransactionSynchronizer), setConversionService(ConversionService)

Method Detail

getFlow

protected Flow getFlow()

Returns the flow whose executions are managed by this manager. Could be null if there is no preconfigured flow and the id of the flow for which executions will be managed is sent in an event parameter "_flowId".

setFlow

public void setFlow(Flow flow)

Set the flow whose executions will be managed if there is no alternate flow id specified in a "_flowId" event parameter.

getFlowLocator

protected FlowLocator getFlowLocator()

Returns the flow locator to use for lookup of flows specified using the "_flowId" event parameter.

setFlowLocator

public void setFlowLocator(FlowLocator flowLocator)

Set the flow locator to use for lookup of flows specified using the "_flowId" event parameter.

getListeners

public FlowExecutionListener[] getListeners(Flow flow)

Returns the array of flow execution listeners for specified flow.

Specified by:

getListeners in interface FlowExecutionListenerLoader

Parameters:

flow - the flow definition associated with the execution to be listened to

Returns:

the flow execution listeners

setListener

public void setListener(FlowExecutionListener listener)

Set the flow execution listener that will be notified of managed flow executions.

setListener

public void setListener(FlowExecutionListener listener,
                        FlowExecutionListenerCriteria criteria)

Set the flow execution listener that will be notified of managed flow executions for the flows that match given criteria.

setListeners

public void setListeners(java.util.Collection listeners)

Sets the flow execution listeners that will be notified of managed flow executions.

setListeners

public void setListeners(java.util.Collection listeners,
                         FlowExecutionListenerCriteria criteria)

Sets the flow execution listeners that will be notified of managed flow executions for flows that match given criteria.

setListenerMap

public void setListenerMap(java.util.Map listenerCriteriaMap)

Sets the flow execution listeners that will be notified of managed flow executions. The map keys may be individual flow execution listener instances or collections of execution listener instances. The map values can either be string encoded flow execution listener criteria or direct FlowExecutionListenerCriteria objects.

addListener

public void addListener(FlowExecutionListener listener)

Add a listener that will listen to executions for all flows.

Parameters:

listener - the listener to add

addListener

public void addListener(FlowExecutionListener listener,
                        FlowExecutionListenerCriteria criteria)

Add a listener that wil listen to executions to flows matching the specified criteria

Parameters:

listener - the listener

criteria - the listener criteria

removeListener

public void removeListener(FlowExecutionListener listener)

Remove the flow execution listener from the listener list.

Parameters:

listener - the listener

getStorage

protected FlowExecutionStorage getStorage()

Returns the storage strategy used by the flow execution manager.

setStorage

public void setStorage(FlowExecutionStorage storage)

Set the storage strategy used by the flow execution manager.

getTransactionSynchronizer

protected TransactionSynchronizer getTransactionSynchronizer()

Return the application transaction synchronization strategy to use. This defaults to a synchronizer token based transaction management system, as implemented by FlowScopeTokenTransactionSynchronizer.

setTransactionSynchronizer

public void setTransactionSynchronizer(TransactionSynchronizer transactionSynchronizer)

Set the application transaction synchronization strategy to use.

getConversionService

public org.springframework.binding.convert.ConversionService getConversionService()

Returns the conversion service used by this flow execution manager.

setConversionService

public void setConversionService(org.springframework.binding.convert.ConversionService conversionService)

Set the conversion service used by this flow execution manager.

getBeanFactory

protected org.springframework.beans.factory.BeanFactory getBeanFactory()

Returns this flow execution manager's bean factory.

setBeanFactory

public void setBeanFactory(org.springframework.beans.factory.BeanFactory beanFactory)
                    throws org.springframework.beans.BeansException

Specified by:

setBeanFactory in interface org.springframework.beans.factory.BeanFactoryAware

Throws:

org.springframework.beans.BeansException

onEvent

public ViewDescriptor onEvent(Event event)
                       throws java.lang.Exception

Signal the occurence of the specified event - this is the entry point into the webflow system for managing all executing flows.

Parameters:

event - the event that occured

Returns:

the view descriptor of the model and view to render

Throws:

java.lang.Exception - in case of errors

onEvent

public ViewDescriptor onEvent(Event event,
                              FlowExecutionListener listener)
                       throws java.lang.Exception

Signal the occurence of the specified event - this is the entry point into the webflow system for managing all executing flows.

Parameters:

event - the event that occured

listener - a listener interested in flow execution lifecycle events that happen while handling this event

Returns:

the view descriptor of the model and view to render

Throws:

java.lang.Exception - in case of errors

createFlowExecution

protected FlowExecution createFlowExecution(Flow flow)

Create a new flow execution for given flow. Subclasses could redefine this if they wish to use a specialized FlowExecution implementation class.

Parameters:

flow - the flow

Returns:

the created flow execution

getFlow

protected Flow getFlow(Event event)

Obtain a flow to use from given event. If there is a "_flowId" parameter specified in the event, the flow with that id will be returend after lookup using the flow locator. If no "_flowId" parameter is present in the event, the default top-level flow will be returned.

getFlowIdParameterName

protected java.lang.String getFlowIdParameterName()

Returns the name of the flow id parameter in the event ("_flowId").

getFlowExecutionId

protected java.lang.String getFlowExecutionId(Event event)

Obtain a unique flow execution id from given event.

Parameters:

event - the event

Returns:

the obtained id or null if not found

getFlowExecutionIdParameterName

protected java.lang.String getFlowExecutionIdParameterName()

Returns the name of the flow execution id parameter in the event ("_flowExecutionId").

getNotSetEventIdParameterMarker

protected java.lang.String getNotSetEventIdParameterMarker()

Returns the marker value indicating that the event id parameter was not set properly in the event because of a view configuration error ("@NOT_SET@").

This is useful when a view relies on an dynamic means to set the eventId event parameter, for example, using javascript. This approach assumes the "not set" marker value will be a static default (a kind of fallback, submitted if the eventId does not get set to the proper dynamic value onClick, for example, if javascript was disabled).

prepareViewDescriptor

protected ViewDescriptor prepareViewDescriptor(ViewDescriptor viewDescriptor,
                                               java.io.Serializable flowExecutionId,
                                               FlowExecutionContext flowExecutionContext)

Do any processing necessary before given view descriptor can be returned to the client of the flow execution manager. This implementation adds a number of infrastructure attributes to the model that will be exposed to the view. More specifically, it will add the FLOW_EXECUTION_CONTEXT_ATTRIBUTE, FLOW_EXECUTION_ID_ATTRIBUTE and CURRENT_STATE_ID_ATTRIBUTE.

Parameters:

viewDescriptor - the view descriptor to be processed

flowExecutionId - the unique id of the flow execution

flowExecutionContext - the flow context providing info about the flow execution

Returns:

the processed view descriptor