Package 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 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:

  • Field Details

    • logger

      protected final org.apache.commons.logging.Log logger
      Logger, can be used in subclasses.

  • Constructor Details

    • Flow

      public Flow(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 Details

    • create

      public static Flow create(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 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(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 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 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 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:
      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(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(String stateId) throws 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:
      IllegalArgumentException - when no state exists with the id you provided

    • setStartState

      public void setStartState(State state) throws 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:
      IllegalArgumentException - given state has not been added to this flow

    • getTransitionableState

      public TransitionableState getTransitionableState(String stateId) throws IllegalArgumentException, ClassCastException
      Return the TransitionableState with given stateId.
      Parameters:
      stateId - id of the state to look up
      Returns:
      the transitionable state
      Throws:
      IllegalArgumentException - if the identified state cannot be found
      ClassCastException - when the identified state is not transitionable

    • getStateInstance

      public State getStateInstance(String stateId) throws IllegalArgumentException
      Lookup the identified state instance of this flow.
      Parameters:
      stateId - the state id
      Returns:
      the state
      Throws:
      IllegalArgumentException - if the identified state cannot be found

    • getStateIds

      public 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(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(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(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class 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, 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 String toString()
      Overrides:
      toString in class Object