org.springframework.webflow.engine
Class Flow

java.lang.Object
  org.springframework.webflow.core.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 drive 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 quintessential 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 occurrence 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. 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 analogous to a Java class, defining all the behavior of an application module. The core behaviors start, resume(RequestControlContext), on event, end, and handleException(FlowExecutionException, RequestControlContext). Each method accepts 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 analogous to a java object that is an instance of a class.

Author:

Keith Donald, Erwin Vervaet, Colin Sampaleanu, Jeremy Grelle

See Also:

State, 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.core.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	addVariable(FlowVariable variable) Adds a flow variable.
void	addVariables(FlowVariable... variables) Adds flow variables.
boolean	containsState(java.lang.String stateId) Is a state with the provided id present in this flow?
static Flow	create(java.lang.String id, AttributeMap<?> attributes) Create a new flow with the given id and attributes.
void	destroy() Destroy this flow definition, releasing any resources.
void	end(RequestControlContext context, java.lang.String outcome, MutableAttributeMap<?> output) Inform this flow definition that an execution session of itself has ended.
boolean	equals(java.lang.Object o)
org.springframework.context.ApplicationContext	getApplicationContext() Returns a reference to application context hosting application objects and services used by this flow definition.
java.lang.ClassLoader	getClassLoader() Returns the class loader used by this flow definition to load classes.
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.
TransitionDefinition	getGlobalTransition(java.lang.String eventId) Returns the transition that matches the event with the provided id.
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.
Mapper	getInputMapper() Returns the configured flow input mapper, or null if none.
Mapper	getOutputMapper() Returns the configured flow output mapper, or null if none.
java.lang.String[]	getPossibleOutcomes() Returns the outcomes that are possible for this flow to reach.
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	getVariable(java.lang.String name) Returns the flow variable with the given name.
FlowVariable[]	getVariables() Returns the flow variables.
boolean	handleEvent(RequestControlContext context) Handle the last event that occurred against an active session of this flow.
boolean	handleException(FlowExecutionException exception, RequestControlContext context) Handle an exception that occurred during an execution of this flow.
int	hashCode()
boolean	inDevelopment() Returns true if this flow definition is currently in development (running in development mode).
void	restoreVariables(RequestContext context)
void	resume(RequestControlContext context) Resume a paused session for this flow in its current view state.
void	setApplicationContext(org.springframework.context.ApplicationContext applicationContext) Sets a reference to the application context hosting application objects needed by this flow.
void	setInputMapper(Mapper inputMapper) Sets the mapper to map flow input attributes.
void	setOutputMapper(Mapper 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.
void	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.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, 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

create

public static Flow create(java.lang.String id,
                          AttributeMap<?> attributes)

Create a new flow with the given id and attributes.

Parameters:

id - the flow id

attributes - the attributes

Returns:

the flow

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

getPossibleOutcomes

public java.lang.String[] getPossibleOutcomes()

Description copied from interface: FlowDefinition

Returns the outcomes that are possible for this flow to reach.

Specified by:

getPossibleOutcomes in interface FlowDefinition

Returns:

the possible outcomes

getClassLoader

public java.lang.ClassLoader getClassLoader()

Description copied from interface: FlowDefinition

Returns the class loader used by this flow definition to load classes.

Specified by:

getClassLoader in interface FlowDefinition

Returns:

the class loader

getApplicationContext

public org.springframework.context.ApplicationContext getApplicationContext()

Description copied from interface: FlowDefinition

Returns a reference to application context hosting application objects and services used by this flow definition.

Specified by:

getApplicationContext in interface FlowDefinition

Returns:

the application context

inDevelopment

public boolean inDevelopment()

Description copied from interface: FlowDefinition

Returns true if this flow definition is currently in development (running in development mode).

Specified by:

inDevelopment in interface FlowDefinition

Returns:

the development flag

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

getVariable

public FlowVariable getVariable(java.lang.String name)

Returns the flow variable with the given name.

Parameters:

name - the name of the variable

getVariables

public FlowVariable[] getVariables()

Returns the flow variables.

getInputMapper

public Mapper getInputMapper()

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

Returns:

the input mapper

setInputMapper

public void setInputMapper(Mapper 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 Mapper getOutputMapper()

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

Returns:

the output mapper

setOutputMapper

public void setOutputMapper(Mapper 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

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

getGlobalTransition

public TransitionDefinition getGlobalTransition(java.lang.String eventId)

Returns the transition that matches the event with the provided id.

Parameters:

eventId - the event id

Returns:

the transition that matches, or null if no match is found.

setApplicationContext

public void setApplicationContext(org.springframework.context.ApplicationContext applicationContext)

Sets a reference to the application context hosting application objects needed by this flow.

Parameters:

applicationContext - the application context

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 void 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. Typically data will be mapped into flow scope using the registered input mapper (setInputMapper(Mapper)).
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

resume

public void resume(RequestControlContext context)
            throws FlowExecutionException

Resume a paused session for this flow in its current view state.

Parameters:

context - the flow execution control context

Throws:

FlowExecutionException - when an exception occurs during the resume operation

handleEvent

public boolean handleEvent(RequestControlContext context)

Handle the last event that occurred against an active session of this flow.

Parameters:

context - the flow execution control context

end

public void end(RequestControlContext context,
                java.lang.String outcome,
                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(Mapper)).

Parameters:

context - the flow execution control context

outcome - the logical flow outcome that will be returned by the session, generally the id of the terminating end state

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

Throws:

FlowExecutionException - when an exception occurs ending this flow

destroy

public void destroy()

Description copied from interface: FlowDefinition

Destroy this flow definition, releasing any resources. After the flow is destroyed it cannot be started again.

Specified by:

destroy in interface FlowDefinition

handleException

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

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

Parameters:

exception - the exception that occurred

context - the flow execution control context

Throws:

FlowExecutionException

restoreVariables

public void restoreVariables(RequestContext context)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object