Spring Web Flow Reference Guide

Authors

Keith Donald , Erwin Vervaet , Jeremy Grelle , Scott Andrews , Rossen Stoyanchev , Phillip Webb

Version 2.4.0

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.


Table of Contents

Preface
1. Introduction
1.1. What this guide covers
1.2. What Web Flow requires to run
1.3. Where to get support
1.4. Where to follow development
1.5. How to access Web Flow artifacts from Maven Central
1.6. How to access Web Flow artifacts with Ivy
1.7. How to access nightly builds and milestone releases
1.7.1. Accessing snapshots and milestones with Maven
2. What's New
2.1. Spring Web Flow 2.4
2.1.1. Java-based Configuration
2.1.2. Spring MVC Flash Scope Integration
2.1.3. Partial JSR-303 Bean Validation
2.1.4. Hibernate 4 Support
2.1.5. Tiles 3 Support
2.1.6. Minimum JSF 2.0 Requirement
2.1.7. Portlet API 2.0 and JSF 2.0 support
2.1.8. Deprecations
2.2. Spring Web Flow 2.3
2.2.1. Embedding A Flow On A Page
2.2.2. Support For JSR-303 Bean Validation
2.2.3. Flow-Managed Persistence Context Propagation
2.2.4. Portlet 2.0 Resource Requests
2.2.5. Custom ConversationManager
2.2.6. Redirect In Same State
2.2.7. Samples
2.3. Spring Web Flow 2.2
2.3.1. JSF 2 Support
Comprehensive JSF 2 Support
Travel Sample With the PrimeFaces Components
2.3.2. Spring Security Facelets Tag Library
2.3.3. Spring JavaScript Updates
Deprecated ResourcesServlet
Dojo 1.5 and dojox
Two Spring JS artifacts
Client resources moved into META-INF/web-resources
2.3.4. JSF Portlet Support
Portlet API 2.0 and JSF 1.2 support
3. Defining Flows
3.1. Introduction
3.2. What is a flow?
3.3. What is the makeup of a typical flow?
3.4. How are flows authored?
3.5. Essential language elements
3.5.1. flow
3.5.2. view-state
3.5.3. transition
3.5.4. end-state
3.5.5. Checkpoint: Essential language elements
3.6. Actions
3.6.1. evaluate
Assigning an evaluate result
Converting an evaluate result
3.6.2. Checkpoint: flow actions
3.7. Input/Output Mapping
3.7.1. input
Declaring an input type
Assigning an input value
Marking an input as required
3.7.2. output
Specifying the source of an output value
3.7.3. Checkpoint: input/output mapping
3.8. Variables
3.8.1. var
3.9. Variable Scopes
3.9.1. Flow Scope
3.9.2. View Scope
3.9.3. Request Scope
3.9.4. Flash Scope
3.9.5. Conversation Scope
3.10. Calling subflows
3.10.1. subflow-state
Passing a subflow input
Mapping subflow output
3.10.2. Checkpoint: calling subflows
4. Expression Language (EL)
4.1. Introduction
4.1.1. Expression types
Standard Expressions
Template expressions
4.2. EL Implementations
4.2.1. Spring EL
4.2.2. Unified EL
4.2.3. OGNL
4.3. EL portability
4.4. Special EL variables
4.4.1. flowScope
4.4.2. viewScope
4.4.3. requestScope
4.4.4. flashScope
4.4.5. conversationScope
4.4.6. requestParameters
4.4.7. currentEvent
4.4.8. currentUser
4.4.9. messageContext
4.4.10. resourceBundle
4.4.11. flowRequestContext
4.4.12. flowExecutionContext
4.4.13. flowExecutionUrl
4.4.14. externalContext
4.5. Scope searching algorithm
5. Rendering views
5.1. Introduction
5.2. Defining view states
5.3. Specifying view identifiers
5.3.1. Flow relative view ids
5.3.2. Absolute view ids
5.3.3. Logical view ids
5.4. View scope
5.4.1. Allocating view variables
5.4.2. Assigning a viewScope variable
5.4.3. Manipulating objects in view scope
5.5. Executing render actions
5.6. Binding to a model
5.7. Performing type conversion
5.7.1. Type Conversion Options
5.7.2. Upgrading to Spring 3 Type Conversion And Formatting
5.7.3. Configuring Type Conversion and Formatting
5.7.4. Working With Spring 3 Type Conversion And Formatting
5.7.5. Formatting Annotations
5.7.6. Working With Dates
5.8. Suppressing binding
5.9. Specifying bindings explicitly
5.10. Validating a model
5.10.1. JSR-303 Bean Validation
Partial Validation
5.10.2. Programmatic validation
Implementing a model validate method
Implementing a Validator
Default validate method
5.10.3. ValidationContext
5.11. Suppressing validation
5.12. Executing view transitions
5.12.1. Transition actions
5.12.2. Global transitions
5.12.3. Event handlers
5.12.4. Rendering fragments
5.13. Working with messages
5.13.1. Adding plain text messages
5.13.2. Adding internationalized messages
5.13.3. Using message bundles
5.13.4. Understanding system generated messages
5.14. Displaying popups
5.15. View backtracking
5.15.1. Discarding history
5.15.2. Invalidating history
6. Executing actions
6.1. Introduction
6.2. Defining action states
6.3. Defining decision states
6.4. Action outcome event mappings
6.5. Action implementations
6.5.1. Invoking a POJO action
6.5.2. Invoking a custom Action implementation
6.5.3. Invoking a MultiAction implementation
6.6. Action exceptions
6.6.1. Handling a business exception with a POJO action
6.6.2. Handling a business exception with a MultiAction
6.6.3. Using an exception-handler element
6.7. Other Action execution examples
6.7.1. on-start
6.7.2. on-entry
6.7.3. on-exit
6.7.4. on-end
6.7.5. on-render
6.7.6. on-transition
6.7.7. Named actions
6.7.8. Streaming actions
6.7.9. Handling File Uploads
7. Flow Managed Persistence
7.1. Introduction
7.2. FlowScoped PersistenceContext
7.3. Flow Managed Persistence And Sub-Flows
8. Securing Flows
8.1. Introduction
8.2. How do I secure a flow?
8.3. The secured element
8.3.1. Security attributes
8.3.2. Matching type
8.4. The SecurityFlowExecutionListener
8.4.1. Custom Access Decision Managers
8.5. Configuring Spring Security
8.5.1. Spring configuration
8.5.2. web.xml Configuration
9. Flow Inheritance
9.1. Introduction
9.2. Is flow inheritance like Java inheritance?
9.3. Types of Flow Inheritance
9.3.1. Flow level inheritance
9.3.2. State level inheritance
9.4. Abstract flows
9.5. Inheritance Algorithm
9.5.1. Mergeable Elements
9.5.2. Non-mergeable Elements
10. System Setup
10.1. Introduction
10.2. Java Config and XML Namespace
10.3. Basic system configuration
10.3.1. FlowRegistry
10.3.2. FlowExecutor
10.4. flow-registry options
10.4.1. Specifying flow locations
10.4.2. Assigning custom flow identifiers
10.4.3. Assigning flow meta-attributes
10.4.4. Registering flows using a location pattern
10.4.5. Flow location base path
10.4.6. Configuring FlowRegistry hierarchies
10.4.7. Configuring custom FlowBuilder services
conversion-service
expression-parser
view-factory-creator
development
10.5. flow-executor options
10.5.1. Attaching flow execution listeners
10.5.2. Tuning FlowExecution persistence
max-executions
max-execution-snapshots
11. Spring MVC Integration
11.1. Introduction
11.2. Configuring web.xml
11.3. Dispatching to flows
11.3.1. Registering the FlowHandlerAdapter
11.3.2. Defining flow mappings
11.3.3. Flow handling workflow
11.4. Implementing custom FlowHandlers
11.4.1. Example FlowHandler
11.4.2. Deploying a custom FlowHandler
11.4.3. FlowHandler Redirects
11.5. View Resolution
11.6. Signaling an event from a View
11.6.1. Using a named HTML button to signal an event
11.6.2. Using a hidden HTML form parameter to signal an event
11.6.3. Using a HTML link to signal an event
11.7. Embedding A Flow On A Page
11.7.1. Embedded Mode Vs Default Redirect Behavior
11.7.2. Embedded Flow Examples
11.8. Saving Flow Output to MVC Flash Scope
12. Spring JavaScript Quick Reference
12.1. Introduction
12.2. Serving Javascript Resources
12.3. Including Spring Javascript in a Page
12.4. Spring Javascript Decorations
12.5. Handling Ajax Requests
12.5.1. Providing a Library-Specific AjaxHandler
12.5.2. Handling Ajax Requests with Spring MVC Controllers
12.5.3. Handling Ajax Requests with Spring MVC + Spring Web Flow
13. JSF Integration
13.1. Introduction
13.2. JSF Integration For Spring Developers
13.3. Upgrading from Spring Web Flow 2.3
13.3.1. Spring Faces Components
13.3.2. Configuring faces-config.xml
13.3.3. Third-party Libraries
13.3.4. Spring Security Facelets Tag Library
13.4. Configuring web.xml
13.5. Configuring Web Flow for use with JSF
13.6. Replacing the JSF Managed Bean Facility
13.6.1. Using Flow Variables
13.6.2. Using Scoped Spring Beans
13.6.3. Manipulating The Model
13.6.4. Data Model Implementations
13.7. Handling JSF Events With Spring Web Flow
13.7.1. Handling JSF In-page Action Events
13.7.2. Handling JSF Action Events
13.7.3. Performing Model Validation
13.7.4. Handling Ajax Events In JSF
13.8. Embedding a Flow On a Page
13.9. Redirect In Same State
13.10. Handling File Uploads with JSF
13.10.1. File Uploads with PrimeFaces
13.10.2. File Uploads with RichFaces
13.11. Using the Spring Security Facelets Tag Library
13.12. Third-Party Component Library Integration
14. Portlet Integration
14.1. Introduction
14.2. Configuring web.xml and portlet.xml
14.3. Configuring Spring
14.3.1. Flow Handlers
14.3.2. Handler Mappings
14.3.3. Flow Handler Adapter
14.4. Portlet Views
14.5. Portlet Modes and Window States
14.5.1. Window State
14.5.2. Portlet Mode
14.6. Using Portlets with JSF
14.6.1.
14.7. Issues in a Portlet Environment
14.7.1. Redirects
14.7.2. Switching Portlet Modes
15. Testing flows
15.1. Introduction
15.2. Extending AbstractXmlFlowExecutionTests
15.3. Specifying the path to the flow to test
15.4. Registering flow dependencies
15.5. Testing flow startup
15.6. Testing flow event handling
15.7. Mocking a subflow
16. Upgrading from 1.0
16.1. Introduction
16.2. Flow Definition Language
16.2.1. Flow Definition Updater Tool
Flow Definition Updater Tool Warnings
16.2.2. EL Expressions
16.3. Web Flow Configuration
16.3.1. Web Flow Bean Configuration
16.3.2. Web Flow Schema Configuration
flow-executor
flow-execution-listeners
flow-registry
16.3.3. Flow Controller
16.3.4. Flow URL Handler
16.3.5. View Resolution
16.4. New Web Flow Concepts
16.4.1. Automatic Model Binding
16.4.2. OGNL vs Spring EL
16.4.3. Flash Scope
16.4.4. JSF
16.4.5. External Redirects
A. Flow Definition Language 1.0 to 2.0 Mappings