Reference Documentation
Version 1.0.3
April 2007
Copyright © 2004-2007 Keith Donald, Erwin Vervaet, Ross Stoyanchev
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. Overview ............................................................................................................................. 7
1.2. Architecture overview .......................................................................................................... 7
1.3. Architectural layers .............................................................................................................. 7
1.4. Layer descriptions ................................................................................................................ 8
1.4.1. The Execution Core Layer (Bottom Layer) .................................................................. 8
1.4.2. The Execution Engine Layer ...................................................................................... 10
1.4.3. The Test Layer .......................................................................................................... 10
1.4.4. The Executor Layer ................................................................................................... 10
1.4.5. The System Configuration Layer (Top Layer) ............................................................. 11
1.5. Support ................................................................................................................................ 12
2. Flow definition ..............................................................................................................................
2.1. Introduction ......................................................................................................................... 13
2.2. FlowDefinition ..................................................................................................................... 13
2.2.1. XML-based Flow template ......................................................................................... 14
2.2.2. Java Flow API example ............................................................................................. 15
2.3. StateDefinition ..................................................................................................................... 15
2.4. Transitionable State .............................................................................................................. 16
2.4.1. XML-based state template .......................................................................................... 16
2.4.2. Java state API example .............................................................................................. 17
2.5. TransitionDefinition ............................................................................................................. 17
2.5.1. Transition XML template ........................................................................................... 18
2.5.2. Transition Java API example ...................................................................................... 18
2.5.3. Action transition execution criteria ............................................................................. 18
2.5.4. Dynamic transitions ................................................................................................... 18
2.5.5. Global transitions ...................................................................................................... 19
2.5.6. Transition executing state exception handlers .............................................................. 20
2.6. Concrete state types .............................................................................................................. 20
2.6.1. ViewState ................................................................................................................. 21
2.6.2. ActionState ............................................................................................................... 27
2.6.3. DecisionState ............................................................................................................ 36
2.6.4. SubflowState ............................................................................................................. 37
2.6.5. EndState ................................................................................................................... 40
3. Flow execution ..............................................................................................................................
3.1. Introduction ......................................................................................................................... 44
3.2. FlowExecution ..................................................................................................................... 44
3.2.1. Flow execution creation ............................................................................................. 44
3.2.2. Flow execution startup ............................................................................................... 44
3.2.3. Flow execution resume .............................................................................................. 45
3.2.4. Flow execution lifecycle ............................................................................................ 45
3.2.5. Flow execution properties .......................................................................................... 46
3.2.6. Flow execution impl creation ..................................................................................... 46
3.3. Flow execution context ......................................................................................................... 47
3.4. Flow execution scopes .......................................................................................................... 49
3.5. Flow execution testing .......................................................................................................... 50
3.5.1. Flow execution test example ...................................................................................... 50
3.5.2. Execution unit testing vs. full-blown system testing ..................................................... 53
Spring Web Flow Version 1.0.3 ii
4. Flow execution repositories ...........................................................................................................
4.1. Introduction ......................................................................................................................... 55
4.2. Repository architecture overview .......................................................................................... 55
4.3. Flow execution identity ........................................................................................................ 56
4.3.1. Conversation identifier ............................................................................................... 56
4.3.2. Continuation identifier ............................................................................................... 57
4.3.3. Flow execution key .................................................................................................... 57
4.4. Conversation ending ............................................................................................................. 57
4.5. Flow execution repository implementations ........................................................................... 57
4.5.1. Simple flow execution repository ................................................................................ 57
4.5.2. Continuation flow execution repository ....................................................................... 58
4.5.3. Client continuation flow execution repository .............................................................. 58
5. Flow executors ..............................................................................................................................
5.1. Introduction ......................................................................................................................... 60
5.2. FlowExecutor ...................................................................................................................... 60
5.2.1. FlowExecutorImpl ..................................................................................................... 61
5.2.2. A typical flow executor configuration with Spring 2.0 ................................................. 61
5.2.3. A flow executor using a simple execution repository .................................................... 62
5.2.4. A flow executor using a client-side continuation-based execution repository ................. 62
5.2.5. A flow executor using a single key execution repository .............................................. 62
5.2.6. A flow executor setting custom conversation management attributes ............................. 62
5.2.7. A flow executor setting system execution attributes ..................................................... 63
5.2.8. A flow executor setting custom execution listeners ...................................................... 63
5.2.9. A Spring 1.2 compatible flow executor configuration ................................................... 63
5.3. Spring MVC integration ....................................................................................................... 64
5.3.1. A single flow controller executing all flows in a Servlet MVC environment .................. 64
5.3.2. A single portlet flow controller executing a flow within a Portlet .................................. 64
5.4. Flow executor parameterization ............................................................................................. 65
5.4.1. Request parameter-based flow executor argument extraction ........................................ 65
5.4.2. Request path based flow executor argument extraction ................................................. 66
5.5. Struts integration .................................................................................................................. 67
5.5.1. A single flow action executing all flows ...................................................................... 67
5.6. Java Server Faces (JSF) integration ....................................................................................... 67
5.6.1. Adding Spring Web Flow extensions to faces-config.xml ............................................. 68
5.6.2. Configuring the Web Flow system .............................................................................. 68
5.6.3. Launching a flow execution - JSF command link component ........................................ 69
5.6.4. Launching a flow execution - normal HTML anchor .................................................... 69
5.6.5. Flow definitions in a JSF environment ........................................................................ 69
5.6.6. Resuming a flow execution - form bound to flow execution variables ........................... 70
5.6.7. Spring Web Flow JSF Integration Samples .................................................................. 70
5.6.8. A pre Spring Web Flow 1.0.2 faces-config.xml file ...................................................... 70
5.6.9. A pre Spring Web Flow 1.0.2 Web Flow system configuration ..................................... 71
5.6.10. Resuming a flow execution - pre Spring Web Flow 1.0.2 ........................................... 71
6. Practical Use of Spring Web Flow .................................................................................................
6.1. Sample applications .............................................................................................................. 72
6.2. Running the Web Flow sample applications ........................................................................... 72
6.2.1. Building from the Command Line .............................................................................. 72
6.2.2. Importing Projects into Eclipse ................................................................................... 73
6.2.3. Deploying projects inside Eclipse using Eclipse Web Tools (WTP) .............................. 73
6.2.4. Other IDE's ............................................................................................................... 73
6.3. Sellitem Example ................................................................................................................. 73
6.3.1. Overview .................................................................................................................. 74
Spring Web Flow
Spring Web Flow Version 1.0.3 iii
