<?xml version="1.0" encoding="UTF-8"?>
<chapter id="flow-definition">
	<title>Flow definition</title>
	<sect1 id="flow-intro">
		<title>Introduction</title>
		<para>
			Spring Web Flow allows developers to build reusable, self-contained controller modules
			called flows.  A flow defines a user dialog that responds to user events to drive
			the execution of application code to complete a business goal.
		</para>
		<para>
			Flows are defined declaratively using a rich domain-specific language (DSL)
			tailored to the problem domain of UI flow.  Currently, XML and Java-based
			forms of this language are provided.
		</para>
		<para>
			This chapter documents Spring Web Flow's core flow definition language.  You will
			learn the core domain constructs of the system and how those constructs are
			representable in an externalized XML form.
		</para>
    </sect1>
    <sect1 id="flow">
    	<title>FlowDefinition</title>
    	<para>
    		A flow definition is a instance of <literal>org.springframework.webflow.definition.FlowDefinition</literal>.
    		This is the central domain artifact representing the definition of a user dialog or task.
		</para>
		<para>
    		A flow definition consists of a set of one or more states, where each state defines a step in
    		the flow that when entered executes a behavior.  What behavior is executed is
    		a function of the state's type and configuration.  The outcome of a state's
    		execution, called an event, is used by the flow to drive a state transition.
    	</para>
    	<para>
			Exactly one of a flow's states is the <literal>startState</literal>
			that defines the starting point of the flow. Optionally, a flow can have one or more end states
			defining the ending points of the flow.
    	</para>
    	<para>
    		An example definition of a simple flow to carry out a search process is shown graphically below:
    	</para>
		<mediaobject>
			<imageobject role="fo">
				<imagedata fileref="images/flow-search.png" format="PNG" align="center"/>
			</imageobject>
			<imageobject role="html">
				<imagedata fileref="images/flow-search.png" format="PNG" align="center"/>
			</imageobject>
			<caption>
				<para>Search Flow</para>
			</caption>
		</mediaobject>
    	<para>
    		The default <literal>FlowDefinition</literal> implementation in Spring Web Flow is
    		<literal>org.springframework.webflow.engine.Flow</literal>.  Its configurable properties are
    		summarized below:
    	</para>
        <table frame="all">
            <title>Flow properties</title>
            <tgroup cols="4">
                <colspec colname="c1" colwidth="2*" />
                <colspec colname="c2" colwidth="4*" />
                <colspec colname="c2" colwidth="2*" />
                <colspec colname="c2" colwidth="2*" />
                <thead>
                    <row>
                        <entry>Property name</entry>
                        <entry>Description</entry>
                        <entry>Cardinality</entry>
                        <entry>Default value</entry>
                    </row>
               </thead>
               <tbody>
                   <row>
                       <entry>id</entry>
                       <entry>The identifier of the flow definition, typically unique to all other flows of the application.</entry>
				       <entry>
				           <emphasis>1</emphasis>
				       </entry>
                   </row>
                   <row>
                       <entry>attributes</entry>
                       <entry>Additional custom attributes about the flow.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>None</entry>
                   </row>
                   <row>
                       <entry>states</entry>
                       <entry>The steps of the flow.</entry>
				       <entry>
				           <emphasis>1..*</emphasis>
				       </entry>
                   </row>
                   <row>
                       <entry>startState</entry>
                       <entry>The starting point of the flow.</entry>
				       <entry>
				           <emphasis>1</emphasis>
				       </entry>
                   </row>
                   <row>
                       <entry>variables</entry>
                       <entry>The set of flow variables to create each time an execution of the flow is started.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
                   <row>
                       <entry>inputMapper</entry>
                       <entry>
                           The service responsible for mapping flow input provided by a caller each time an
                           execution of the flow is started.
                       </entry>
				       <entry>
				           <emphasis>0..1</emphasis>
				       </entry>
				       <entry>Null</entry>
                   </row>
                   <row>
                       <entry>startActions</entry>
                       <entry>The list of actions to execute each time an execution of the flow is started.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
                   <row>
                       <entry>endActions</entry>
                       <entry>The list of actions to execute each time an execution of the flow ends.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
                   <row>
                       <entry>outputMapper</entry>
                       <entry>
                           The service responsible for mapping flow output to expose to the caller each time an
                           execution of the flow ends.
                       </entry>
				       <entry>
				           <emphasis>0..1</emphasis>
				       </entry>
				       <entry>Null</entry>
                   </row>
                   <row>
                       <entry>globalTransitions</entry>
                       <entry>The set of transitions shared by all states of the flow.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
                   <row>
                       <entry>exceptionHandlers</entry>
                       <entry>An ordered set of handlers to be applied when an exception is thrown within a state of the flow.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
                   <row>
                       <entry>inlineFlows</entry>
                       <entry>A set of inner flows that will be called as subflows; these flows are locally scoped to the outer flow.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
               </tbody>
          </tgroup>
        </table>
        <para>
            Below is a high level example of how these properties can be configured in XML form
            or directly in Java code.
        </para>
        <sect2 id="flow-xml">
        	<title>XML-based Flow template</title>
       	    <programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;attribute .../&gt;

        &lt;var .../&gt;

        &lt;input-mapper .../&gt;

        &lt;start-actions&gt;
            ...
        &lt;/start-actions&gt;

        &lt;start-state idref="yourStartingStateId"/&gt;

        &lt;-- your state definitions go here --&gt;

        &lt;global-transitions&gt;
            ...
        &lt;/global-transitions&gt;

        &lt;end-actions&gt;
            ...
        &lt;/end-actions&gt;

        &lt;output-mapper .../&gt;

        &lt;exception-handler .../&gt;

        &lt;inline-flow&gt;
            ...
        &lt;/inline-flow&gt;

    &lt;/flow&gt;
         	</programlisting>
        </sect2>
        <sect2 id="flow-java">
           <title>Java Flow API example</title>
           <programlisting>
    Flow flow = new Flow("id");
    flow.getAttributeMap().put("name", "value");
    flow.addState(...);
    flow.setStartState("startingPoint");
    flow.addVariable(...);
    flow.setInputMapper(...);
    flow.getStartActionList().add(...);
    flow.getEndActionList().add(...);
    flow.setOutputMapper(...);
    flow.getGlobalTransitionSet().add(...);
    flow.getExceptionHandlerSet().add(...);
    flow.addInlineFlow(...);
          </programlisting>
          <para>
              A Flow is typically built by a FlowBuilder rather than assembled
              by hand.  The flow building subsystem is contained within the
              <literal>org.springframework.webflow.engine.builder</literal> package.
              The XML Flow Builder and <literal>spring-webflow.xsd</literal> schema are located
              within the <literal>org.springframework.webflow.engine.builder.xml</literal> package.
              The XML-based format is the most popular way to define flows.
          </para>
        </sect2>
    </sect1>
    <sect1 id="state">
    	<title>StateDefinition</title>
    	<para>
    	    A <literal>StateDefinition</literal> defines the behavior for a step of a <literal>FlowDefinition</literal>.
    	    The base implementation class for all Flow state types is <literal>org.springframework.webflow.engine.State</literal>.
    	    This abstract class defines common properties applicable to all state types, which include:
    	</para>
    	<table>
            <title>State properties</title>
            <tgroup cols="4">
                <colspec colname="c1" colwidth="2*" />
                <colspec colname="c2" colwidth="4*" />
                <colspec colname="c2" colwidth="2*" />
                <colspec colname="c2" colwidth="2*" />
                <thead>
                    <row>
                        <entry>Property name</entry>
                        <entry>Description</entry>
                        <entry>Cardinality</entry>
                        <entry>Default value</entry>
                    </row>
               </thead>
               <tbody>
                   <row>
                       <entry>id</entry>
                       <entry>The id of the state, unique to its containing flow definition.</entry>
				       <entry>
				           <emphasis>1</emphasis>
				       </entry>
                   </row>
                   <row>
                       <entry>owner</entry>
                       <entry>The owning flow definition.</entry>
				       <entry>
				           <emphasis>1</emphasis>
				       </entry>
                   </row>
                   <row>
                       <entry>attributes</entry>
                       <entry>Additional custom attributes about the state.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>None</entry>
                   </row>
                   <row>
                       <entry>entryActions</entry>
                       <entry>The list of actions to execute each time the state is entered.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
                   <row>
                       <entry>exceptionHandlers</entry>
                       <entry>An ordered set of handlers to be invoked when an exception is thrown within the state.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
               </tbody>
          </tgroup>
        </table>
    </sect1>
    <sect1 id="transitionable-state">
    	<title>Transitionable State</title>
    	<para>
    	    A central subclass of State is <literal>org.springframework.webflow.TransitionableState</literal>.
    	    This abstract class defines common properties applicable to all state types that execute
    	    transitions to other states in response to events.  These properties include:
    	</para>
    	<table>
            <title>TransitionableState properties</title>
            <tgroup cols="4">
                <colspec colname="c1" colwidth="2*" />
                <colspec colname="c2" colwidth="4*" />
                <colspec colname="c2" colwidth="2*" />
                <colspec colname="c2" colwidth="2*" />
                <thead>
                    <row>
                        <entry>Property name</entry>
                        <entry>Description</entry>
                        <entry>Cardinality</entry>
                        <entry>Default value</entry>
                    </row>
               </thead>
               <tbody>
                   <row>
                       <entry>transitions</entry>
                       <entry>The eligible paths out of this state.</entry>
				       <entry>
				           <emphasis>1..*</emphasis>
				       </entry>
                   </row>
                   <row>
                       <entry>exitActions</entry>
                       <entry>The list of actions to execute each time this state is exited.</entry>
				       <entry>
				           <emphasis>0..*</emphasis>
				       </entry>
				       <entry>Empty</entry>
                   </row>
               </tbody>
          </tgroup>
        </table>
        <para>
            Below is a mock flow definition snippet showing how properties may be configured for
            a TransitionableState in XML and in Java code:
        </para>
        <sect2 id="state-xml">
        	<title>XML-based state template</title>
       	    <programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="myStateId"/&gt;

        &lt;xxx-state id="myStateId"&gt;
            &lt;attribute name="..." value="..."/&gt;

            &lt;entry-actions&gt;
                ...
            &lt;/entry-actions&gt;

            &lt;transition on="..." to="..."/&gt;
            &lt;transition on-exception="..." to="..."/&gt;

            &lt;exit-actions&gt;
    	        ...
            &lt;/exit-actions&gt;

            &lt;exception-handler .../&gt;
        &lt;/xxx-state&gt;

    &lt;/flow&gt;
         	</programlisting>
        </sect2>
        <sect2 id="state-java">
           <title>Java state API example</title>
           <programlisting>
    Flow flow = new Flow("id");
    TransitionableState state = new XXXState(flow, "stateId");
    state.getAttributeMap().put("name", "value");
    state.getEntryActionList().add(...);
    state.getTransitionSet().add(...);
    state.getExitActionList().add(...);
          </programlisting>
	        <para>
	            A State is typically constructed by a <literal>FlowArtifactFactory</literal>, used by
	            a <literal>FlowBuilder</literal> during flow assembly.  The flow building subsystem is contained within the
	            <literal>org.springframework.webflow.engine.builder</literal> package.
	        </para>
        </sect2>
    </sect1>
    <sect1 id="transition">
    	<title>TransitionDefinition</title>
    	<para>
    	    A transition takes a flow from one state to another, defining a <emphasis>path</emphasis> through the flow.
    	    This is modeled using a <literal>TransitionDefinition</literal>.
    	</para>
    	<para>
    	    Recall that all TransitionableStates have a set of one or more transitions, each defining a
    	    path to another state in the flow (or a recursive path back to the same state).
    	    When a transitionable state is entered it executes a behavior.
    	    For example, a transitionable state called "Display Form" may display a form to the user
    	    and wait for user input.  The outcome of the state's execution, called an event, is used to drive execution of
    	    one of the state's transitions.  For example, the user may press the form submit button which
    	    signals a <emphasis>submit</emphasis> event that matches the transition to
    	    the "Process Submit" state.
    	</para>
    	<para>
    		This event-driven transition execution process is shown graphically below:
    	</para>
		<mediaobject>
			<imageobject role="fo">
				<imagedata fileref="images/transition-statediagram.jpg" format="JPEG" align="center"/>
			</imageobject>
			<imageobject role="html">
				<imagedata fileref="images/transition-statediagram.jpg" format="JPEG" align="center"/>
			</imageobject>
			<caption>
				<para>Transition execution</para>
			</caption>
		</mediaobject>
		<para>
			The transition definition implementation is defined by an instance of
			<literal>org.springframework.webflow.engine.Transition</literal>.
			Its properties are summarized below:
		</para>
    	<table>
   	        <title>Transition properties</title>
       	    <tgroup cols="4">
           	    <colspec colname="c1" colwidth="2*" />
       			<colspec colname="c2" colwidth="4*" />
   	            <colspec colname="c2" colwidth="2*" />
                <colspec colname="c2" colwidth="2*" />
                <thead>
    	            <row>
           		        <entry>Property name</entry>
           				<entry>Description</entry>
                        <entry>Cardinality</entry>
    	                <entry>Default value</entry>
       				</row>
	  			</thead>
			  	<tbody>
           			<row>
           				<entry>attributes</entry>
						<entry>Additional attributes describing the transition.</entry>
					    <entry>
							<emphasis>0..*</emphasis>
						</entry>
						<entry>None</entry>
       	            </row>
           			<row>
           				<entry>matchingCriteria</entry>
						<entry>The strategy that determines if the transition matches on an event occurrence.</entry>
					    <entry>
							<emphasis>1</emphasis>
						</entry>
						<entry>Always matches</entry>
       	            </row>
           			<row>
           				<entry>executionCriteria</entry>
						<entry>The strategy that determines if the transition, once matched, is allowed to execute.</entry>
					    <entry>
							<emphasis>1</emphasis>
						</entry>
						<entry>Always allowed</entry>
        	        </row>
           			<row>
           				<entry>targetStateResolver</entry>
						<entry>
							The strategy that resolves the target state of the transition.
							Most transitions always resolve to the same target state.
							This strategy allows for dynamic resolution.
						</entry>
					    <entry>
							<emphasis>1</emphasis>
						</entry>
						<entry></entry>
       	           </row>
           	   </tbody>
          </tgroup>
   	    </table>
   	    <para>
            Below is a high-level example of how a Transition can be configured in XML form
            or directly in Java code.
   	    </para>
        <sect2 id="transition-xml">
        	<title>Transition XML template</title>
       	    <programlisting>
    &lt;transition on="event" to="targetState"&gt;
        &lt;attribute ... /&gt;
        &lt;action ... /&gt;
    &lt;/transition&gt;
         	</programlisting>
        </sect2>
        <sect2 id="transition-java">
        	<title>Transition Java API example</title>
       	    <programlisting>
    Transition transition = new Transition("targetState");
    transition.getAttributeMap().put("name", "value");
    transition.setMatchingCriteria(new EventIdTransitionCriteria("event"));
    transition.setExecutionCriteria(...);
         	</programlisting>
        </sect2>
        <sect2 id="transition-actioncriteria">
        	<title>Action transition execution criteria</title>
         	<para>
         		In the XML transition template above note the support for the <literal>action</literal> element within the <literal>transition</literal> element.
         	</para>
         	<para>
         		A transition may be configured with one or more actions that execute <emphasis>before</emphasis> the transition itself
         		executes as <literal>executionCriteria</literal>.  If one or more of these
         		actions do not complete successfully the transition will <emphasis>not</emphasis> be allowed.
         		This <emphasis>action transition criteria</emphasis> makes it possible to execute arbitrary logic
         		after a transition is matched but before it is executed.  This is useful when you want to execute
         		event post-processing logic.  A good example is executing form data binding and validation behavior
         		after a form submit event.
         	</para>
        </sect2>
        <sect2 id="transition-dynamic">
        	<title>Dynamic transitions</title>
        	<para>
	        	A transition's target state resolver can be configured to dynamically calculate the
    	    	target state.  For example:
    	    </para>
       	    <programlisting>
    &lt;transition on="back" to="${flowScope.lastStateId}" /&gt;
         	</programlisting>
         	<para>
         		This will transition the flow to the state resolved by evaluating the
         		<literal>flowScope.lastStateId</literal> expression.
         	</para>
        </sect2>
        <sect2 id="transition-global">
        	<title>Global transitions</title>
        	<para>
        		As outlined, one or more transitions are added to all TransitionableState types,
        		attached at the state-level.  Optionally, transitions may also be added at the
        		<emphasis>flow-level</emphasis> where they are shared by all states.  These shared
        		transitions are called <emphasis>global transitions</emphasis>.
        	</para>
        	<para>
        	    When an event is signaled in a transitionable state the state will first try and
        	    match one of its own transitions.  If there is no match at the state level the set of
        	    global transitions will be tested.  If there still is no match
        	    a <literal>NoMatchingTransitionException</literal> will be thrown.
        	</para>
        	<para>
        	    Global transitions are useful in situations where many states of the flow share
        	    the same transitional criteria.  For example, consider a navigation menu that displays
        	    alongside each view of a flow.  Logic to process navigation menu events is needed
        	    by all view states.  This is the problem global transitions are designed to solve.
        	</para>
        	<sect3 id="transition-globalXml">
    	    	<title>Global transitions - XML example</title>
    	    	<para>
    	    	    The following example shows transitions defined at the state level, as well as
    	    	    global transitions defined at the flow level.
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="state1"/&gt;

        &lt;xxx-state id="state1"&gt;
            &lt;transition on="localEvent1" to="state2"/&gt;
        &lt;/xxx-state&gt;

        &lt;xxx-state id="state2"&gt;
            &lt;transition on="localEvent1" to="state1"/&gt;
        &lt;/xxx-state&gt;

        &lt;global-transitions&gt;
            &lt;transition on="globalEvent1" to="state1"/&gt;
            &lt;transition on="globalEvent2" to="state2"/&gt;
        &lt;/global-transitions&gt;

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    In this mock example <literal>state1</literal> defines one transition and also inherits
    			    the two others defined within the <literal>global-transitions</literal> element.
    			    Any other states defined within this flow would also inherit those global
    			    transitions.
    			</para>
    			<para>
    			    This example is shown graphically below:
    			</para>
				<mediaobject>
					<imageobject role="fo">
						<imagedata fileref="images/globaltransitions-statediagram.png" format="PNG" align="center"/>
					</imageobject>
					<imageobject role="html">
						<imagedata fileref="images/globaltransitions-statediagram.png" format="PNG" align="center"/>
					</imageobject>
					<caption>
						<para>Global transitions</para>
					</caption>
				</mediaobject>
			</sect3>
		</sect2>
        <sect2 id="transition-exception-handling">
        	<title>Transition executing state exception handlers</title>
        	<para>
        		The <literal>&lt;transition/&gt;</literal> element contains an exclusive <literal>on-exception</literal>
        		attribute used to specify an exception-based criteria for transition execution.  This allows you to
        		transition the flow to another state on the occurrence of an exception.
        	</para>
        	<sect3 id="transition-onExceptionXml">
    	    	<title>Exception handling - XML example</title>
    	    	<para>
    	    	    The following example shows a transition that is applied as a state exception handler:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="state1"/&gt;

        &lt;xxx-state id="state1"&gt;
            &lt;transition on="event1" to="state2"/&gt;
            &lt;transition on-exception="example.MyBusinessException" to="state3"/&gt;
        &lt;/xxx-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    In this example <literal>state1</literal> defines one transition and an exception handler
    			    which executes a transition to <literal>state3</literal> if a <literal>MyBusinessException</literal>
    			    is thrown within the state. The handled exception will be put into flash scope using the
    			    key "stateException". That way it is available for processing in the flow or display in a view.
    			</para>
   			</sect3>
		</sect2>
    </sect1>
    <sect1 id="core-states">
    	<title>Concrete state types</title>
    	<para>
    		Spring Web Flow has five (5) built-in concrete state types, all contained within the
    		<literal>org.springframework.webflow.engine</literal> package.  These states execute common
    		controller behaviors including:
    		<orderedlist>
    			<listitem><para>allowing the user to participate in a flow (ViewState)</para></listitem>
    			<listitem><para>executing business application code (ActionState)</para></listitem>
    			<listitem><para>making a flow routing decision (DecisionState)</para></listitem>
    			<listitem><para>spawning another flow as a subflow (SubflowState)</para></listitem>
    			<listitem><para>terminating a flow (EndState)</para></listitem>
    		</orderedlist>
    	</para>
    	<para>
    		Each of these state types, with the exception of EndState, is transitionable.
    		This hierarchy is illustrated below:
    	</para>
		<mediaobject>
			<imageobject role="fo">
				<imagedata fileref="images/flowdefinition-classdiagram.png" format="PNG" align="center"/>
			</imageobject>
			<imageobject role="html">
				<imagedata fileref="images/flowdefinition-classdiagram.png" format="PNG" align="center"/>
			</imageobject>
			<caption>
				<para>FlowDefinition class diagram</para>
			</caption>
		</mediaobject>
    	<para>
    		As you will see, with these five basic state types you can develop rich controller modules.
    	</para>
    	<sect2 id="viewState">
    		<title>ViewState</title>
    		<para>
    			When entered a view state allows the user (or other external client) to participate
    			in a flow.  This participation process goes as follows:
    			<orderedlist>
    				<listitem>
    					<para>
	    					The entered view state makes a <literal>org.springframework.webflow.execution.ViewSelection</literal>
		   	 				that represents a <emphasis>logical</emphasis> response to issue to the caller.
   		 				</para>
    				</listitem>
    				<listitem>
    					<para>
	    					The flow execution 'pauses' in this state, and control is returned to the calling
    						system.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
	    				    The calling system uses the returned <literal>ViewSelection</literal> to present a
    					    suitable interface (or other response) to the user.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
	    				    After some 'think time' the user signals an input event to resume the flow execution
    					    from the 'paused' point.
    					</para>
    				</listitem>
    			</orderedlist>
    		</para>
    		<para>
    		    Spring Web Flow gives you full control over the view selection process and, on resume,
    		    how a view state responds to a user input event.  It's important to understand that Spring Web Flow is <emphasis>not</emphasis>
    		    responsible for response rendering--as a controller, a flow makes a <emphasis>logical</emphasis> view selection when user input is required,
    		    where a view selection serves as a response instruction.  It is up to the calling system to interpret that instruction to issue a
    		    response suitable for the environment in which the flow is executing.
    		</para>
    	    <para>
    	    	The properties of a <literal>org.springframework.webflow.engine.ViewState</literal> are summarized below:
    	    </para>
	    	<table>
    	        <title>ViewState properties</title>
        	    <tgroup cols="4">
            	    <colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
    	            <colspec colname="c2" colwidth="2*" />
	                <colspec colname="c2" colwidth="2*" />
	                <thead>
       		            <row>
               		        <entry>Property name</entry>
               				<entry>Description</entry>
	                        <entry>Cardinality</entry>
       		                <entry>Default value</entry>
           				</row>
		  			</thead>
				  	<tbody>
            			<row>
              				<entry>viewSelector</entry>
							<entry>The strategy that makes the view selection when this state is entered.</entry>
						    <entry>
								<emphasis>0..1</emphasis>
					       </entry>
					       <entry>Null</entry>
					    </row>
            			<row>
              				<entry>renderActions</entry>
							<entry>
								The list of actions to execute each time a renderable view selection is made.
								Allows for execution of pre-render logic.
							</entry>
						    <entry>
								<emphasis>0..*</emphasis>
					       </entry>
					       <entry>Empty</entry>
        	           </row>
            	   </tbody>
	          </tgroup>
    	    </table>
    	    <para>
    	    	The <literal>org.springframework.webflow.execution.ViewSelection</literal> base class is abstract,
    	    	acting as a marker indicating a response should be issued to the client interacting
    	    	with the flow.  Concrete subtypes exist for each of the supported response types.
    	    	These response types are summarized below:
    	    </para>
	    	<table>
    	        <title>Concrete ViewSelection types</title>
        	    <tgroup cols="2">
            	    <colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
	                <thead>
       		            <row>
               		        <entry>Type</entry>
               				<entry>Description</entry>
           				</row>
		  			</thead>
				  	<tbody>
            			<row>
              				<entry>ApplicationView</entry>
              				<entry>Requests the rendering of a local, internal application view resource such as a JSP, Velocity, or Freemarker template.</entry>
 						</row>
            			<row>
              				<entry>FlowExecutionRedirect</entry>
              				<entry>
              					Requests a redirect back to the ViewState at a unique <emphasis>flow execution URL</emphasis>.
              					When this URL is accessed on subsequent requests an ApplicationView will be reconstituted and rendered.
              					The URL is refreshable while the flow execution remains active.
								<note>
									<para>
    	          						Multiple flow execution URLs may be generated for a single logical user conversation.
       		       						In that case each flow execution URL provides access to the conversation
       	   	    						from a previous point (ViewState).  Accessing the URL refreshes the execution
           		   						from that point.
              						</para>
              					</note>
              				</entry>
 						</row>
            			<row>
              				<entry>FlowDefinitionRedirect</entry>
              				<entry>
              					Requests a redirect that launches an entirely new flow execution.  Used to support
              					<emphasis>redirect to flow</emphasis> (flow chaining) and <emphasis>restart flow</emphasis> use cases.
              				</entry>
 						</row>
            			<row>
              				<entry>ExternalRedirect</entry>
              				<entry>
              					Requests a redirect to an arbitrary external URL, typically used to inteface
              					with an external system.
              				</entry>
 						</row>
            			<row>
              				<entry>NullView</entry>
              				<entry>
              					Requests that no response be issued; for use in corner cases where the flow itself has already
              					issued the response.
              				</entry>
 						</row>
            	   </tbody>
	          </tgroup>
    	    </table>
    	    <sect3 id="viewSelector">
    			<title>ViewSelector</title>
	    		<para>
    				The creational strategy responsible for making a <literal>ViewSelection</literal> when an <literal>ViewState</literal> is entered
    				is <literal>org.springframework.webflow.engine.ViewSelector</literal>.  This provides a plugin-point for customizing <emphasis>how</emphasis>
    				a response instruction is constructed.
    			</para>
    			<para>
    			    Four <literal>ViewSelector</literal> implementations are provided with Spring Web Flow:
    			</para>
	    		<table>
    	   			<title>ViewSelector implementations</title>
        		    <tgroup cols="2">
		           	    <colspec colname="c1" colwidth="2*" />
        				<colspec colname="c2" colwidth="4*" />
	        	        <thead>
       		    	        <row>
               			        <entry>Implementation</entry>
               					<entry>Description</entry>
               			    </row>
						</thead>
					  	<tbody>
            				<row>
              					<entry>ApplicationViewSelector</entry>
								<entry>
									Returns an ApplicationView referencing a logical <literal>viewName</literal> to render and containing a
									<literal>modelMap</literal> with the application data needed by the rendering process
									(by default, this map contains the union of the data scopes such flow, flash, and request scope).
									Supports setting a <literal>redirect</literal> flag that triggers
									a browser redirect to the selected view using a <literal>FlowExecutionRedirect</literal>.
									The default implementation.
								</entry>
	        	   	        </row>
	        	   	        <row>
              					<entry>FlowDefinitionRedirectSelector</entry>
								<entry>
									Returns a FlowDefinitionRedirect with a <literal>flowId</literal> and <literal>executionInput</literal> map requesting
									the launch of an entirely new flow execution (an instance of the FlowDefinition identified by the flowId).
									Useful for <emphasis>redirect after flow completion</emphasis>, where one flow ending should trigger
									the start of another flow independently.
								</entry>
	        	   	        </row>
            				<row>
              					<entry>ExternalRedirectSelector</entry>
								<entry>
									Returns an ExternalRedirect that triggers a browser redirect to an abitrary external URL.
									Mainly used by end states to redirect to external systems after flow completion,
									but can also be used by view states to interface with an external system that may
									call back into the flow execution at a later point.
								</entry>
	        	   	        </row>
            				<row>
              					<entry>NullViewSelector</entry>
								<entry>
									Returns an NullView indicating that no response should be issued.
								</entry>
	        	   	        </row>
	            		</tbody>
		       		</tgroup>
    		    </table>
    		</sect3>
    		<sect3>
    			<title>ViewState class diagram</title>
	    		<para>
	    			The class diagram below shows the ViewState and the associated types used to carry
	    			out the view selection process:
	    		</para>
				<mediaobject>
					<imageobject role="fo">
						<imagedata fileref="images/viewstate-classdiagram.png" format="PNG" align="center"/>
					</imageobject>
					<imageobject role="html">
						<imagedata fileref="images/viewstate-classdiagram.png" format="PNG" align="center"/>
					</imageobject>
					<caption>
						<para>ViewState class diagram</para>
					</caption>
				</mediaobject>
    		</sect3>
    	    <sect3 id="viewStateXml">
    	    	<title>ViewState XML - application view selection</title>
    	    	<para>
    	    	    The following example shows a <literal>view-state</literal> definition in XML that makes an application view
    	    	    selection when entered, selecting the <literal>searchForm</literal> view for display and, on resume, responding to
    	    	    two possible user input events (submit and cancel) in different ways:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="displaySearchForm"/&gt;

        &lt;view-state id="displaySearchForm" view="searchForm"&gt;
            &lt;transition on="submit" to="processFormSubmission"/&gt;
            &lt;transition on="cancel" to="processCancellation"/&gt;
        &lt;/view-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    				View name expressions may also be specified for the <literal>view</literal> attribute to
    				achieve runtime view name calculation.
    				For example, <literal>view="${requestScope.calculatedViewName}"</literal>.
    			</para>
			</sect3>
    	    <sect3 id="viewStateJava">
    	    	<title>ViewState API - application view selection</title>
    	    	<para>
    	    	    The following example shows the equivalent view state definition using
    	    	    the FlowBuilder API:
    	    	</para>
    	    	<programlisting>
    public class SearchFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
    	    addViewState("displaySearchForm", "searchForm",
    	        new Transition[] {
    	            transition(on("submit"), to("processFormSubmission")),
    	            transition(on("cancel"), to("processFormCancellation"))
    	        }
    	    );
            ...
        }
    }
    			</programlisting>
			</sect3>
    	    <sect3 id="viewStateXml-redirect">
    	    	<title>ViewState XML - flow execution redirect</title>
    	    	<para>
    	    	    The following example illustrates a <literal>view-state</literal> definition in XML that makes an
    	    	    flow execution redirect selection when entered, redirecting to the
    	    	    <literal>yourList</literal> view for display.
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="displayList"/&gt;

        &lt;view-state id="displayList" view="redirect:yourList"&gt;
            &lt;transition on="add" to="addListItem"/&gt;
        &lt;/view-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
				<para>
				    This example is called a <emphasis>flow execution redirect</emphasis> because the application view selected
				    is rendered only after a redirect to the flow execution.  The redirect request is sent to a
				    URL that <emphasis>refreshes</emphasis> the flow execution paused in the <literal>displayList</literal>
				    view state.  Refresh then triggers the rendering of the <literal>yourList</literal> application view
				    on the next request into the server.
				</para>
				<sect4 id="viewState-POST-REDIRECT-GET">
					<title>POST+REDIRECT+GET in Spring Web Flow</title>
					<para>
						The above example is one way to achieve the <literal>POST+REDIRECT+GET</literal> pattern in Spring Web Flow.
						When the redirect is performed, the GET request issued hits a stable <emphasis>flow execution URL</emphasis>
						which remains active for the duration of the conversation.  This URL may be freely refreshed.
						Browser navigational buttons may be used freely without browser warnings.
					</para>
					<para>
				 	    Later in this document the execution attribute <literal>alwaysRedirectOnPause</literal> is discussed,
				 	    which enforces this pattern by default.  In that case each time a view state is entered
				 	    a redirect is always performed--<emphasis>automatically</emphasis>.
					</para>
				</sect4>
			</sect3>
    	    <sect3 id="viewStateJava-redirect">
    	    	<title>ViewState API - flow execution redirect</title>
    	    	<para>
    	    	    The following example shows the equivalent view state definition using
    	    	    the FlowBuilder API:
    	    	</para>
    	    	<programlisting>
    public class SearchFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
    	    addViewState("displayList", viewSelector("redirect:yourView"),
   	            transition(on("add"), to("addListItem"))
    	    );
            ...
        }
    }
    			</programlisting>
			</sect3>
    	    <sect3 id="viewStateXml-nullView">
    	    	<title>ViewState XML - null view</title>
    	    	<para>
    	    	    The following example illustrates a <literal>view-state</literal> definition in XML that makes a
    	    	    null view selection when entered, which causes no additional response to be issued.
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="displayPdf"/&gt;

        &lt;view-state id="displayPdf"&gt;
            &lt;render-actions&gt;
                &lt;action bean="pdfWriter" method="write"/&gt;
            &lt;/render-actions&gt;
        &lt;/view-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
			</sect3>
			<sect3 id="viewState-flowDefinitionRedirectAndExternalRedirect">
    	    	<title>FlowDefinitionRedirect and ExternalRedirect</title>
				<para>
					The <literal>FlowDefinitionRedirect</literal> and <literal>ExternalRedirect</literal> are not
					normally used with a view state. Instead they're used in an end state to continue with another,
					independent flow or to redirect to an external URL. Examples are provided in the discussion of the
					end state.
				</para>
			</sect3>
    	    <sect3 id="viewStateXml-formState">
    	    	<title>ViewState XML - form state behavior</title>
    	    	<para>
    	    	    The following example illustrates a <literal>view-state</literal> definition in XML that encapsulates
    	    	    typical "form state" behavior.
    	    	</para>
    	    	<para>
    	    	    Consider the requirements of typical input forms.  Most forms require <emphasis>pre-render</emphasis> or
    	    	    <emphasis>setup</emphasis> logic to execute before the form is displayed.  For example, such logic might
    	    	    load the <emphasis>backing form object</emphasis> from the database, install formatters for formatting
    	    	    form field values, and pull in supporting form data needed to populate drop-down menus.
    	    	</para>
    	    	<para>
    	    	    In addition, most forms require <emphasis>post-back</emphasis> or <emphasis>submission</emphasis> logic
    	    	    to execute when the form is submitted.  This logic typically involves binding form input to the
    	    	    <emphasis>backing form object</emphasis> and performing type conversion and data validation.
    	    	</para>
    	    	<para>
    	    	    This "form state" behavior of form setup, display, and post-back is handled elegantly in Spring Web Flow
    	    	    by the capabilities of the <literal>view-state</literal> construct.  See below:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="displayForm"/&gt;

        &lt;view-state id="displayForm" view="form"&gt;
            &lt;render-actions&gt;
                &lt;action bean="formAction" method="setupForm"/&gt;
                &lt;action bean="formAction" method="loadFormReferenceData"/>
            &lt;/render-actions&gt;
            &lt;transition on="submit" to="saveForm"&gt;
                &lt;action bean="formAction" method="bindAndValidate"/&gt;
            &lt;/transition&gt;
        &lt;/view-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			   This reads "<emphasis>when this flow starts enter the <literal>displayForm</literal> state
    			   to execute the <literal>setupForm</literal> and <literal>loadFormReferenceData</literal> methods
    			   before rendering the <literal>form</literal> view. On <literal>submit</literal>,
    			   transition to the <literal>saveForm</literal> state if the <literal>bindAndValidate</literal> method executes successfully.</emphasis>"
    			</para>
			</sect3>
    	</sect2>
    	<sect2 id="actionState">
    		<title>ActionState</title>
    		<para>
    			When entered, an action state executes business application code, then responds to the result of that
    			execution by deciding what state in the flow to enter next.  Specifically:
    			<orderedlist>
    				<listitem>
    					<para>
	    					The entered action state executes an ordered list of one or more
	    					<literal>org.springframework.webflow.execution.Action</literal>
    						instances.  This <literal>Action</literal> interface is the central abstraction that
    						encapsulates the execution of a logical unit of application code.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
	    					The state determines if the outcome of the first action's execution matches a
   		 					transition.  If there is a match, the transition is executed.  If there is no match,
    						the next action in the list is executed.  This process continues until a transition is
    						matched or the list of actions is exhausted.
    					</para>
    				</listitem>
    			</orderedlist>
    		</para>
    		<para>
    		    Spring Web Flow gives you full control over implementing your own actions and configuring when they should be invoked
    		    within the lifecycle of a flow.  The system can also <emphasis>automatically</emphasis> adapt methods on
    		    your existing application objects (POJOs) to the <literal>Action</literal> interface in a non-invasive manner.
    		    This means in many cases you can implement your flows without needing to develop custom glue code to bind SWF
    		    to your service layer operations.
    		</para>
    	    <para>
    	    	The properties of a <literal>org.springframework.webflow.engine.ActionState</literal> are summarized below:
    	    </para>
	    	<table>
    	        <title>ActionState properties</title>
        	    <tgroup cols="4">
            	    <colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
    	            <colspec colname="c2" colwidth="2*" />
	                <colspec colname="c2" colwidth="2*" />
	                <thead>
       		            <row>
               		        <entry>Property name</entry>
               				<entry>Description</entry>
	                        <entry>Cardinality</entry>
       		                <entry>Default value</entry>
           				</row>
		  			</thead>
				  	<tbody>
            			<row>
              				<entry>actions</entry>
							<entry>The ordered list of actions to execute when the state is entered.</entry>
						    <entry>
								<emphasis>1..*</emphasis>
							</entry>
							<entry></entry>
        	           </row>
            	   </tbody>
	          </tgroup>
    	    </table>
    		<sect3>
    			<title>Action execution points</title>
    			<para>
    			    As outlined, the <literal>ActionState</literal> is the dedicated state type for invoking one
    			    or more actions and responding to their result to drive a state transition.  There are
    			    also other points within the lifecycle of a flow where a chain of actions can be executed.
    			    At all of these points the only requirement is that these actions implement the central
    			    <literal>org.springframework.webflow.execution.Action</literal> interface.
	    		</para>
	    		<table>
    	   			<title>
    	   				Other points in a Flow where an Action can be executed and how those points
    	   				can be defined in a XML-based Flow definition.
    	   			</title>
        		    <tgroup cols="3">
		           	    <colspec colname="c1" colwidth="2*" />
        				<colspec colname="c2" colwidth="4*" />
        				<colspec colname="c3" colwidth="4*" />
	        	        <thead>
       		    	        <row>
               			        <entry>Point</entry>
               					<entry>Description</entry>
               					<entry>XML Configuration Element</entry>
               			    </row>
						</thead>
					  	<tbody>
            				<row>
              					<entry>on flow start</entry>
								<entry>
									Each time a new flow session starts.
								</entry>
								<entry>
								    A flow's <literal>&lt;start-actions/&gt;</literal>
								</entry>
	        	   	        </row>
            				<row>
              					<entry>on state entry</entry>
								<entry>
									Each time a state enters.
								</entry>
								<entry>
								    A state's <literal>&lt;entry-actions/&gt;</literal>
								</entry>
	        	   	        </row>
            				<row>
              					<entry>on transition</entry>
								<entry>
									Each time a state transition is matched but before it is executed.
								</entry>
								<entry>
								    A transition <literal>&lt;action/&gt;</literal>
								</entry>
	        	   	        </row>
            				<row>
              					<entry>on state exit</entry>
								<entry>
									Each time a transitionable state exits.
								</entry>
								<entry>
								    A transitionable state's <literal>&lt;exit-actions/&gt;</literal>
								</entry>
	        	   	        </row>
            				<row>
              					<entry>before view rendering</entry>
								<entry>
									Each time a renderable view selection is made.
								</entry>
								<entry>
								    A view state's <literal>&lt;render-actions/&gt;</literal>
								</entry>
	        	   	        </row>
            				<row>
              					<entry>on flow end</entry>
								<entry>
									Each time a flow session terminates.
								</entry>
								<entry>
								    A flow's <literal>&lt;end-actions/&gt;</literal>
								</entry>
	        	   	        </row>
	            		</tbody>
		       		</tgroup>
    		    </table>
    		    <para>
    		    	<note>
    		    	The above other points in a flow where actions may be executed do not
    		    	allow you to execute a state transition in response to the action result event.
    		    	If you need such flow control you must execute the action from within an action state.
					</note>
    		    </para>
    		</sect3>
    		<sect3>
    			<title>Action attributes</title>
    			<para>
    			    An <literal>Action</literal> may be annotated with attributes by wrapping the Action
    			    in a decorator, an instance of <literal>org.springframework.webflow.engine.AnnotatedAction</literal>.
    			    These attributes may provide descriptive characteristics, or may be used to affect
    			    the action's execution in a specific usage context.
	    		</para>
    			<para>
    			    Support for setting several common attributes is provided for convenience.  These
    			    include:
	    		</para>
	    		<table>
    	   			<title>Common Action attributes</title>
        		    <tgroup cols="2">
		           	    <colspec colname="c1" colwidth="2*" />
        				<colspec colname="c2" colwidth="4*" />
	        	        <thead>
       		    	        <row>
               			        <entry>Attribute name</entry>
               					<entry>Description</entry>
               			    </row>
						</thead>
					  	<tbody>
            				<row>
              					<entry>caption</entry>
								<entry>
									A short description about the action, suitable for display as a tooltip.
								</entry>
	        	   	        </row>
            				<row>
              					<entry>description</entry>
								<entry>
									A long description about the action, suitable for display in a text box.
								</entry>
	        	   	        </row>
            				<row>
              					<entry>name</entry>
								<entry>
									The name of the action, used to qualify the action's result event.
									For example, an Action named <literal>placeOrder</literal> that returns <literal>success</literal>
									would be assigned a result event identified by <literal>placeOrder.success</literal>.
									This allows you to distinguish logical execution outcomes by action, useful when
									invoking multiple actions as part of a chain.
								</entry>
	        	   	        </row>
            				<row>
              					<entry>method</entry>
								<entry>
									The name of the target method on the Action instance to invoke to carry out execution.
									This facilitates multiple <emphasis>action methods</emphasis> per Action instance,
									supported by the <literal>org.springframework.webflow.action.MultiAction</literal>.
								</entry>
	        	   	        </row>
	            		</tbody>
		       		</tgroup>
    		    </table>
			</sect3>
			<sect3>
				<title>ActionState class diagram</title>
	    		<para>
	    			The class diagram below shows the ActionState and the associated types used to carry
	    			out the action execution process:
	    		</para>
				<mediaobject>
					<imageobject role="fo">
						<imagedata fileref="images/actionstate-classdiagram.jpg" format="JPEG" align="center"/>
					</imageobject>
					<imageobject role="html">
						<imagedata fileref="images/actionstate-classdiagram.jpg" format="JPEG" align="center"/>
					</imageobject>
					<caption>
						<para>ActionState class diagram</para>
					</caption>
				</mediaobject>
			</sect3>
    	    <sect3 id="actionStateXml-simple">
    	    	<title>ActionState XML - simple action execution</title>
    	    	<para>
    	    	    The following example constructs an <literal>ActionState</literal> definition from
    	    	    XML that executes a single action when entered and then responds to its result:
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="executeSearch"/&gt;

        &lt;action-state id="executeSearch"&gt;
            &lt;action bean="searchAction"/&gt;
            &lt;transition on="success" to="displayResults"/&gt;
        &lt;/action-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			    This state definition reads "<emphasis>when the <literal>executeSearch</literal>
    			    state is entered, execute the <literal>searchAction</literal>.  On successful execution,
    			    transition to the <literal>displayResults</literal> state</emphasis>."
    			</para>
    			<para>
    			    The binding between the <literal>searchAction</literal> id and an
    			    <literal>Action</literal> implementation is made at Flow build time
    			    by querying a service locator, typically a Spring BeanFactory.  For example:
    	    	<programlisting>
    &lt;beans&gt;
        &lt;bean id="searchAction" class="example.webflow.SearchAction"/&gt;
    &lt;/beans&gt;
    			</programlisting>
    			    ... binds the <literal>searchAction</literal> action identifier to a singleton instance of the
    			    <literal>example.webflow.SearchAction</literal> class.
    			</para>
    			<para>
    			    A simple <literal>SearchAction</literal> implementation might look like this:
    			<programlisting>
    public class SearchAction implements Action {
        private SearchService searchService;

        public SearchAction(SearchService searchService) {
            this.searchService = searchService;
        }

        public Event execute(RequestContext context) {
            // lookup the search criteria in "flow scope"
            SearchCriteria criteria =
                (SearchCriteria)context.getFlowScope().get("criteria");

            // execute the search
            Collection results = searchService.executeSearch(criteria);

            // set the results in "request scope"
            context.getRequestScope().put("results", results);

            // return "success"
            return new Event(this, "success");
        }
    }
    			</programlisting>
    			</para>
			</sect3>
    	    <sect3 id="actionStateJava-simple">
    	    	<title>ActionState API - standard action</title>
    	    	<para>
    	    	    The following example constructs the equivalent action state definition using
    	    	    the FlowBuilder API:
    	    	</para>
    	    	<programlisting>
    public class SearchFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
            ...
            addActionState("executeSearch", action("searchAction"),
                transition(on("success"), to("displayResults")));
            ...
        }
    }
    			</programlisting>
			</sect3>
    	    <sect3 id="actionStateXml-multiActionMethod">
    	    	<title>ActionState XML - multi action</title>
    	    	<para>
    	    	    The next example constructs an <literal>ActionState</literal> definition from XML that
			executes a single <emphasis>action method</emphasis> on a <literal>org.springframework.webflow.action.MultiAction</literal>
			and then responds to its result:
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="executeSearch"/&gt;

        &lt;action-state id="executeSearch"&gt;
            &lt;action bean="searchAction" method="executeSearch"/&gt;
            &lt;transition on="success" to="displayResults"/&gt;
        &lt;/action-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			    This state definition reads "<emphasis>when the <literal>executeSearch</literal>
    			    state is entered, call the <literal>executeSearch</literal> method on the
    			    <literal>searchFlowAction</literal>.  On successful execution,
    			    transition to the <literal>displayResults</literal> state</emphasis>."
    			</para>
    			<para>
    			    A <literal>SearchAction</literal> implementation containing multiple action methods
    			    might look like this:
    			<programlisting>
    public class SearchAction extends MultiAction {
        private SearchService searchService;

        public SearchAction(SearchService searchService) {
            this.searchService = searchService;
        }

        public Event executeSearch(RequestContext context) {
            // lookup the search criteria in "flow scope"
            SearchCriteria criteria =
                (SearchCriteria)context.getFlowScope().get("criteria");

            // execute the search
            Collection results = searchService.executeSearch(criteria);

            // set the results in "request scope"
            context.getRequestScope().put("results", results);

            // return "success"
            return success();
        }

        public Event someOtherRelatedActionMethod(RequestContext context) {
            ...
            return success();
        }

        public Event yetAnotherRelatedActionMethod(RequestContext context) {
            ...
            return success();
        }
    }
    			</programlisting>
    				As you can see, this allows you to define one to many action methods per Action class.
    				With this approach, there are two requirements:
    				<orderedlist>
 						<listitem>
 							<para>
 								Your Action class must extend from <literal>org.springframework.webflow.MultiAction</literal>, or
 								another class that extends from <literal>MultiAction</literal>.  The multi action cares
    							for the action method dispatch that is based on the value of the <literal>method</literal>
    							property.
 							</para>
 						</listitem>
 						<listitem>
 							<para>
			    				Each action method must conform to the signature illustrated above: <literal>public Event ${method}(RequestContext) { ... }	</literal>
 							</para>
 						</listitem>
    				</orderedlist>
    			</para>
    			<para>
    			    MultiActions are useful for centralizing command logic on a per-flow definition basis, as
    			    a flow definition typically carries out execution of a single application use case.
    			</para>
			</sect3>
    	    <sect3 id="actionStateJava-multiActionMethod">
    	    	<title>ActionState API - multi action</title>
    	    	<para>
    	    	    The following example constructs the equivalent action state definition using
    	    	    the FlowBuilder API:
    	    	</para>
    	    	<programlisting>
    public class SearchFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
            ...
            addActionState("executeSearch", invoke("executeSearch", action("searchAction")),
                transition(on("success"), to("displayResults")));
            ...
        }
    }
    			</programlisting>
			</sect3>
    	    <sect3 id="actionStateXml-beanActionMethod">
    	    	<title>ActionState XML - bean action</title>
    	    	<para>
    	    	    The next example constructs an <literal>ActionState</literal> definition from XML that
					executes a single method on a Plain Old Java Object (POJO) and then responds to the result:
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;start-state idref="executeSearch"/&gt;

        &lt;action-state id="executeSearch"&gt;
            &lt;bean-action bean="searchService" method="executeSearch"&gt;
                &lt;method-arguments&gt;
                    &lt;argument expression="${flowScope.criteria}"/&gt;
                &lt;/method-arguments&gt;
                &lt;method-result name="results"/&gt;
            &lt;/bean-action&gt;
            &lt;transition on="success" to="displayResults"/&gt;
        &lt;/action-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			    This state definition reads "<emphasis>when the <literal>executeSearch</literal>
    			    state is entered, call the <literal>executeSearch</literal> method on the
    			    <literal>searchService</literal> passing it the object indexed by name <literal>criteria</literal>
    			    in <literal>flowScope</literal>.  On successful execution, expose the method
    			    return value in the default scope (request) under the name <literal>results</literal>
    			    and transition to the <literal>displayResults</literal> state</emphasis>."
    			</para>
    			<para>
    				In this example the referenced bean <literal>searchService</literal> would be
    				<emphasis>your application object</emphasis>, typically a transactional
    				business service.  Such a service implementation must have defined the
    				the <literal>Collection executeSearch(SearchCriteria)</literal> method,
    				typically by implementing a service interface:
    			</para>
    			<programlisting>
    public interface SearchService {
        public Collection executeSearch(SearchCriteria criteria);
    }
    			</programlisting>
    			<para>
    			    With this approach there are no requirements on the signature of the methods that carry out
    			    action execution, nor is there any requirement to extend from a Web Flow specific base class.
    			    Basically, you are not required to write a custom <literal>Action</literal> implementation at all--you
    			    simply instruct Spring Web Flow to call your business methods directly.  The need
    			    for custom "glue code" to bind your web-tier to your middle-tier is eliminated.
    			</para>
    			<para>
    			    Spring Web Flow achieves this by automatically adapting the method on your existing
    			    application object to the <literal>Action</literal> interface and caring for
    			    exposing any return value in the correct scope.
    			</para>
    			<para>
    			    This adaption process is shown graphically below:
    			</para>
				<mediaobject>
					<imageobject role="fo">
						<imagedata fileref="images/actionadapter-classdiagram.png" format="PNG" align="center"/>
					</imageobject>
					<imageobject role="html">
						<imagedata fileref="images/actionadapter-classdiagram.png" format="PNG" align="center"/>
					</imageobject>
					<caption>
						<para>Bean-&gt;Action adapter</para>
					</caption>
				</mediaobject>
			</sect3>
    	    <sect3 id="actionStateXml-action">
    	    	<title>ActionState XML - decision bean action</title>
    	    	<para>
    	    	    The following example constructs an <literal>ActionState</literal> from
    	    	    XML that executes an action whose execution result forms the basis for the transition decision:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        ...

        &lt;action-state id="shippingRequired"&gt;
            &lt;bean-action bean="shippingService" method="isShippingRequired"&gt;
                &lt;method-arguments&gt;
                    &lt;argument expression="${flowScope.purchase}"/&gt;
                &lt;/method-arguments&gt;
            &lt;/bean-action&gt;
            &lt;transition on="yes" to="enterShippingDetails"/&gt;
            &lt;transition on="no" to="placeOrder"/&gt;
        &lt;/action-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This state definition reads "<emphasis>if the <literal>isShippingRequired</literal> method on the
    			    <literal>shippingService</literal> returns true, transition to the <literal>enterShippingDetails</literal>
    			    state, otherwise transition to the <literal>placeOrder</literal> state</emphasis>."
    			</para>
    			<note>
    				<para>
	    			    Note how the boolean return value of the <literal>isShippingRequired</literal> method is
    				    converted to the event identifiers <literal>yes</literal> or <literal>no</literal>.
    				</para>
    			</note>
    			<para>
    			    This conversion process is handled by the action adapter responsible for adapting the method on your
    			    application object to the <literal>org.springframework.webflow.execution.Action</literal> interface.
    			    By default, this adapter applies a number of rules for creating a result event from a method return value.
    			</para>
    			<para>
	    			These conversion rules are:
    			</para>
		    	<table>
    		        <title>Default method return value to Event conversion rules</title>
	        	    <tgroup cols="2">
   		         	    <colspec colname="c1" colwidth="4*" />
   		     			<colspec colname="c2" colwidth="2*" />
	   		    	    <thead>
       		        	    <row>
               		    	    <entry>Return type</entry>
	               				<entry>Event identifier</entry>
	           				</row>
			  			</thead>
					  	<tbody>
			        	    <row>
               		    	    <entry>boolean</entry>
               		    	    <entry>yes or no</entry>
	           				</row>
			        	    <row>
               		    	    <entry>java.lang.Enum</entry>
               		    	    <entry>this.name()</entry>
	           				</row>
	           				<row>
	           				    <entry>org.springframework.core.enum.LabeledEnum</entry>
	           				    <entry>this.getLabel()</entry>
	           				</row>
	           				<row>
	           				    <entry>org.springframework.webflow.execution.Event</entry>
	           				    <entry>this.getId()</entry>
	           				</row>
	           				<row>
	           				    <entry>java.lang.String</entry>
	           				    <entry>the string</entry>
	           				</row>
	           				<row>
	           				    <entry>any other type</entry>
	           				    <entry>success</entry>
	           				</row>
	            	   </tbody>
					</tgroup>
    		    </table>
    			<para>
    				You may customize these default conversion policies by setting a custom <literal>ResultEventFactory</literal>
    				instance on the bean invoking action performing the adaption. Consult the JavaDoc documentation for
    				more details on how to do this.
    			</para>
			</sect3>
    	    <sect3 id="actionStateXml-actionenum">
    	    	<title>ActionState XML - decision bean action with enum return value</title>
    	    	<para>
    	    	    The following example constructs an <literal>ActionState</literal> from
    	    	    XML that executes a action that invokes a method on an application object that
    	    	    returns a <literal>java.lang.Enum</literal>:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        ...

        &lt;action-state id="shippingRequired"&gt;
            &lt;bean-action bean="shippingService" method="calculateShippingMethod"/&gt;
            	&lt;method-arguments&gt;
            	    &lt;argument expression="${flowScope.order}"/&gt;
            	&lt;/method-arguments&gt;
            &lt;/bean-action&gt;
            &lt;transition on="BASIC" to="enterBasicShippingDetails"/&gt;
            &lt;transition on="EXPRESS" to="enterExpressShippingDetails"/&gt;
            &lt;transition on="NONE" to="placeOrder"/>
        &lt;/action-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This state definition reads "<emphasis>if the <literal>calculateShippingMethod</literal> method on the
    			    <literal>shippingService</literal> returns <literal>BASIC</literal> for the current order, transition to the <literal>enterBasicShippingDetails</literal>
    			    state.  If the return value is <literal>EXPRESS</literal> transition to the <literal>enterExpressShippingDetails</literal> state.
    			    If the return value is <literal>NONE</literal> transition to the <literal>placeOrder</literal> state</emphasis>."
    			</para>
			</sect3>
    	    <sect3 id="actionStateXml-evaluateaction">
    	    	<title>ActionState XML - evaluate action</title>
    	    	<para>
    	    	    The following example constructs an <literal>ActionState</literal> from
    	    	    XML that executes a action that evaluates an expression against the
    	    	    flow request context and exposes the evaluation result:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;


        &lt;action-state id="getNextInterviewQuestion"&gt;
            &lt;evaluate-action expression="flowScope.interview.nextQuestion()"/&gt;
                &lt;evaluation-result name="question"/&gt;
            &lt;/evaluate-action&gt;
            &lt;transition on="success" to="displayQuestion"/&gt;
        &lt;/action-state&gt;

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This state definition reads "<emphasis>evaluate the <literal>flowScope.interview.nextQuestion()</literal> expression
    			    and expose the result under name <literal>question</literal> in the default scope.</emphasis>"
    			</para>
    			<para>
    				The expression can evaluate any object traversable from the flow's
    				<literal>org.springframework.webflow.execution.RequestContext</literal>.  This example expression evaluates the
    				<literal>nextQuestion</literal> method on the <literal>interview</literal>
    				business object in flow scope.
    			</para>
			</sect3>
    	    <sect3 id="actionStateXml-set">
    	    	<title>ActionState XML - set action</title>
    	    	<para>
    	    	    The next example constructs an <literal>ActionState</literal> from
    	    	    XML that executes an action on a success transition that sets an attribute in "flash scope":
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;view-state id="selectFile" view="fileUploadForm"&gt;
            &lt;transition on="submit" to="uploadFile"/&gt;
        &lt;/view-state&gt;

        &lt;action-state id="uploadFile"&gt;
            &lt;action bean="uploadAction" method="uploadFile"/&gt;
            &lt;transition on="success" to="selectFile"&gt;
                &lt;set attribute="fileUploaded" scope="flash" value="true"/&gt;
            &lt;/transition&gt;
        &lt;/action-state&gt;

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This flow definition reads "<emphasis>display the <literal>fileUploadForm</literal>.
    			    On form <literal>submit</literal> invoke the <literal>uploadFile</literal> method
    			    on the <literal>uploadAction</literal>. On <literal>success</literal> allow the user
    			    to select another file to upload.  Report that the last file was uploaded successfully by
    			    setting the <literal>fileUploaded</literal> attribute in <literal>flash</literal> scope to
    			    <literal>true</literal>.</emphasis>
    			</para>
    			<note>
    				<para>
    					Flash scoped attributes are preserved until the next user event is signaled into
    					the flow execution.  In this example this means the <literal>fileUploaded</literal>
    					attribute is preserved across a redirect to the <literal>selectFile</literal>
    					view state and any subsequent browser refreshes. Only when the <literal>submit</literal>
    					event is signaled will the flash scope be cleared.
    				</para>
    			</note>
			</sect3>
    		<sect3>
    			<title>When to use which kind of action?</title>
    			<para>
    				Simple action, Multi action, bean action, evaluate action, set?  When to use one or the other?
	    		</para>
	    		<table>
    	   			<title>
    	   				Action implementation usage guidelines
    	   			</title>
        		    <tgroup cols="2">
		           	    <colspec colname="c1" colwidth="2*" />
        				<colspec colname="c2" colwidth="4*" />
	        	        <thead>
       		    	        <row>
               			        <entry>Action type</entry>
               					<entry>Usage scenario</entry>
               			    </row>
						</thead>
					  	<tbody>
            				<row>
              					<entry>Simple (extends <literal>AbstractAction</literal>)</entry>
								<entry>
									You have a specialized behavior that stands on its own;
									for creating lightweight stubs or mocks for testing purposes.
								</entry>
	        	   	        </row>
            				<row>
              					<entry><literal>MultiAction</literal></entry>
								<entry>
									To group related command logic together.  Particularly
									useful for when there are multiple related behaviors
									called by a flow.
								</entry>
	        	   	        </row>
            				<row>
              					<entry>Bean action</entry>
								<entry>
									When the logical behavior maps well to a method call on a service
									layer bean.  When there is no "special" or exotic glue code
									required.
								</entry>
	        	   	        </row>
            				<row>
              					<entry>
              						<literal>EvaluateAction</literal>
              					</entry>
								<entry>
									When you need to invoke a bean in flow scope or evaluate
									any other flow expression.
								</entry>
	        	   	        </row>
            				<row>
              					<entry>
              						<literal>SetAction</literal>
              					</entry>
								<entry>
									When you need to set an attribute in flow or other scope
									during the course of flow execution.
								</entry>
	        	   	        </row>
	            		</tbody>
		       		</tgroup>
    		    </table>
    		</sect3>
    	</sect2>
    	<sect2 id="decisionState">
    		<title>DecisionState</title>
    		<para>
    			When entered, a decision state makes a flow routing decision.  This process consists of:
    			<orderedlist>
    				<listitem>
    					<para>
	    					Evaluating one or more boolean expressions against the executing flow to decide
	    					what state to transition to next.
    					</para>
    				</listitem>
    			</orderedlist>
    		</para>
    	    <para>
    	    	The properties of a <literal>org.springframework.webflow.engine.DecisionState</literal> are summarized below:
    	    </para>
	    	<table>
    	        <title>DecisionState properties</title>
        	    <tgroup cols="4">
            	    <colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
    	            <colspec colname="c2" colwidth="2*" />
	                <colspec colname="c2" colwidth="2*" />
	                <thead>
       		            <row>
               		        <entry>Property name</entry>
               				<entry>Description</entry>
	                        <entry>Cardinality</entry>
       		                <entry>Default value</entry>
           				</row>
		  			</thead>
				  	<tbody>
            			<row>
              				<entry>transitions (inherited from TransitionableState)</entry>
							<entry>
								The transitions that are evaluated on an event occurrence that
								forms the basis for the decision.
							</entry>
						    <entry>
								<emphasis>1..*</emphasis>
							</entry>
        	           </row>
            	   </tbody>
	          </tgroup>
    	    </table>
    	    <sect3 id="decisionStateXml-expression">
    	    	<title>DecisionState XML - expression evaluation</title>
    	    	<para>
    	    	    The following example constructs a <literal>DecisionState</literal> from
    	    	    XML that evalutes a boolean expression to determine what transition
    	    	    to execute:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;
        ...

        &lt;decision-state id="shippingRequired"&gt;
            &lt;if test="${flowScope.order.needsShipping}" then="enterShippingDetails" else="placeOrder"/&gt;
        &lt;/decision-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This state definition reads "<emphasis>if the <literal>needsShipping</literal> property on the
    			    <literal>order</literal> object in flow scope is true, transition to the <literal>enterShippingDetails</literal>
    			    state, otherwise transition to the <literal>placeOrder</literal> state</emphasis>."
    			</para>
    			<para>
    				<note>
    			    <emphasis>Caution</emphasis>: flow definitions should <emphasis>not</emphasis> be vehicles for
    			    business logic.  In this case the decision made was controller logic, reasoning on a
    			    pre-calculated value to decide what step of the flow to transition to next.  That is the kind of logic that
    			    should be in a flow definition.  In contrast, having the state <emphasis>itself</emphasis> embed
    			    the business rule defining how shipping status is calculated is a misuse.
    			    Instead, push such a calculation into application code where it belongs and <emphasis>instruct</emphasis>
    			    the flow to invoke that code using an action.
    			    </note>
    			</para>
			</sect3>
    	</sect2>
    	<sect2 id="subflowState">
    		<title>SubflowState</title>
    		<para>
    			When entered, a subflow state spawns another flow as a subflow.
    		</para>
    		<para>
    			Recall that a flow is a reusable, self-contained controller module.  The ability for one flow to <emphasis>call</emphasis> another flow
    			gives you the ability to compose independent modules together to create complex controller workflows.  Any flow can be used as subflow
    			by any other flow, and there is a well-defined contract in play. Specifically:
    		</para>
    		<para>
    			<orderedlist>
    				<listitem>
    					<para>
    						A Flow is an instance of <literal>org.springframework.webflow.engine.Flow</literal>.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
    						A newly launched flow can be passed input attributes which it may choose
    						to map into its own local scope.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
    						An ending flow can return output attributes.  If the ended flow was launched as a subflow,
    						the resuming parent flow may choose to map these output attributes into its own scope.
    					</para>
    				</listitem>
    			</orderedlist>
    		</para>
    		<para>
    		   It is helpful to think of the process of calling a flow like calling a Java method.  Flows can
    		   be passed input arguments and can produce return values just like methods can.  Flows are more powerful because
    		   they are potentially long-running, as they can span more than one request into the server.
    		</para>
    	    <para>
    	    	The properties of a <literal>org.springframework.webflow.engine.SubflowState</literal> are summarized below:
    	    </para>
	    	<table>
    	        <title>SubflowState properties</title>
        	    <tgroup cols="4">
            	    <colspec colname="c1" colwidth="2*" />
        			<colspec colname="c2" colwidth="4*" />
    	            <colspec colname="c2" colwidth="2*" />
	                <colspec colname="c2" colwidth="2*" />
	                <thead>
       		            <row>
               		        <entry>Property name</entry>
               				<entry>Description</entry>
	                        <entry>Cardinality</entry>
       		                <entry>Default value</entry>
           				</row>
		  			</thead>
				  	<tbody>
            			<row>
              				<entry>subflow</entry>
							<entry>
								The definition of the flow to be spawned as a subflow.
							</entry>
						    <entry>
								<emphasis>1</emphasis>
							</entry>
							<entry></entry>
        	            </row>
            			<row>
              				<entry>attributeMapper</entry>
							<entry>
								The strategy responsible for mapping input attributes to the subflow and
								mapping output attributes from the subflow.
							</entry>
						    <entry>
								<emphasis>0..*</emphasis>
							</entry>
							<entry>Null</entry>
        	           </row>
            	   </tbody>
	          </tgroup>
    	    </table>
    		<para>
    			When a SubflowState is entered, the following behavior occurs:
    			<orderedlist>
    				<listitem>
    					<para>
    						The state first messages its <literal>attributeMapper</literal>, an instance of
    						<literal>org.springframework.webflow.engine.FlowAttributeMapper</literal>,
    						to prepare a <literal>Map</literal> of input attributes to pass to the subflow.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
    						The subflow is spawned, passing the input attributes.  When this happens,
    						the parent flow <emphasis>suspends</emphasis> itself in the subflow state until
    						the subflow ends.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
    						When the subflow ends, a <emphasis>result event</emphasis> is returned describing the flow outcome
    						that occurred.  The parent flow <emphasis>resumes</emphasis> back in the subflow state.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
    						The resumed subflow state messages its <literal>attributeMapper</literal> to
    						map any output attributes returned by the subflow into flow scope, if necessary.
    					</para>
    				</listitem>
    				<listitem>
    					<para>
    						Finally, the resumed subflow state responds to the result event returned by the ended subflow
    						by matching and executing a state transition.
    					</para>
    				</listitem>
    			</orderedlist>
    		</para>
    		<para>
    		   The constructs used in spawning a flow as a subflow are shown graphically below:
    		</para>
			<mediaobject>
				<imageobject role="fo">
					<imagedata fileref="images/subflowstate-classdiagram.png" format="PNG" align="center"/>
				</imageobject>
				<imageobject role="html">
					<imagedata fileref="images/subflowstate-classdiagram.png" format="PNG" align="center"/>
				</imageobject>
				<caption>
					<para>SubflowState class diagram</para>
				</caption>
			</mediaobject>
    	    <sect3 id="subflowStateXml">
    	    	<title>SubflowState XML - with input attribute</title>
    	    	<para>
    	    	    The following example constructs an <literal>SubflowState</literal> from
    	    	    XML that spawns a shipping subflow:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        ...

        &lt;subflow-state id="enterShippingDetails" flow="shipping"&gt;
            &lt;attribute-mapper&gt;
                &lt;input-mapper&gt;
                    &lt;mapping source="flowScope.order.shipping" target="shipping"/&gt;
                &lt;/input-mapper&gt;
            &lt;/attribute-mapper&gt;
            &lt;transition on="finish" to="placeOrder"/>
        &lt;/subflow-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This subflow state definition reads "<emphasis>spawn the <literal>shipping</literal> flow
    			    and pass it the value of the <literal>shipping</literal> property on the <literal>order</literal>
    			    object in flow scope as an input attribute with the name <literal>shipping</literal>.
    			    When the <literal>shipping</literal> flow ends, respond to the <literal>finish</literal>
    			    result event by transitioning to the <literal>placeOrder</literal> state</emphasis>."
    			</para>
	   			<note>
	   				<para>
		   				The inner structure and behavior of the <literal>shipping</literal> flow is fully encapsulated within
		   				its own flow definition.  A flow calling another flow as a subflow can pass that flow input
		   				and capture its output, but it cannot see inside it.  Flows are <emphasis>black boxes</emphasis>.
		   				Because any flow can be used as a subflow, it can be reused in other contexts without change.
		   			</para>
	   			</note>
			</sect3>
    	    <sect3 id="subflowStateJava">
    	    	<title>SubflowState API - input attributes</title>
    	    	<para>
    	    	    The following illustrates the equivalent example using the <literal>FlowBuilder</literal> API:
    	    	</para>
    	    	<programlisting>
    public class OrderFlowBuilder extends AbstractFlowBuilder {
        public void buildStates() {
    	    ...
            addSubflowState("enterShippingDetails", flow("shipping"), shippingMapper(),
                transition(on("finish"), to("placeOrder")));
            ...
        }

        protected FlowAttributeMapper shippingMapper() {
            DefaultFlowAttributeMapper mapper = new DefaultFlowAttributeMapper();
            mapper.addInputMapping(mapping().source("flowScope.order.shipping").target("shipping").value());
            return mapper;
        }
    }
    			</programlisting>
    		</sect3>
    	    <sect3 id="flowInputMapping">
    	    	<title>Flow input mapping - input contract</title>
   				<para>
   					Internally within the definition of the <literal>shipping</literal> flow referenced above, the flow
   					may choose to map the <literal>shipping</literal> input attribute into its own scope using
   					its input mapper when it starts.  Any input attributes must be explictly mapped, defining the input
   					contract for the flow:
	   			</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        &lt;input-mapper&gt;
            &lt;input-attribute name="shipping"/&gt;
        &lt;/input-mapper&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This short-form input mapper declaration reads "<emphasis>when a new execution of this flow starts
    			    map the <literal>shipping</literal> input attribute into <literal>flowScope</literal> under
    			    the name <literal>shipping</literal></emphasis>."
    			</para>
    			<note>
    				<para>
	    				Had this input mapping not been defined the shipping attribute made available as input
    					to this flow by a calling parent flow or external client would have been ignored.
    				</para>
    			</note>
			</sect3>
    	</sect2>
    	<sect2 id="endState">
    		<title>EndState</title>
    		<para>
    			When entered, an end state terminates a flow.  A EndState represents exactly one logical
    			flow outcome; for example, "finish", or "cancel".
    		</para>
    		<para>
    			If the ended flow was acting as a top-level or <emphasis>root flow</emphasis> the
    			entire flow execution ends and cannot be resumed.  In this case the end state is responsible
    			for making a <literal>ViewSelection</literal> that is the basis for the ending response (for example,
    			a confirmation page, or a redirect request to another flow or an external URL).
    		</para>
    		<para>
    			If the ended flow was acting as a subflow, the spawned subflow session ends and
    			the calling parent flow <emphasis>resumes</emphasis> by responding to the end
    			result returned.  In this case the responsibility for any <literal>ViewSelection</literal>
    			falls on the parent flow.
    		</para>
    		<para>
    			Once a flow ends any attributes in flow scope go out of scope immediately
    			and become eligible for garbage collection.
    		</para>
    		<para>
    			As outlined, an end state entered as part of a root flow messages its <literal>ViewSelector</literal>
    			to make a ending view selection.  Typically this is a redirect-based <literal>ViewSelector</literal>,
    			allowing for <emphasis>redirect after flow completion</emphasis>.  An end state entered as part of
    			a subflow is not responsible for a view selection; this responsibility falls on the calling flow.
    		</para>
    		<sect3 id="endState-resultevents">
    			<title>EndState result events</title>
	    		<para>
    				When a EndState is entered it terminates a flow and, if used as subflow,
    				returns a result event the parent flow uses to drive a state transition from the calling subflow
    				state.  It is the end state's responsibility to create this result event which
    				is the basis for communicating the <emphasis>logical flow outcome</emphasis> to
    				callers.
    			</para>
				<para>
    				By default, an EndState creates a result event with an identifier that matches the
    				identifier of the end-state itself.  For example, an end state with id <literal>finish</literal>
    				returns a result event with id <literal>finish</literal>.  Also, any attributes in
    				flow scope that have been explicitly mapped as <emphasis>output attributes</emphasis>
    				are returned as result event parameters.  This allows you to return data along
    				with the logical flow outcome.
 				</para>
				<para>
					Spring Web Flow gives you full control over the ending view selection strategy, as
					well as what flow attributes should be exposed as output on a per EndState basis.
					These configurable properties are summarized below:
				</para>
			</sect3>
			<sect3 id="endState-properties">
				<title>EndState Properties</title>
		    	<table>
	    	        <title>EndState properties</title>
	        	    <tgroup cols="4">
	            	    <colspec colname="c1" colwidth="2*" />
	        			<colspec colname="c2" colwidth="4*" />
	    	            <colspec colname="c2" colwidth="2*" />
		                <colspec colname="c2" colwidth="2*" />
		                <thead>
	       		            <row>
	               		        <entry>Property name</entry>
	               				<entry>Description</entry>
		                        <entry>Cardinality</entry>
	       		                <entry>Default value</entry>
	           				</row>
			  			</thead>
					  	<tbody>
	            			<row>
	            				<entry>viewSelector</entry>
								<entry>The strategy that makes the ending view selection when this state is entered and the flow is a root flow.</entry>
							    <entry>
									<emphasis>0..1</emphasis>
						       </entry>
						       <entry>Null</entry>
						    </row>
	            			<row>
	              				<entry>outputMapper</entry>
								<entry>
									The service responsible for exposing flow output attributes, making those attributes eligible for output mapping by a calling flow.
								</entry>
							    <entry>
									<emphasis>0..1</emphasis>
								</entry>
								<entry>None</entry>
	        	           </row>
	            	   </tbody>
		          </tgroup>
	    	    </table>
			</sect3>
    	    <sect3 id="endStateXml-flowDefinitionRedirect">
    	    	<title>EndState XML - redirect to flow after completion</title>
    	    	<para>
    	    	    The following example constructs an <literal>EndState</literal> from
    	    	    XML that terminates a shipping subflow and requests a
    	    	    redirect response to another flow:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        ...

        &lt;end-state id="finish" view="flowRedirect:searchFlow"/&gt;

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This end state definition reads "<emphasis>terminate the <literal>order</literal> flow
    			    and redirect to a new execution of the <literal>searchFlow</literal></emphasis>".
    			</para>
			</sect3>
    	    <sect3 id="endStateXml-externalRedirect">
    	    	<title>EndState XML - redirect after flow completion</title>
    	    	<para>
    	    	    The following example constructs an <literal>EndState</literal> from
    	    	    XML that terminates a shipping subflow and requests a
    	    	    redirect response to an external URL:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        ...

        &lt;end-state id="finish" view="externalRedirect:/orders/${flowScope.order.id}"/&gt;

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This end state definition reads "<emphasis>terminate the <literal>order</literal> flow
    			    and redirect to the URL returned by evaluating the <literal>/orders/${flowScope.order.id}</literal>
    			    expression</emphasis>."
    			</para>
    			<para>
    				This is an example of the familiar <emphasis>redirect after post</emphasis> pattern where
    				after transaction completion a redirect is issued allowing the result of the transaction
    				to be viewed (in this case using REST-style URLs).
    			</para>
			</sect3>
    	    <sect3 id="endStateXml-outputattribute">
    	    	<title>EndState XML - flow output attribute</title>
    	    	<para>
    	    	    The following example constructs an <literal>EndState</literal> from
    	    	    XML that terminates a shipping subflow:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        ...

        &lt;end-state id="finish"&gt;
            &lt;output-mapper&gt;
                &lt;output-attribute name="shipping"/&gt;
            &lt;/output-mapper&gt;
        &lt;/end-state&gt;

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This end state definition reads "<emphasis>terminate the <literal>shipping</literal> flow
    			    and expose the <literal>shipping</literal> property in flow scope as an output attribute
    			    with name <literal>shipping</literal></emphasis>."
    			</para>
    		</sect3>
    	    <sect3 id="endStateJava-outputattribute">
    	    	<title>EndState API - flow output attribute</title>
    	    	<para>
    	    	    The following illustrates the equivalent example using the <literal>FlowBuilder</literal> API:
    	    	</para>
    	    	<programlisting>
    public class ShippingFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
    	    ...
            addEndState("finish",
                new DefaultAttributeMapper().add(
                   mapping().source("flowScope.shipping").target("shipping").value()
                );
        }
    }
    			</programlisting>
	   			<para>
	   			    Since this end-state does not make a view selection it is expected this flow will be always used
	   			    as a subflow.  When this flow ends, the calling parent flow is expected to respond to the
	   			    <literal>finish</literal> result, and may choose to map the <literal>shipping</literal> output
	   			    attribute into its own scope.
	   			</para>
    		</sect3>
    	    <sect3 id="subflowStateXml-output">
    	    	<title>SubflowState XML - mapping an output attribute</title>
    	    	<para>
    	    		The next example shows how a <literal>subflow-state</literal> can respond to the ending
    	    		result of a subflow and map output attributes into its own scope:
    	    	</para>
    	    	<programlisting>
    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;flow xmlns="http://www.springframework.org/schema/webflow"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="
              http://www.springframework.org/schema/webflow
              http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"&gt;

        ...

        &lt;subflow-state id="enterShippingDetails" flow="shipping"&gt;
            &lt;attribute-mapper&gt;
                &lt;output-mapper&gt;
                    &lt;output-attribute name="shipping"/&gt;
                &lt;/output-mapper&gt;
            &lt;/attribute-mapper&gt;
            &lt;transition on="finish" to="placeOrder"/>
        &lt;/subflow-state&gt;

        ...

    &lt;/flow&gt;
    			</programlisting>
    			<para>
    			    This subflow state definition reads "<emphasis>spawn the <literal>shipping</literal> flow
    			    as a subflow.  When the <literal>shipping</literal> flow ends map the <literal>shipping</literal> output
    			    attribute into flow scope under the name <literal>shipping</literal>, then respond to
    			    the <literal>finish</literal> result event by transitioning to
    			    the <literal>placeOrder</literal> state</emphasis>."
    			</para>
    			<note>
    				<para>
	    				Had this output mapping not been defined the shipping attribute made available as output
    					to this flow by the ending subflow would have been ignored.
    				</para>
    			</note>
			</sect3>
    	</sect2>
    </sect1>
</chapter>