<?xml version="1.0" encoding="UTF-8"?>
<preface id="preface">
	<title>Preface</title>
	<para>
		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.
	</para>
	<para>		
		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.
	</para>
	<para>
		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.
	</para>
	<para>
		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.
	</para>
</preface>

<chapter id="introduction">
	<title>Introduction</title>
	<sect1 id="introduction-overview">
		<title>Overview</title>
		<para>
			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.
		</para>
		<para>
			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
			<emphasis>conversation</emphasis>.
			Flows often execute across HTTP requests,
			have state, exhibit transactional characteristics,
			and may	be dynamic and/or long-running in nature.
		</para>
		<para>
			Spring Web Flow exists at a higher level of abstraction, integrating
			as a self-contained <emphasis>flow engine</emphasis> 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.
		</para>
	</sect1>
	<sect1 id="introduction-architecture-overview">
		<title>Architecture overview</title>
		<para>
			Spring Web Flow has been architected as a self-contained <emphasis>flow engine</emphasis>
			with few required dependencies on third-party APIs.  All dependencies are 
			carefully managed.
		</para>
		<para>
			At a minimum, to use Spring Web Flow you need:
		</para>
		<itemizedlist spacing="compact">
        	<listitem>
         		<para>spring-webflow (the framework)</para>
	        </listitem>
        	<listitem>
         		<para>spring-core (miscellaneous utility classes used internally by the framework)</para>
	        </listitem>
        	<listitem>
         		<para>spring-binding (the Spring data binding framework, used internally)</para>
	        </listitem>
        	<listitem>
         		<para>commons-logging (a simple logging facade, used internally)</para>
	        </listitem>
        	<listitem>
         		<para>OGNL (the default expression language)</para>
	        </listitem>
		</itemizedlist>
		<para>
			Most users will embed SWF as a component within a larger web application development
			framework, as SWF is a focused <emphasis>controller technology</emphasis> 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. 			
		</para>
		<para>
			<note>			
			Spring Web Flow, like Spring, is a <emphasis>layered</emphasis> 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 <emphasis>any</emphasis> environment.
			</note>
		</para>
	</sect1>
	<sect1 id="introduction-structure-layer-diagram">
		<title>Architectural layers</title>
		<para>
			Spring Web Flow is a layered framework.  A diagram of Spring Web Flow's layered architecture is
			shown below:
		</para>
		<mediaobject>
			<imageobject role="fo">
				<imagedata fileref="images/architecture-layer-diagram.png" format="PNG" align="center"/>
			</imageobject>
			<imageobject role="html">
				<imagedata fileref="images/architecture-layer-diagram.png" format="PNG" align="center"/>
			</imageobject>
			<caption>
				<para>Spring Web Flow layer diagram</para>
			</caption>
		</mediaobject>		
	</sect1>
	<sect1 id="introduction-structure-layer-description">
		<title>Layer descriptions</title>
		<para>
			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:
		</para>
		<itemizedlist spacing="compact">
			<listitem>
				<para>
					<emphasis>Subsystem name</emphasis> - The name of a layer subsystem.
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>Description</emphasis> - The purpose of the subsystem.
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>Packages</emphasis> - The Java packages that contain the source code for
					the subsystem. The packages are rooted at the <literal>org.springframework.webflow</literal>
					root package in the package hierarchy.
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>Subsystem interfaces</emphasis> - Central API elements exposed by the subsystem,
					typically through Java interfaces.
				</para>
			</listitem>
			<listitem>
				<para>
					<emphasis>Internal dependencies</emphasis> - Dependencies of the subsystem. These could be
					other subsystems of the layer or external libraries.
				</para>
			</listitem>
		</itemizedlist>
		<sect2 id="layer-execution-core">
			<title>The Execution Core Layer (Bottom Layer)</title>
			<para>
				Defines core flow definition and execution public APIs.  As the "bottom layer", this 
				layer is highly stable with no dependencies on any other layer.
			</para>
			<table>
				<title>Execution Core Subsystems</title>
				<tgroup cols="5">
					<colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
					<colspec colname="c3" colwidth="2*" />
					<colspec colname="c4" colwidth="2*" />
					<colspec colname="c5" colwidth="2*" />
					<thead>
						<row>
							<entry>Subsystem name</entry>
							<entry>Description</entry>
							<entry>Packages</entry>
							<entry>Subsystem interfaces</entry>
							<entry>Internal dependencies</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Core</entry>
            				<entry>
            					Foundational, generic types usable by all other subsystems.
            					Contains the default expression parser (OGNL-based) and
            					core collection types (AttributeMap and company).
            				</entry>
            				<entry>
            					core,
            					core.collection
            				</entry>
            				<entry>None</entry>
            				<entry>None</entry>
        	            </row>
						<row>
							<entry>Util</entry>
            				<entry>
            					Low level utilities used by all other parts of the system.
            				</entry>
            				<entry>
            					util
            				</entry>
            				<entry>None</entry>
            				<entry>None</entry>
        	            </row>
            			<row>
            				<entry>Flow Definition</entry>
            				<entry>
            					Central abstractions for modeling flow definitions.
            					These abstractions include <literal>FlowDefinition</literal>,
            					<literal>StateDefinition</literal>, and <literal>TransitionDefinition</literal>
            					that form the domain language for describing flows.
            				</entry>
            				<entry>
            					definition
            				</entry>
            				<entry>
            					FlowDefinition
            				</entry>
            				<entry>Core</entry>
        	       		</row>
           				<row>
            				<entry>Flow Definition Registry</entry>
            				<entry>
								Support for working with registries of flow definitions.  Flow 
								definitions eligible for execution are typically stored in 
								a registry providing lookup services.
            				</entry>
            				<entry>
            					definition.registry
            				</entry>
            				<entry>
            					FlowDefinitionRegistry,
            					FlowDefinitionLocator
            				</entry>
            				<entry>
            					Core,
            					Flow Definition
            				</entry>
        	       		</row>
           				<row>
            				<entry>External Context</entry>
            				<entry>
            					Provides normalized access to a client environment that has called into Spring Web Flow.
            				</entry>
            				<entry>
            					context,
            					context.servlet,
            					context.portlet
            				</entry>
            				<entry>
            					ExternalContext
            				</entry>
            				<entry>
								Core,
								context.servlet requires Servlet API 2.3,
								context.portlet requires Portlet API 1.0 in addition to Servlet API 2.3
            				</entry>
        	       		</row>
           				<row>
            				<entry>Conversation</entry>
            				<entry>
            					Manages the creation and cleanup of conversational state.  Used by 
            					the execution repository system to begin new user conversations and 
            					track execution state.
            				</entry>
            				<entry>
            					conversation,
            					conversation.impl
            				</entry>
            				<entry>
            					ConversationManager
            				</entry>
            				<entry>
								Core,
								Util,
								External Context
            				</entry>
        	       		</row>
           				<row>
            				<entry>Flow Execution</entry>
            				<entry>
								Stable runtime abstractions that define the flow definition
								execution model.  For executing flow definitions 
								and representing execution state.
            				</entry>
            				<entry>
            					execution,
            					execution.support,
            					execution.factory
            				</entry>
            				<entry>
            					FlowExecution
            				</entry>
            				<entry>
            					Core,
            					External Context,
            					Flow Definition
            				</entry>
        	       		</row>
           				<row>
            				<entry>Flow Execution Repository</entry>
            				<entry>
 								For persisting paused flow executions beyond a single request
								into the server.            				
            				</entry>
            				<entry>
            					execution.repository,
            					execution.repository.support,
            					execution.repository.continuation
            				</entry>
            				<entry>
            					FlowExecutionRepository
            				</entry>
            				<entry>
            					Core,
            					Util,
            					Flow Definition,
            					Conversation,
            					Flow Execution
            				</entry>
        	     		</row>
           				<row>
            				<entry>Action</entry>
            				<entry>
 								Reusable action implementations.        				
            				</entry>
            				<entry>
            					action,
            					action.portlet
            				</entry>
            				<entry>
            					None
            				</entry>
            				<entry>
            					Core,
            					Util,
            					Flow Definition,
            					External Context,
            					Flow Execution
            				</entry>
        	     		</row>
 					</tbody>
	    		</tgroup>
    		</table>
		</sect2>
		<sect2 id="layer-execution-engine">
			<title>The Execution Engine Layer</title>
   	        <para>
				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.
   	        </para>
   	        <para>
   	        	Depends On: Execution Core
   	        </para>
	    	<table>
    	        <title>Execution Engine Subsystems</title>
        	    <tgroup cols="5">
            	    <colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
    	            <colspec colname="c2" colwidth="2*" />
    	            <colspec colname="c2" colwidth="2*" />
	                <colspec colname="c2" colwidth="2*" />
	                <thead>
       		            <row>
               		        <entry>Subsystem name</entry>
               				<entry>Description</entry>
	                        <entry>Packages</entry>
	                        <entry>Subsystem interfaces</entry>
       		                <entry>Internal dependencies</entry>
           				</row>
		  			</thead>
				  	<tbody>
            			<row>
            				<entry>Engine Implementation</entry>
            				<entry>
								The implementation of the flow execution engine based on a finite state machine.
            				</entry>
            				<entry>
            					engine,
            					engine.support,
            					engine.impl
            				</entry> 
            				<entry>None</entry>
            				<entry>None</entry>
        	            </row>
            			<row>
            				<entry>Flow Definition Builder</entry>
            				<entry>
								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.	
            				</entry>
            				<entry>
            					engine.builder,
            					engine.builder.xml
            				</entry>
            				<entry>
            					<literal>FlowBuilder</literal>
            				</entry>
            				<entry>
            					Engine Implementation,
            					Spring Beans 1.2.7,
            					Spring Context 1.2.7,
            					<literal>builder.xml</literal> requires JDK 1.5 or Xerces for XSD support
            				</entry>
        	       		</row>
            	   </tbody>
	          </tgroup>
    	    </table>
		</sect2>
		<sect2 id="layer-execution-test">
			<title>The Test Layer</title>
			<para>
				Support for unit testing flow artifacts and system testing flow executions.
			</para>
			<para>
				Depends On: Execution Engine, Execution Core
			</para>
			<table>
				<title>Test Subsystems</title>
				<tgroup cols="5">
            	    <colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
    	            <colspec colname="c2" colwidth="2*" />
    	            <colspec colname="c2" colwidth="2*" />
	                <colspec colname="c2" colwidth="2*" />
	                <thead>
       		            <row>
               		        <entry>Subsystem name</entry>
               				<entry>Description</entry>
	                        <entry>Packages</entry>
	                        <entry>Subsystem interfaces</entry>
       		                <entry>Internal dependencies</entry>
           				</row>
		  			</thead>
					<tbody>
						<row>
							<entry>Engine Artifact Unit Test Support</entry>
            				<entry>
								Support for unit testing implementations such as Actions in isolation.		
            				</entry>
            				<entry>
            					test
            				</entry> 
            				<entry>None</entry>
            				<entry>JUnit 3.8.1</entry>
        	            </row>
            			<row>
            				<entry>Flow Execution Test Support</entry>
            				<entry>
       							Support for testing Flow Executions out-of-container.
            				</entry>
            				<entry>
            					test.execution
            				</entry>
            				<entry>None</entry>
            				<entry>
            					Spring Beans 1.2.7,
            					JUnit 3.8.1
            				</entry>
        	       		</row>
 					</tbody>
	    		</tgroup>
    		</table>
		</sect2>
		<sect2 id="layer-executor">
			<title>The Executor Layer</title>
			<para>
				Stable higher-layer for driving and coordinating the execution of flow definitions.
				This layer is decoupled from the more-volatile engine implementation.
			</para>
			<para>
				Depends On: Execution Core
			</para>
			<table>
				<title>Executor Subsystems</title>
				<tgroup cols="5">
					<colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
					<colspec colname="c2" colwidth="2*" />
					<colspec colname="c2" colwidth="2*" />
					<colspec colname="c2" colwidth="2*" />
					<thead>
						<row>
							<entry>Subsystem name</entry>
							<entry>Description</entry>
							<entry>Packages</entry>
							<entry>Subsystem interfaces</entry>
							<entry>Internal dependencies</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Core</entry>
            				<entry>
            					Stable, generic flow executor abstractions and support.
            				</entry>
            				<entry>
            					executor,
            					executor.support
            				</entry>
            				<entry>
            					<literal>FlowExecutor</literal>
            				</entry>
            				<entry>None</entry>
        	            </row>
						<row>
							<entry>Spring MVC</entry>
            				<entry>
            					The integration between Spring Web Flow and the Spring MVC framework.
            				</entry>
            				<entry>executor.mvc</entry>
            				<entry>None</entry>
            				<entry>
            					Core,
            					Spring Web MVC 1.2.7,
            					Portlet MVC requires Spring 2.0
            				</entry>
        	            </row>
						<row>
							<entry>Struts</entry>
            				<entry>
            					The integration between Spring Web Flow and the Struts Classic framework.
            				</entry>
            				<entry>
            					executor.struts
            				</entry>
            				<entry>None</entry>
            				<entry>
            					Core,
            					Struts 1.1
            				</entry>
        	            </row>
						<row>
							<entry>Java Server Faces (JSF)</entry>
            				<entry>
            					The integration between Spring Web Flow and the Java Server Faces framework.
            				</entry>
            				<entry>
            					executor.jsf
            				</entry>
            				<entry>None</entry>
            				<entry>
            					Core,
            					JSF 1.0
            				</entry>
        	            </row>
 					</tbody>
	    		</tgroup>
    		</table>
		</sect2>
		<sect2 id="layer-config">
			<title>The System Configuration Layer (Top Layer)</title>
			<para>
				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.
			</para>
			<para>
				Depends On: Executor, Execution Engine, Execution Core
			</para>
			<table>
				<title>System Configuration Subsystems</title>
				<tgroup cols="5">
					<colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
					<colspec colname="c2" colwidth="2*" />
					<colspec colname="c2" colwidth="2*" />
					<colspec colname="c2" colwidth="2*" />
					<thead>
						<row>
							<entry>Subsystem name</entry>
							<entry>Description</entry>
							<entry>Packages</entry>
							<entry>Subsystem interfaces</entry>
							<entry>Internal dependencies</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Spring Configuration Support</entry>
            				<entry>
								For configuring Spring Web Flow using Spring 1.x and 2.x.            				
            				</entry>
            				<entry>
            					config
            				</entry>
            				<entry>None</entry>
            				<entry>
            					Spring Beans 1.2.7,
            					<literal>spring-webflow-config-1.0</literal> XSD support requires Spring 2.0
            				</entry>
        	            </row>
 					</tbody>
	    		</tgroup>
    		</table>
			<para>
				<note>
					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 <literal>ExternalContext</literal> 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.
				</note>
			</para>
			<para>
				For the exact list of dependencies, as well as supported product usage configurations, 
				see the Ivy dependency manager descriptor located within the SWF distribution.
			</para>
		</sect2>
	</sect1>
	<sect1 id="introduction-support">
		<title>Support</title>
		<para>
			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.
		</para>
		<para>
			XML-based flow building requires Xerces 2 or JDK 5.0 (for XSD support).
		</para>
		<para>
			The Spring Web Flow Portlet integration requires Spring Portlet MVC 2.0.
		</para>
		<para>
		    Our active community support forum is located at http://forum.springframework.org.
		</para>
	</sect1>
</chapter>