org.springframework.webflow.engine
Class Flow

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

All Implemented Interfaces:

Annotated, FlowDefinition

public class Flow
extends AnnotatedObject
implements FlowDefinition

A single flow definition. A Flow definition is a reusable, self-contained controller module that provides the blue print for a user dialog or conversation. Flows typically orchestrate controlled navigations within web applications to guide users through fulfillment of a business process/goal that takes place over a series of steps, modeled as states.

A simple Flow definition could do nothing more than execute an action and display a view all in one request. A more elaborate Flow definition may be long-lived and execute across a series of requests, invoking many possible paths, actions, and subflows.

Especially in Intranet applications there are often "controlled navigations" where the user is not free to do what he or she wants but must follow the guidelines provided by the system to complete a process that is transactional in nature (the quinessential example would be a 'checkout' flow of a shopping cart application). This is a typical use case appropriate to model as a flow.

Structurally a Flow is composed of a set of states. A State is a point in a flow where a behavior is executed; for example, showing a view, executing an action, spawning a subflow, or terminating the flow. Different types of states execute different behaviors in a polymorphic fashion.

Each TransitionableState type has one or more transitions that when executed move a flow to another state. These transitions define the supported paths through the flow.

A state transition is triggered by the occurence of an event. An event is something that happens the flow should respond to, for example a user input event like ("submit") or an action execution result event like ("success"). When an event occurs in a state of a Flow that event drives a state transition that decides what to do next.

Each Flow has exactly one start state. A start state is simply a marker noting the state executions of this Flow definition should start in. The first state added to the flow will become the start state by default.

Flow definitions may have one or more flow exception handlers. A FlowExecutionExceptionHandler can execute custom behavior in response to a specific exception (or set of exceptions) that occur in a state of one of this flow's executions.

Instances of this class are typically built by FlowBuilder implementations but may also be directly instantiated.

This class and the rest of the Spring Web Flow (SWF) engine have been designed with minimal dependencies on other libraries. Spring Web Flow is usable in a standalone fashion (as well as in the context of other frameworks like Spring MVC, Struts, or JSF, for example). The engine system is fully usable outside an HTTP servlet environment, for example in portlets, tests, or standalone applications. One of the major architectural benefits of Spring Web Flow is the ability to design reusable, high-level controller modules that may be executed in any environment.

Note: flows are singleton definition objects so they should be thread-safe. You can think a flow definition as analagous somewhat to a Java class, defining all the behavior of an application module. The core behaviors start, on event, and end each accept a request context that allows for this flow to access execution state in a thread safe manner. A flow execution is what models a running instance of this flow definition, somewhat analgous to a java object that is an instance of a class.

Author:

Keith Donald, Erwin Vervaet, Colin Sampaleanu

See Also:

State, TransitionableState, ActionState, ViewState, SubflowState, EndState, DecisionState, Transition, FlowExecutionExceptionHandler

Field Summary

protected org.apache.commons.logging.Log

logger Logger, can be used in subclasses.

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

CAPTION_PROPERTY, DESCRIPTION_PROPERTY

Constructor Summary

Flow(java.lang.String id)
Construct a new flow definition with the given id.

Method Summary

protected void	add(State state) Add given state definition to this flow definition.
void	addInlineFlow(Flow flow) Adds an inline flow to this flow.
void	addVariable(FlowVariable variable) Adds a flow variable.
void	addVariables(FlowVariable[] variables) Adds flow variables.
boolean	containsInlineFlow(java.lang.String id) Tests if this flow contains an in-line flow with the specified id.
boolean	containsState(java.lang.String stateId) Is a state with the provided id present in this flow?
void	end(RequestControlContext context, MutableAttributeMap output) Inform this flow definition that an execution session of itself has ended.
boolean	equals(java.lang.Object o)
ActionList	getEndActionList() Returns the list of actions executed by this flow when an execution of the flow ends.
FlowExecutionExceptionHandlerSet	getExceptionHandlerSet() Returns the set of exception handlers, allowing manipulation of how exceptions are handled when thrown during flow execution.
TransitionSet	getGlobalTransitionSet() Returns the set of transitions eligible for execution by this flow if no state-level transition is matched.
java.lang.String	getId() Returns the unique id of this flow.
Flow	getInlineFlow(java.lang.String id) Returns the inline flow with the provided id, or null if no such inline flow exists.
int	getInlineFlowCount() Returns the count of registered inline flows.
java.lang.String[]	getInlineFlowIds() Returns the list of inline flow ids.
Flow[]	getInlineFlows() Returns the list of inline flows.
org.springframework.binding.mapping.AttributeMapper	getInputMapper() Returns the configured flow input mapper, or null if none.
org.springframework.binding.mapping.AttributeMapper	getOutputMapper() Returns the configured flow output mapper, or null if none.
ActionList	getStartActionList() Returns the list of actions executed by this flow when an execution of the flow starts.
StateDefinition	getStartState() Return this flow's starting point.
StateDefinition	getState(java.lang.String stateId) Returns the state definition with the specified id.
int	getStateCount() Returns the number of states defined in this flow.
java.lang.String[]	getStateIds() Convenience accessor that returns an ordered array of the String ids for the state definitions associated with this flow definition.
State	getStateInstance(java.lang.String stateId) Lookup the identified state instance of this flow.
TransitionableState	getTransitionableState(java.lang.String stateId) Return the TransitionableState with given stateId.
FlowVariable[]	getVariables() Returns the flow variables.
ViewSelection	handleException(FlowExecutionException exception, RequestControlContext context) Handle an exception that occured during an execution of this flow.
int	hashCode()
ViewSelection	onEvent(RequestControlContext context) Inform this flow definition that an event was signaled in the current state of an active flow execution.
protected void	setId(java.lang.String id) Set the unique id of this flow.
void	setInputMapper(org.springframework.binding.mapping.AttributeMapper inputMapper) Sets the mapper to map flow input attributes.
void	setOutputMapper(org.springframework.binding.mapping.AttributeMapper outputMapper) Sets the mapper to map flow output attributes.
void	setStartState(State state) Set the start state for this flow to the state provided; any state may be the start state.
void	setStartState(java.lang.String stateId) Set the start state for this flow to the state with the provided stateId; a state must exist by the provided stateId.
ViewSelection	start(RequestControlContext context, MutableAttributeMap input) Start a new session for this flow in its start state.
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, can be used in subclasses.

Constructor Detail

Flow

public Flow(java.lang.String id)

Construct a new flow definition with the given id. The id should be unique among all flows.

Parameters:

id - the flow identifier

Method Detail

getId

public java.lang.String getId()

Description copied from interface: FlowDefinition

Returns the unique id of this flow.

Specified by:

getId in interface FlowDefinition

Returns:

the flow id

getStartState

public StateDefinition getStartState()

Description copied from interface: FlowDefinition

Return this flow's starting point.

Specified by:

getStartState in interface FlowDefinition

Returns:

the start state

getState

public StateDefinition getState(java.lang.String stateId)

Description copied from interface: FlowDefinition

Returns the state definition with the specified id.

Specified by:

getState in interface FlowDefinition

Parameters:

stateId - the state id

Returns:

the state definition

setId

protected void setId(java.lang.String id)

Set the unique id of this flow.

add

protected void add(State state)
            throws java.lang.IllegalArgumentException

Add given state definition to this flow definition. Marked protected, as this method is to be called by the (privileged) state definition classes themselves during state construction as part of a FlowBuilder invocation.

Parameters:

state - the state to add

Throws:

java.lang.IllegalArgumentException - when the state cannot be added to the flow; for instance if another state shares the same id as the one provided or if given state already belongs to another flow

getStateCount

public int getStateCount()

Returns the number of states defined in this flow.

Returns:

the state count

containsState

public boolean containsState(java.lang.String stateId)

Is a state with the provided id present in this flow?

Parameters:

stateId - the state id

Returns:

true if yes, false otherwise

setStartState

public void setStartState(java.lang.String stateId)
                   throws java.lang.IllegalArgumentException

Set the start state for this flow to the state with the provided stateId; a state must exist by the provided stateId.

Parameters:

stateId - the id of the new start state

Throws:

java.lang.IllegalArgumentException - when no state exists with the id you provided

setStartState

public void setStartState(State state)
                   throws java.lang.IllegalArgumentException

Set the start state for this flow to the state provided; any state may be the start state.

Parameters:

state - the new start state

Throws:

java.lang.IllegalArgumentException - given state has not been added to this flow

getTransitionableState

public TransitionableState getTransitionableState(java.lang.String stateId)
                                           throws java.lang.IllegalArgumentException,
                                                  java.lang.ClassCastException

Return the TransitionableState with given stateId.

Parameters:

stateId - id of the state to look up

Returns:

the transitionable state

Throws:

java.lang.IllegalArgumentException - if the identified state cannot be found

java.lang.ClassCastException - when the identified state is not transitionable

getStateInstance

public State getStateInstance(java.lang.String stateId)
                       throws java.lang.IllegalArgumentException

Lookup the identified state instance of this flow.

Parameters:

stateId - the state id

Returns:

the state

Throws:

java.lang.IllegalArgumentException - if the identified state cannot be found

getStateIds

public java.lang.String[] getStateIds()

Convenience accessor that returns an ordered array of the String ids for the state definitions associated with this flow definition.

Returns:

the state ids

addVariable

public void addVariable(FlowVariable variable)

Adds a flow variable.

Parameters:

variable - the variable

addVariables

public void addVariables(FlowVariable[] variables)

Adds flow variables.

Parameters:

variables - the variables

getVariables

public FlowVariable[] getVariables()

Returns the flow variables.

getInputMapper

public org.springframework.binding.mapping.AttributeMapper getInputMapper()

Returns the configured flow input mapper, or null if none.

Returns:

the input mapper

setInputMapper

public void setInputMapper(org.springframework.binding.mapping.AttributeMapper inputMapper)

Sets the mapper to map flow input attributes.

Parameters:

inputMapper - the input mapper

getStartActionList

public ActionList getStartActionList()

Returns the list of actions executed by this flow when an execution of the flow starts. The returned list is mutable.

Returns:

the start action list

getEndActionList

public ActionList getEndActionList()

Returns the list of actions executed by this flow when an execution of the flow ends. The returned list is mutable.

Returns:

the end action list

getOutputMapper

public org.springframework.binding.mapping.AttributeMapper getOutputMapper()

Returns the configured flow output mapper, or null if none.

Returns:

the output mapper

setOutputMapper

public void setOutputMapper(org.springframework.binding.mapping.AttributeMapper outputMapper)

Sets the mapper to map flow output attributes.

Parameters:

outputMapper - the output mapper

getExceptionHandlerSet

public FlowExecutionExceptionHandlerSet getExceptionHandlerSet()

Returns the set of exception handlers, allowing manipulation of how exceptions are handled when thrown during flow execution. Exception handlers are invoked when an exception occurs at execution time and can execute custom exception handling logic as well as select an error view to display. Exception handlers attached at the flow level have an opportunity to handle exceptions that aren't handled at the state level.

Returns:

the exception handler set

addInlineFlow

public void addInlineFlow(Flow flow)

Adds an inline flow to this flow.

Parameters:

flow - the inline flow to add

getInlineFlowIds

public java.lang.String[] getInlineFlowIds()

Returns the list of inline flow ids.

Returns:

a string array of inline flow identifiers

getInlineFlows

public Flow[] getInlineFlows()

Returns the list of inline flows.

Returns:

the list of inline flows

getInlineFlowCount

public int getInlineFlowCount()

Returns the count of registered inline flows.

Returns:

the count

containsInlineFlow

public boolean containsInlineFlow(java.lang.String id)

Tests if this flow contains an in-line flow with the specified id.

Parameters:

id - the inline flow id

Returns:

true if this flow contains a inline flow with that id, false otherwise

getInlineFlow

public Flow getInlineFlow(java.lang.String id)
                   throws java.lang.IllegalArgumentException

Returns the inline flow with the provided id, or null if no such inline flow exists.

Parameters:

id - the inline flow id

Returns:

the inline flow

Throws:

java.lang.IllegalArgumentException - when an invalid flow id is provided

getGlobalTransitionSet

public TransitionSet getGlobalTransitionSet()

Returns the set of transitions eligible for execution by this flow if no state-level transition is matched. The returned set is mutable.

Returns:

the global transition set

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

start

public ViewSelection start(RequestControlContext context,
                           MutableAttributeMap input)
                    throws FlowExecutionException

Start a new session for this flow in its start state. This boils down to the following:

1. Create (setup) all registered flow variables (addVariable(FlowVariable)) in flow scope.
2. Map provided input data into the flow execution control context. Typically data will be mapped into flow scope using the registered input mapper (setInputMapper(AttributeMapper)).
3. Execute all registered start actions (getStartActionList()).
4. Enter the configured start state (setStartState(State))

Parameters:

context - the flow execution control context

input - eligible input into the session

Throws:

FlowExecutionException - when an exception occurs starting the flow

onEvent

public ViewSelection onEvent(RequestControlContext context)
                      throws FlowExecutionException

Inform this flow definition that an event was signaled in the current state of an active flow execution. The signaled event is the last event available in given request context (RequestContext.getLastEvent()).

Parameters:

context - the flow execution control context

Returns:

the selected view

Throws:

FlowExecutionException - when an exception occurs processing the event

end

public void end(RequestControlContext context,
                MutableAttributeMap output)
         throws FlowExecutionException

Inform this flow definition that an execution session of itself has ended. As a result, the flow will do the following:

1. Execute all registered end actions (getEndActionList()).
2. Map data available in the flow execution control context into provided output map using a registered output mapper (setOutputMapper(AttributeMapper)).

Parameters:

context - the flow execution control context

output - initial output produced by the session that is eligible for modification by this method

Throws:

FlowExecutionException - when an exception occurs ending this flow

handleException

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

Handle an exception that occured during an execution of this flow.

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

Throws:

FlowExecutionException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object