Spring Web Flow (SWF) is a component of the Spring Framework's web stack focused on the definition and execution of UI flow within a web application.
The system allows you to capture a logical flow of your web application as a self-contained module that can be reused in different situations. Such a flow guides a single user through the implementation of a business task, and represents a single user conversation. Flows often execute across HTTP requests, have state, exhibit transactional characteristics, and may be dynamic and/or long-running in nature.
Spring Web Flow exists at a higher level of abstraction, integrating as a self-contained flow engine within base frameworks such as Struts, Spring MVC, Portlet MVC, and JSF. SWF provides you the capability to capture your application's UI flow explicitly in a declarative, portable, and manageable fashion. SWF is a powerful controller framework based on a finite-state machine, fully addressing the "C" in MVC.
Spring Web Flow has been architected as a self-contained flow engine with few required dependencies on third-party APIs. All dependencies are carefully managed.
At a minimum, to use Spring Web Flow you need:
spring-webflow (the framework)
spring-core (miscellaneous utility classes used internally by the framework)
spring-binding (the Spring data binding framework, used internally)
commons-logging (a simple logging facade, used internally)
OGNL (the default expression language)
Most users will embed SWF as a component within a larger web application development framework, as SWF is a focused controller technology that expects a calling system to care for request mapping and response rendering. In this case, those users will depend on a thin integration piece for their environment. For example, those executing flows within a Servlet environment might use the Spring MVC integration to care for dispatching requests to SWF and rendering responses for SWF view selections. Spring Web Flow ships convenient Spring MVC, Struts Classic, and JSF integration out of the box.
![[Note]](../images/admons/note.png) | Note |
|---|---|
Spring Web Flow, like Spring, is a layered framework, packaged in a manner that allows teams to use the parts they need and nothing else. For example, one team might use Spring Web Flow in a Servlet environment with Spring MVC and thus require the Spring MVC integration. Another team might use SWF in a Portlet environment, and thus require the Portlet MVC integration. Another team might mix and match. A major benefit of SWF is that it allows you to define reusable, self-contained controller modules that can execute in any environment. | |
Spring Web Flow is a layered framework. A diagram of Spring Web Flow's layered architecture is shown below:
Spring Web Flow layer diagram
Each layer is partitioned into one or more subsystems that together carry out the layer's role within the overall system. This section notes the purpose of each layer and describes each subsystem in the following format:
Subsystem name - The name of a layer subsystem.
Description - The purpose of the subsystem.
Packages - The Java packages that contain the source code for the subsystem. The packages are rooted at the org.springframework.webflow root package in the package hierarchy.
Subsystem interfaces - Central API elements exposed by the subsystem, typically through Java interfaces.
Internal dependencies - Dependencies of the subsystem. These could be other subsystems of the layer or external libraries.
Defines core flow definition and execution public APIs. As the "bottom layer", this layer is highly stable with no dependencies on any other layer.
Table 1.1. Execution Core Subsystems
| Subsystem name | Description | Packages | Subsystem interfaces | Internal dependencies |
|---|---|---|---|---|
| Core | Foundational, generic types usable by all other subsystems. Contains the default expression parser (OGNL-based) and core collection types (AttributeMap and company). | core, core.collection | None | None |
| Util | Low level utilities used by all other parts of the system. | util | None | None |
| Flow Definition | Central abstractions for modeling flow definitions. These abstractions include FlowDefinition, StateDefinition, and TransitionDefinition that form the domain language for describing flows. | definition | FlowDefinition | Core |
| Flow Definition Registry | Support for working with registries of flow definitions. Flow definitions eligible for execution are typically stored in a registry that provides lookup services. | definition.registry | FlowDefinitionRegistry, FlowDefinitionLocator | Core, Flow Definition |
| External Context | Provides normalized access to a client environment that has called into Spring Web Flow. | context, context.servlet, context.portlet | ExternalContext | Core, context.servlet requires Servlet API 2.3, context.portlet requires Portlet API 1.0 in addition to Servlet API 2.3 |
| Conversation | Manages the creation and cleanup of conversational state. Used by the execution repository system to begin new user conversations and track execution state. | conversation, conversation.impl | ConversationManager | Core, Util, External Context |
| Flow Execution | Stable runtime abstractions that define the flow definition execution model. For executing flow definitions and representing execution state. | execution, execution.support, execution.factory | FlowExecution | Core, External Context, Flow Definition |
| Flow Execution Repository | For persisting paused flow executions beyond a single request into the server. | execution.repository, execution.repository.support, execution.repository.continuation | FlowExecutionRepository | Core, Util, Flow Definition, Conversation, Flow Execution |
| Action | Reusable action implementations. | action, action.portlet | None | Core, Util, Flow Definition, External Context, Flow Execution |
Defines an implementation of the flow execution core API, forming the basis of the state machine or "engine" implementation. More volatile, as it contains specific implementations of stable execution abstractions.
Depends On: Execution Core
Table 1.2. Execution Engine Subsystems
| Subsystem name | Description | Packages | Subsystem interfaces | Internal dependencies |
|---|---|---|---|---|
| Engine Implementation | The implementation of the flow execution engine based on a finite state machine. | engine, engine.support, engine.impl | None | None |
| Flow Definition Builder | Abstractions used at configuration-time for building and assembling Flow definitions executable by this engine implementation. Flows are typically defined in externalized resources such as XML files. | engine.builder, engine.builder.xml | FlowBuilder | Engine Implementation, Spring Beans 1.2.7, Spring Context 1.2.7, builder.xml requires JDK 1.5 or Xerces for XSD support |
Support for unit testing flow artifacts and system testing flow executions.
Depends On: Execution Engine, Execution Core
Table 1.3. Test Subsystems
| Subsystem name | Description | Packages | Subsystem interfaces | Internal dependencies |
|---|---|---|---|---|
| Engine Artifact Unit Test Support | Support for unit testing implementations such as Actions in isolation. | test | None | JUnit 3.8.1 |
| Flow Execution Test Support | Support for testing Flow Executions out-of-container. | test.execution | None | Spring Beans 1.2.7, JUnit 3.8.1 |
Stable higher-level layer for driving and coordinating the execution of flow definitions. This layer is decoupled from the more-volatile engine implementation.
Depends On: Execution Core
Table 1.4. Executor Subsystems
| Subsystem name | Description | Packages | Subsystem interfaces | Internal dependencies |
|---|---|---|---|---|
| Core | Generic flow executor abstractions and support. | executor, executor.support | FlowExecutor | None |
| Spring MVC | The integration between Spring Web Flow and the Spring MVC framework. | executor.mvc | None | Core, Spring Web MVC 1.2.7, Portlet MVC requires Spring 2.0 |
| Struts | The integration between Spring Web Flow and the Struts Classic framework. | executor.struts | None | Core, Struts 1.1 |
| Java Server Faces (JSF) | The integration between Spring Web Flow and the Java Server Faces framework. | executor.jsf | None | Core, JSF 1.0 |
The top-most layer for configuring the overall Spring Web Flow system for use within an application. As the top layer, this layer depends on the most.
Depends On: Executor, Execution Engine, Execution Core
Table 1.5. System Configuration Subsystems
| Subsystem name | Description | Packages | Subsystem interfaces | Internal dependencies |
|---|---|---|---|---|
| Spring Configuration Support | For configuring Spring Web Flow using Spring 1.x and 2.x. | config | None | Spring Beans 1.2.7, spring-webflow-config-1.0 XSD support requires Spring 2.0 |
| Note |
|---|---|
As described above, some subsystem packages are optional depending on your use of the subsystem. For example, use of Spring Web Flow in a Servlet environment entails use of the ExternalContext context.servlet package which requires the Servlet API to be in the classpath. In this case, the context.portlet package is not used and the Portlet API is not required. | |
For the exact list of dependencies, as well as supported product usage configurations, see the Ivy dependency manager descriptor located within the SWF distribution.
Spring Web Flow 1.x is supported on Spring Framework 1.2.7 or > for the 1.x series, and supported on 2.0 or > for the 2.x series.
XML-based flow building requires Xerces 2 or JDK 5.0 (for XSD support).
The Spring Web Flow Portlet integration requires Spring Portlet MVC 2.0.
Our active community support forum is located at http://forum.springframework.org.