Spring Web Flow Reference Guide

Keith Donald

Erwin Vervaet

Jeremy Grelle

Scott Andrews

Rossen Stoyanchev

Phil Webb

Version 2.3.2

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
What this guide covers
What Web Flow requires to run
Where to get support
Where to follow development
How to access Web Flow artifacts from Maven Central
How to access Web Flow artifacts with Ivy
How to access nightly builds and milestone releases
Accessing snapshots and milestones with Maven
2. What's New
Spring Web Flow 2.3
Embedding A Flow On A Page
Support For JSR-303 Bean Validation
Flow-Managed Persistence Context Propagation
Portlet 2.0 Resource Requests
Custom ConversationManager
Redirect In Same State
Samples
Spring Web Flow 2.2
JSF 2 Support
Spring Security Facelets Tag Library
Spring JavaScript Updates
JFS Portlet Support
3. Defining Flows
Introduction
What is a flow?
What is the makeup of a typical flow?
How are flows authored?
Essential language elements
flow
view-state
transition
end-state
Checkpoint: Essential language elements
Actions
evaluate
Checkpoint: flow actions
Input/Output Mapping
input
output
Checkpoint: input/output mapping
Variables
var
Calling subflows
subflow-state
Checkpoint: calling subflows
4. Expression Language (EL)
Introduction
Expression types
EL Implementations
Spring EL
Unified EL
OGNL
EL portability
Special EL variables
flowScope
viewScope
requestScope
flashScope
conversationScope
requestParameters
currentEvent
currentUser
messageContext
resourceBundle
flowRequestContext
flowExecutionContext
flowExecutionUrl
externalContext
Scope searching algorithm
5. Rendering views
Introduction
Defining view states
Specifying view identifiers
Flow relative view ids
Absolute view ids
Logical view ids
View scope
Allocating view variables
Assigning a viewScope variable
Manipulating objects in view scope
Executing render actions
Binding to a model
Performing type conversion
Type Conversion Options
Upgrading to Spring 3 Type Conversion And Formatting
Configuring Type Conversion and Formatting
Working With Spring 3 Type Conversion And Formatting
Formatting Annotations
Working With Dates
Suppressing binding
Specifying bindings explicitly
Validating a model
JSR-303 Bean Validation
Programmatic validation
ValidationContext
Suppressing validation
Executing view transitions
Transition actions
Global transitions
Event handlers
Rendering fragments
Working with messages
Adding plain text messages
Adding internationalized messages
Using message bundles
Understanding system generated messages
Displaying popups
View backtracking
Discarding history
Invalidating history
6. Executing actions
Introduction
Defining action states
Defining decision states
Action outcome event mappings
Action implementations
Invoking a POJO action
Invoking a custom Action implementation
Invoking a MultiAction implementation
Action exceptions
Handling a business exception with a POJO action
Handling a business exception with a MultiAction
Other Action execution examples
on-start
on-entry
on-exit
on-end
on-render
on-transition
Named actions
Streaming actions
Handling File Uploads
7. Flow Managed Persistence
Introduction
FlowScoped PersistenceContext
Flow Managed Persistence And Sub-Flows
8. Securing Flows
Introduction
How do I secure a flow?
The secured element
Security attributes
Matching type
The SecurityFlowExecutionListener
Custom Access Decision Managers
Configuring Spring Security
Spring configuration
web.xml Configuration
9. Flow Inheritance
Introduction
Is flow inheritance like Java inheritance?
Types of Flow Inheritance
Flow level inheritance
State level inheritance
Abstract flows
Inheritance Algorithm
Mergeable Elements
Non-mergeable Elements
10. System Setup
Introduction
webflow-config.xsd
Basic system configuration
FlowRegistry
FlowExecutor
flow-registry options
Specifying flow locations
Assigning custom flow identifiers
Assigning flow meta-attributes
Registering flows using a location pattern
Flow location base path
Configuring FlowRegistry hierarchies
Configuring custom FlowBuilder services
flow-executor options
Attaching flow execution listeners
Tuning FlowExecution persistence
11. Spring MVC Integration
Introduction
Configuring web.xml
Dispatching to flows
Registering the FlowHandlerAdapter
Defining flow mappings
Flow handling workflow
Implementing custom FlowHandlers
Example FlowHandler
Deploying a custom FlowHandler
FlowHandler Redirects
View Resolution
Signaling an event from a View
Using a named HTML button to signal an event
Using a hidden HTML form parameter to signal an event
Using a HTML link to signal an event
Embedding A Flow On A Page
Embedded Mode Vs Default Redirect Behavior
Embedded Flow Examples
12. Spring JavaScript Quick Reference
Introduction
Serving Javascript Resources
Including Spring Javascript in a Page
Spring Javascript Decorations
Handling Ajax Requests
Providing a Library-Specific AjaxHandler
Handling Ajax Requests with Spring MVC Controllers
Handling Ajax Requests with Spring MVC + Spring Web Flow
13. JSF Integration
Introduction
JSF Integration For Spring Developers
Configuring web.xml
Configuring web.xml in JSF 1.2
Configuring Web Flow for use with JSF
Configuring Spring MVC for JSF 2
Configuring faces-config.xml
Replacing the JSF Managed Bean Facility
Using Flow Variables
Using Scoped Spring Beans
Manipulating The Model
Data Model Implementations
Handling JSF Events With Spring Web Flow
Handling JSF In-page Action Events
Handling JSF Action Events
Performing Model Validation
Handling Ajax Events In JSF 2.0
Handling File Uploads with JSF
Handling Ajax Events In JSF 1.2
Embedding a Flow On a Page
Redirect In Same State
Using the Spring Security Facelets Tag Library
Enhancing The User Experience With Rich Web Forms in JSF 1.2
Validating a Text Field
Validating a Numeric Field
Validating a Date Field
Preventing an Invalid Form Submission
Third-Party Component Library Integration
Rich Faces Integration (JSF 1.2)
Apache MyFaces Trinidad Integration (JSF 1.2)
14. Portlet Integration
Introduction
Configuring web.xml and portlet.xml
Configuring Spring
Flow Handlers
Handler Mappings
Flow Handler Adapter
Portlet Views
Portlet Modes and Window States
Window State
Portlet Mode
Using Portlets with JSF
Issues in a Portlet Environment
Redirects
Switching Portlet Modes
15. Testing flows
Introduction
Extending AbstractXmlFlowExecutionTests
Specifying the path to the flow to test
Registering flow dependencies
Testing flow startup
Testing flow event handling
Mocking a subflow
16. Upgrading from 1.0
Introduction
Flow Definition Language
Flow Definition Updater Tool
EL Expressions
Web Flow Configuration
Web Flow Bean Configuration
Web Flow Schema Configuration
Flow Controller
Flow URL Handler
View Resolution
New Web Flow Concepts
Automatic Model Binding
OGNL vs Spring EL
Flash Scope
JSF
External Redirects
A. Flow Definition Language 1.0 to 2.0 Mappings

List of Tables

6.1. Action method return value to event id mappings
A.1. Mappings