A single flow definition. A Flow definition represents a reusable, self-contained controller module that provides the blue print for a logical page flow of a web application. A "logical page flow" is defined as a controlled navigation that guides a single user 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, executing accross a series of requests, invoking many possible paths, actions, and subflows.

Note: A flow is not a welcome page or an index page: don't use flows for those cases, use simple controllers/actions/portlets instead. Don't use flows where your application demands a significant amount of "free browsing": flows force strict navigation. 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 for 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, defining the supported paths through the flow. A state transition is triggered by the occurence of an event. An event is something that happens externally 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 StateExceptionHandler 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 subclassed.

This class, and the rest of the Spring Web Flow (SWF) core, has been designed with minimal dependencies on other libraries, and is usable in a standalone fashion (as well as in the context of other frameworks like Spring MVC, Struts, or JSF, for example). The core 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!