# Preface

Many web applications consist of a mix of free browsing, where the user is allowed to navigate a web site as they please, and controlled navigations where the user is guided through a series of steps towards completion of a business goal.

Consider the typical shopping cart application. While a user is shopping, she is freely browsing available products, adding her favorites to her cart while skipping over others. This is a good "free browsing" use case. However, when the user decides to checkout, a controlled workflow begins--the checkout process. Such a process represents a single user conversation that takes place over a series of steps, and navigation from step-to-step is controlled. The entire process represents an discrete application transaction that must complete exactly once or not at all.

Consider some other good examples of "controlled navigations": applying for a loan, paying your taxes on-line, booking a trip reservation, registering an account, or updating a warehouse inventory.

Traditional approaches to modeling and enforcing such controlled navigations or "flows" fall flat, and fail to express the Flow as a first class concept. Spring Web Flow (SWF) is a component of the Spring Framework's web stack focused on solving this problem in a productive and powerful manner.

# Introduction

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

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

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.

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

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

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

#### 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.4, context.portlet requires Portlet API 1.0 in addition to Servlet API 2.4
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

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

#### 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 2.0, Spring Context 2.0, `builder.xml` requires JDK 1.5 or Xerces for XSD support

### The Test Layer

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

Depends On: Execution Engine, Execution Core

#### 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 2.0, JUnit 3.8.1

### The Executor Layer

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

#### 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 2.0
Struts | The integration between Spring Web Flow and the Struts Classic framework. | executor.struts | None | Core, Struts 1.1

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

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

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.

## 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).

Our active community support forum is located at http://forum.springframework.org.