Overview | Package | Class | Tree | Deprecated | Index | Help
| Spring Web Flow
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Spring Web Flow
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD