The default executor implementation is org.springframework.webflow.executor.FlowExecutorImpl. It allows for configuration of a FlowDefinitionLocator responsible for loading the flow definitions to execute, as well as the FlowExecutionRepository strategy responsible for persisting flow executions that remain active beyond a single request into the server.

The configurable FlowExecutorImpl properties are shown below:

    <?xml version="1.0" encoding="UTF-8"?>	    	
    <beans xmlns="http://www.springframework.org/schema/beans"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:flow="http://www.springframework.org/schema/webflow-config"
           xsi:schemaLocation="
               http://www.springframework.org/schema/beans
               http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
               http://www.springframework.org/schema/webflow-config
               http://www.springframework.org/schema/webflow-config/spring-webflow-config-1.0.xsd">
           	    	
        <!-- Launches new flow executions and resumes existing executions. -->
        <flow:executor id="flowExecutor" registry-ref="flowRegistry"/>

        <!-- Creates the registry of flow definitions for this application -->
        <flow:registry id="flowRegistry">
            <flow:location path="/WEB-INF/flows/**/*-flow.xml"/>
        </flow:registry>
        
    </beans>
	        

This instructs Spring to create a flow executor that can execute all XML-based flow definitions contained within the /WEB-INF/flows directory. The default flow execution repository, continuation, is used.

    <flow:executor id="flowExecutor" registry-ref="flowRegistry" repository-type="simple"/>
	    	

This executor is configured with a simple repository that manages execution state in the user session.

    <flow:executor id="flowExecutor" registry-ref="flowRegistry" repository-type="client"/>
	    	

This executor is configured with a continuation-based repository that serializes continuation state to the client using no server-side state.

    <flow:executor id="flowExecutor" registry-ref="flowRegistry" repository-type="singleKey"/>>
	    	

This executor is configured with a simple repository that assigns a single flow execution key per conversation. The key, once assigned, never changes for the duration of the conversation.

    <flow:executor id="flowExecutor" registry-ref="flowRegistry">
        <flow:repository type="continuation" max-conversations="5" max-continuations="30" conversation-manager-ref="conversationManager"/>
    </flow:executor>

    <bean id="conversationManager" class="example.MyCustomConversationalStateManager"/>
	    	

This executor is configured with a continuation repository configured with custom settings for:

The flow:repository child element is the more flexible form for configuring the flow execution repository. Use it or the convenient repository-type attribute, not both.

    <flow:executor id="flowExecutor" registry-ref="flowRegistry" repository-type="continuation">
        <flow:execution-attributes>
            <flow:alwaysRedirectOnPause value="false"/>
            <flow:attribute name="foo" value="bar"/>
        </flow:execution-attributes>
    </flow-executor>
			

This executor is configured to set two flow execution system attributes alwaysRedirectOnPause=false and foo=bar.

	Note
	The alwaysRedirectOnPause attribute determines if a flow execution redirect occurs automatically each time an execution pauses (automated POST+REDIRECT+GET behavior). Setting this attribute to false will disable the default 'true' behavior.

    <flow:executor id="flowExecutor" registry-ref="flowRegistry" repository-type="continuation">
        <flow:execution-listeners>
            <flow:listener ref="listener" criteria="order-flow"/>
        </flow:execution-listeners>
    </flow-executor>

    <!-- A FlowExecutionListener to observe the lifecycle of order-flow executions -->
    <bean id="listener" class="example.OrderFlowExecutionListener"/>
			

This executor is configured to apply the execution listener to the "order-flow".

    <?xml version="1.0" encoding="UTF-8"?>	    	
    <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" 
	    "http://www.springframework.org/dtd/spring-beans.dtd">
    <beans>
    
        <!-- Launches new flow executions and resumes existing executions: Spring 1.2 config version -->
        <bean id="flowExecutor" class="org.springframework.webflow.config.FlowExecutorFactoryBean">
            <property name="definitionLocator" ref="flowRegistry"/>
            <property name="executionAttributes">
                <map>
                    <entry key="alwaysRedirectOnPause">
                        <value type="java.lang.Boolean">false</value>
                    </entry>
                </map>
            </property>
            <property name="repositoryType" value="CONTINUATION"/>
        </bean>
        
        <!-- Creates the registry of flow definitions for this application: Spring 1.2 config version -->
        <bean id="flowRegistry"
           class="org.springframework.webflow.engine.builder.xml.XmlFlowRegistryFactoryBean">
            <property name="flowLocations">
                <list>
                    <value>/WEB-INF/flows/**/*-flow.xml</value>
                </list>
            </property>
        </bean>
	
    </beans>
	        

This achieves similar semantics as the Spring 2.0 version above. The 2.0 version is more concise, provides stronger validation, and encapsulates internal details such as FactoryBean class names. The 1.2 version is Spring 1.2 or > compatible and digestable by Spring IDE 1.3.

    <bean name="/flowController.htm" class="org.springframework.webflow.executor.mvc.FlowController">
        <property name="flowExecutor" ref="flowExecutor"/>
    </bean>
	    	

This controller, exported at the context-relative /flowController.htm URL, delegates to the configured flow executor for driving flow executions in a Spring Servlet MVC environment.

    <bean id="portletModeControllerMapping"
             class="org.springframework.web.portlet.handler.PortletModeHandlerMapping">
        <property name="portletModeMap">
            <map>
                <entry key="view" value-ref="flowController"/>
            </map>
        </property>
    </bean>

    <bean id="flowController" class="org.springframework.webflow.executor.mvc.PortletFlowController">
        <property name="flowExecutor" ref="flowExecutor"/>
        <property name="defaultFlowId" ref="search-flow"/>
    </bean>
	    	

This controller, exported for access with the configured portlet mode, delegates to the configured flow executor for driving flow executions in a Spring Portlet MVC environment (by default, an execution of the search-flow will be launched).

The default executor argument extractor strategy is request-parameter based. The default request parameters are:

	<a href="flowController.htm?_flowId=myflow">Launch My Flow</a>
		    	

    <form action="flowController.htm" method="post">
        <input type="submit" value="Launch My Flow"/>
        <input type="hidden" name="_flowId" value="myflow">
    </form>
	    		

    <a href="flowController.htm?_flowExecutionKey=${flowExecutionKey}&_eventId=submit">
        Submit
    </a>
	    		

    <form action="flowController.htm" method="post">
        ...
        <input type="hidden" name="_flowExecutionKey" value="${flowExecutionKey}">
        <input type="hidden" name="_eventId" value="submit"/>
        <input type="submit" class="button" value="Submit">
    </form>
		    	

5.4.1.5. Resuming a flow execution - multiple form buttons

    <form action="flowController.htm" method="post">
        ...
        <input type="hidden" name="_flowExecutionKey" value="${flowExecutionKey}">
        <input type="submit" class="button" name="_eventId_submit" value="Submit">
        <input type="submit" class="button" name="_eventId_cancel" value="Cancel">
    </form>
		    	

	Note
	In this case, the eventId is determined by parsing the name of the button that was pressed.

    <a href="flowController.htm?_flowExecutionKey=${flowExecutionKey}">Refresh</a>
	    		

The request-path based argument extractor strategy relies on executor arguments being path elements as much as possible. This results in friendlier REST-style URLs such as http://host/app/myflow, instead of http://host/app?_flowId=myflow.

    <bean name="/flowController.htm" class="org.springframework.webflow.executor.mvc.FlowController">
        <property name="flowExecutor" ref="flowExecutor"/>
        <property name="argumentHandler">
            <bean class="org.springframework.webflow.executor.support.RequestPathFlowExecutorArgumentHandler"/>
        </property>        
    </bean>
		    	

	<a href="flowController/myflow"/>Launch My Flow</a>
		    	

    <form action="${flowExecutionKey}" method="post">
        ...
        <input type="submit" class="button" name="_eventId_submit" value="Submit">
        <input type="submit" class="button" name="_eventId_cancel" value="Cancel">
    </form>
		    	

    <a href="flowController/k/${flowExecutionKey}">Refresh</a>
	    		

    <form-beans>
        <form-bean name="actionForm" type="org.springframework.web.struts.SpringBindingActionForm"/>
    </form-beans>
	    	
    <action-mappings>
        <action path="/flowAction" name="actionForm" scope="request"
                type="org.springframework.webflow.executor.struts.FlowAction"/>
    </action-mappings>
	    	

Using Spring Web Flow in a JSF environment requires adding these custom artifacts to the application's faces-config.xml file:

<faces-config>
    <application>
        <navigation-handler>org.springframework.webflow.executor.jsf.FlowNavigationHandler</navigation-handler>
        <variable-resolver>org.springframework.webflow.executor.jsf.DelegatingFlowVariableResolver</variable-resolver>
    </application>

    <lifecycle>
        <phase-listener>org.springframework.webflow.executor.jsf.FlowPhaseListener</phase-listener>
    </lifecycle>
</faces-config>
	    	

The FlowPhaseListener is required to manage the overall flow execution lifecycle in a JSF environment. It handles launching new flows accessed by browsers via direct URLs, and also handles restoring flow executions on postback and browser refreshes.

The FlowNavigationHandler is required to continue a flow on an action outcome from a JSF view participating in the flow. Outcome strings are treated as events signaled against the current view state of the flow execution automatically.

The DelegatingFlowVariableResolver resolves JSF a value binding expression like {#someBean.someProperty} to a flow execution attribute. This resolver searches flash, flow, and conversation scope in that order until it finds a match. If no match is found, this resolver delegates to the next resolver in the chain.

The artifacts defined in the faces-config.xml use Spring to access the Web Flow system configuration. This requires a Spring Web Application Context to be bootstrapped using a ContextLoaderListener in the web.xml deployment descriptor:

<context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>
        /WEB-INF/webflow-config.xml
    </param-value>
</context-param>

<listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>				
			

This context should contain the Web Flow system configuration. The example webflow-config.xml below shows a typical Web Flow configuration for a JSF environment:

<?xml version="1.0" encoding="UTF-8"?>	    	
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:flow="http://www.springframework.org/schema/webflow-config"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
           http://www.springframework.org/schema/webflow-config
           http://www.springframework.org/schema/webflow-config/spring-webflow-config-1.0.xsd">
           	    	
    <!-- Launches new flow executions and resumes existing executions. -->
    <flow:executor id="flowExecutor" registry-ref="flowRegistry"/>

    <!-- Creates the registry of flow definitions for this application -->
    <flow:registry id="flowRegistry">
        <flow:location path="/WEB-INF/flows/**/*-flow.xml"/>
    </flow:registry>
        
</beans>
	        

A bean named flowExecutor must be configured and linked with a flow definition registry that contains the flows eligible for execution. Note the flowExecutor bean name is significant, as that is bean name the Web Flow JSF extensions will expect.

Any flow executor property such as the flow execution repository type is configurable here, consistent with the other environments Spring Web Flow supports.

Flows can be launched by firing JSF action outcomes that adhere to a special format:

<h:commandLink value="Go" action="flowId:myflow"/>
	    	

The command link above says launch 'myflow' when clicked. 'myflow' is expected to be a valid id of a flow definition registered in the configured registry.

	Tip
	By default, an action outcome prefixed with flowId: will be treated as a flow definition identifier. The flow id prefix respected by the FlowNavigationHandler is configurable. See the API documentation for more information.

Flows can also be launched simply by accessing flow definition URLs directly using a bookmark or normal HTML link:

<a href="app.faces?_flowId=myflow">Go</a>
	    	

This example link assumes *.faces has been mapped to the FacesServlet defined within web.xml. The format of a flow definition URL is configurable on the FlowPhaseListener.

Flow definitions in a JSF environment are just plain Spring Web Flow definitions:

<?xml version="1.0" encoding="UTF-8"?>
<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">

    <var name="myBean" class="example.ManagedBeanImpl" scope="conversation" />
	
    <start-state idref="displayView" />

    <view-state id="displayView" view="/myview.jsp">
        <transition on="submit" to="displayNextView"/>
    </view-state>

    <view-state id="displayNextView" view="/mynextview.jsp" />

</flow>				
			

A primary benefit of using JSF is it a rich UI component framework, and UI components have both data and behavior. As JSF components typically handle data binding and validation behaviors, the actual flow definition logic is often simpler and more focused as a result.

In general, it is recommended views selected by view states follow the standard JSF view identifier format, which requires a leading forward-slash and ends in a prefix. How Spring Web Flow view names are mapped to JSF view ids is configurable. See the FlowPhaseListener API documentation for more information.

Views participating in flows are just plain JSF views. They may also incorporate other JSF view technologies such as Facelets and Ajax4JSF.

<f:view>		
    <h:form id="form">
        ...
        <h:inputText id="propertyName" value="#{someBean.someProperty}"/>
        ...
        <h:commandButton type="submit" value="Next" action="submit"/>
    </h:form>
</f:view>		
	    	

As shown above, there is nothing Spring Web Flow specific here. The flow execution key is automatically tracked by a special UI component in the view root, so there is no need to track it manually. Action outcomes are automatically mapped to Spring Web Flow event identifiers signaled against the current state.

See the sellitem-jsf sample that illustrates Spring Web Flow operating in a JSF environment.

	Note
	The following three sections apply only to those using Spring Web Flow's JSF integration before release 1.0.2.

Before release 1.0.2, Spring Web Flow only supported resolving variables in flow scope (and not the other scopes such as flash and conversation shown above). This configuration is still supported for backwards compatibility reasons:

<faces-config>
    <application>
        <navigation-handler>org.springframework.webflow.executor.jsf.FlowNavigationHandler</navigation-handler>
        <variable-resolver>org.springframework.webflow.executor.jsf.FlowVariableResolver</variable-resolver>
        <property-resolver>org.springframework.webflow.executor.jsf.FlowPropertyResolver</property-resolver>
    </application>

    <lifecycle>
        <phase-listener>org.springframework.webflow.executor.jsf.FlowPhaseListener</phase-listener>
    </lifecycle>
</faces-config>
	    	

	Note
	With 1.0.2 DelegatingFlowVariableResolver is now the recommended default resolver, as it allows full access to all flow execution scopes transparently from the point of view of the JSF view developer.

Before release 1.0.2, Spring Web Flow did not support the configuration of a flowExecutor in a JSF environment. Those who needed to customize Web Flow services such as the flow execution repository or registry deployed those beans individually with special bean names. This configuration is still supported for backwards compatability reasons. However, it is recommended that existing users of Spring Web Flow's JSF integration use the standard <flow:executor/> tag in the webflow-config namespace for consistency and simplicity.

Before release 1.0.2, the flow execution key had to be tracked manually in JSF views participating in a flow execution. This configuration is still supported for backwards compatibility reasons. However, it is highly recommended that existing users of Spring Web Flow's JSF integration update their views to be just plain JSF.

<f:view>
    <h:form id="form">
        ...
        <h:inputText id="propertyName" value="#{flowScope.aFlowScopeAttribute}"/>
        ...
        <input type="hidden" name="_flowExecutionKey" value="${flowExecutionKey}">
        <h:commandButton type="submit" value="Next" action="submit"/>
    </h:form>
</f:view>
	    	

The hidden form field above can now be safely removed. In addition, the new variable resolver can be plugged in to gain access to other scopes such as flash and conversation.