Chapter 1. Introduction

1.1. Overview


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.

1.2. Architecture overview

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]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.

1.3. Architectural layers

Spring Web Flow is a layered framework. A diagram of Spring Web Flow's layered architecture is shown below:

Spring Web Flow layer diagram

1.4. Layer descriptions

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.

1.4.1. The Execution Core Layer (Bottom Layer)

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 nameDescriptionPackagesSubsystem interfacesInternal 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 NoneNone
Util Low level utilities used by all other parts of the system. util NoneNone
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 providing 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, repository.continuation requires commons-codec 1.0 if using client continuations
Action Reusable action implementations. action, action.portlet None Core, Util, Flow Definition, External Context, Flow Execution

1.4.2. The Execution Engine Layer

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 nameDescriptionPackagesSubsystem interfacesInternal dependencies
Engine Implementation The implementation of the flow execution engine based on a finite state machine. engine, engine.support, engine.impl NoneNone
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

1.4.3. The Test Layer

Support for unit testing flow artifacts and system testing flow executions.

Depends On: Execution Engine, Execution Core

Table 1.3. Test Subsystems

Subsystem nameDescriptionPackagesSubsystem interfacesInternal dependencies
Engine Artifact Unit Test Support Support for unit testing implementations such as Actions in isolation. test NoneJUnit 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

1.4.4. The Executor Layer

Stable higher-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 nameDescriptionPackagesSubsystem interfacesInternal dependencies
Core Stable, generic flow executor abstractions and support. executor, executor.support FlowExecutorNone
Spring MVC The integration between Spring Web Flow and the Spring MVC framework. executor.mvcNone 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

1.4.5. The System Configuration Layer (Top Layer)

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 nameDescriptionPackagesSubsystem interfacesInternal 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]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.

1.5. Support

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.