Spring Web Flow 2 Reference Guide
Reference Documentation
Keith Donald, SpringSource
Erwin Vervaet, Ervacon
Jeremy Grelle, SpringSource
Scott Andrews, SpringSource
Rossen Stoyanchev, SpringSource
Version 2.0.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.
Published June 2008
Table of Contents
Preface ...................................................................................................................................vii
1. Introduction ..........................................................................................................................1
1.1. What this guide covers ...............................................................................................1
1.2. What Web Flow requires to run ...................................................................................1
1.3. Where to get support ..................................................................................................1
1.4. Where to follow development .....................................................................................1
1.5. How to obtain Web Flow artifacts from the SpringSource Bundle Repository ................1
Accessing Web Flow with Maven ..............................................................................2
Accessing Web Flow with Ivy ...................................................................................2
1.6. How to obtain Web Flow artifacts from Maven Central ................................................3
1.7. How to Obtain Nightly Builds .....................................................................................4
2. Defining Flows .....................................................................................................................6
2.1. Introduction ...............................................................................................................6
2.2. What is a flow? ..........................................................................................................6
2.3. What is the makeup of a typical flow? .........................................................................7
2.4. How are flows authored? ............................................................................................7
2.5. Essential language elements ........................................................................................8
flow .........................................................................................................................8
view-state .................................................................................................................8
transition ..................................................................................................................8
end-state ..................................................................................................................8
Checkpoint: Essential language elements ...................................................................9
2.6. Actions ......................................................................................................................9
evaluate .................................................................................................................10
Checkpoint: flow actions .........................................................................................10
2.7. Input/Output Mapping ..............................................................................................11
input ......................................................................................................................11
output ....................................................................................................................12
Checkpoint: input/output mapping ...........................................................................12
2.8. Variables .................................................................................................................13
var .........................................................................................................................13
2.9. Calling subflows ......................................................................................................13
subflow-state ..........................................................................................................13
Checkpoint: calling subflows ...................................................................................14
3. Expression Language (EL) ..................................................................................................16
3.1. Introduction .............................................................................................................16
3.2. Supported EL implementations .................................................................................16
Unified EL .............................................................................................................16
OGNL ...................................................................................................................16
3.3. EL portability ..........................................................................................................16
please define productname in your docbook file!
Version 2.0.2 Spring Web Flow 2 Reference ii
3.4. EL usage .................................................................................................................16
Expression types .....................................................................................................17
3.5. Special EL variables .................................................................................................18
flowScope ..............................................................................................................18
viewScope .............................................................................................................18
requestScope ..........................................................................................................18
flashScope .............................................................................................................18
conversationScope ..................................................................................................19
requestParameters ...................................................................................................19
currentEvent ...........................................................................................................19
currentUser ............................................................................................................19
messageContext ......................................................................................................19
resourceBundle .......................................................................................................19
flowRequestContext ...............................................................................................20
flowExecutionContext ............................................................................................20
flowExecutionUrl ...................................................................................................20
externalContext ......................................................................................................20
3.6. Scope searching algorithm ........................................................................................20
4. Rendering views .................................................................................................................22
4.1. Introduction .............................................................................................................22
4.2. Defining view states .................................................................................................22
4.3. Specifying view identifiers .......................................................................................23
Flow relative view ids .............................................................................................23
Absolute view ids ...................................................................................................23
Logical view ids .....................................................................................................23
4.4. View scope ..............................................................................................................23
Allocating view variables ........................................................................................23
Assigning a viewScope variable ..............................................................................24
Manipulating objects in view scope .........................................................................24
4.5. Executing render actions ...........................................................................................24
4.6. Binding to a model ...................................................................................................25
4.7. Suppressing binding .................................................................................................25
4.8. Validating a model ...................................................................................................25
Programmatic validation .........................................................................................25
4.9. Transition actions .....................................................................................................26
4.10. Handling events .....................................................................................................27
Rendering partials ...................................................................................................27
Handling global events ............................................................................................28
4.11. Working with messages ..........................................................................................28
Adding plain text messages .....................................................................................28
Adding internationalized messages ..........................................................................28
Using message bundles ...........................................................................................28
4.12. Displaying popups ..................................................................................................29
4.13. View backtracking ..................................................................................................29
Discarding history ..................................................................................................29
please define productname in your docbook file!
Version 2.0.2 Spring Web Flow 2 Reference iii
Invalidating history .................................................................................................29
5. Flow Managed Persistence ..................................................................................................31
5.1. Introduction .............................................................................................................31
5.2. Data access patterns .................................................................................................31
5.3. FlowScoped PersistenceContext ................................................................................31
5.4. ConversationScoped PersistenceContext ....................................................................32
5.5. ViewState PersistenceContext ...................................................................................33
6. Securing Flows ...................................................................................................................34
6.1. Introduction .............................................................................................................34
6.2. How do I secure a flow? ...........................................................................................34
6.3. The secured element .................................................................................................34
Security attributes ...................................................................................................34
Matching type ........................................................................................................35
6.4. The SecurityFlowExecutionListener ..........................................................................35
Custom Access Decision Managers ..........................................................................35
6.5. Configuring Spring Security .....................................................................................36
Spring configuration ...............................................................................................36
web.xml Configuration ...........................................................................................36
7. Flow Inheritance .................................................................................................................38
7.1. Introduction .............................................................................................................38
7.2. Is flow inheritance like Java inheritance? ...................................................................38
7.3. Types of Flow Inheritance ........................................................................................38
Flow level inheritance .............................................................................................38
State level inheritance .............................................................................................38
7.4. Abstract flows ..........................................................................................................39
7.5. Inheritance Algorithm ..............................................................................................39
Mergeable Elements ...............................................................................................39
Non-mergeable Elements ........................................................................................40
8. System Setup ......................................................................................................................42
8.1. Introduction .............................................................................................................42
8.2. webflow-config.xsd ..................................................................................................42
8.3. Basic system configuration .......................................................................................42
FlowRegistry ..........................................................................................................42
FlowExecutor .........................................................................................................42
8.4. flow-registry options ................................................................................................43
Configuring custom FlowBuilder services ................................................................43
Configuring FlowRegistry hierarchies ......................................................................44
Specifying flow locations ........................................................................................44
Assigning custom flow identifiers ............................................................................44
Assigning flow meta-attributes ................................................................................45
Registering flows using a location pattern ................................................................45
8.5. flow-executor options ...............................................................................................45
Attaching flow execution listeners ...........................................................................45
Tuning FlowExecution persistence ..........................................................................45
9. Spring MVC Integration ......................................................................................................47
please define productname in your docbook file!
Guide
9.1. Introduction .............................................................................................................47
9.2. Configuring web.xml ................................................................................................47
9.3. Mapping URLs to Flows ...........................................................................................47
9.4. Flow Handlers .........................................................................................................48
Example FlowHandler ............................................................................................49
Registering the FlowHandlerAdapter .......................................................................49
FlowHandler Redirects ...........................................................................................50
9.5. Flow Controller ........................................................................................................50
9.6. View Resolution ......................................................................................................51
10. Spring JavaScript Quick Reference ....................................................................................52
10.1. Introduction ...........................................................................................................52
10.2. Serving Javascript Resources ..................................................................................52
10.3. Including Spring Javascript in a Page .......................................................................52
10.4. Spring Javascript Decorations .................................................................................53
10.5. Handling Ajax Requests .........................................................................................54
Handling Ajax Requests with Spring MVC Controllers .............................................54
Handling Ajax Requests with Spring MVC + Spring Web Flow ................................55
11. JSF Integration ..................................................................................................................56
11.1. Introduction ...........................................................................................................56
11.2. Spring-centric Integration Approach ........................................................................56
11.3. Configuring web.xml ..............................................................................................57
11.4. Configuring Web Flow to render JSF views .............................................................58
11.5. Configuring faces-config.xml ..................................................................................59
11.6. Replacing the JSF Managed Bean Facility ................................................................59
Using Flow Variables .............................................................................................59
Using Scoped Spring Beans .....................................................................................60
Manipulating The Model .........................................................................................60
11.7. Handling JSF Events With Spring Web Flow ...........................................................61
Handling JSF In-page Action Events ........................................................................61
Handling JSF Action Events ....................................................................................62
Performing Model Validation ..................................................................................63
Handling Ajax Events .............................................................................................63
11.8. Enhancing The User Experience With Rich Web Forms ............................................65
Validating a Text Field ...........................................................................................65
Validating a Numeric Field .....................................................................................65
Validating a Date Field ...........................................................................................65
Preventing an Invalid Form Submission ...................................................................66
11.9. Third-Party Component Library Integration .............................................................66
Rich Faces Integration ............................................................................................66
Apache MyFaces Trinidad Integration .....................................................................68
12. Portlet Integration .............................................................................................................69
12.1. Introduction ...........................................................................................................69
12.2. Configuring web.xml and portlet.xml ......................................................................69
12.3. Configuring Spring .................................................................................................70
Flow Handlers ........................................................................................................70
please define productname in your docbook file!
Version 2.0.2 Spring Web Flow 2 Reference v
