The following example shows transitions defined at the state level, as well as global transitions defined at the flow level.

    <?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">

        <start-state idref="state1"/>

        <xxx-state id="state1">
            <transition on="localEvent1" to="state2"/>
        </xxx-state>

        <xxx-state id="state2">
            <transition on="localEvent1" to="state1"/>
        </xxx-state>

        <global-transitions>
            <transition on="globalEvent1" to="state1"/>
            <transition on="globalEvent2" to="state2"/>
        </global-transitions>

    </flow>
    			

In this mock example, state1 defines one transition and also inherits the two others defined within the global-transitions element. Any other states defined within this flow would also inherit those global transitions.

This example is shown graphically below:

Global transitions

The following example illustrates a state-level transition executing exception handler:

    <?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">

        <start-state idref="state1"/>

        <xxx-state id="state1">
            <transition on="event1" to="state2"/>
            <transition on-exception="example.MyBusinessException" to="state3"/>
        </xxx-state>

        ...

    </flow>
    			

In this example, state1 defines one transition and an exception handler which executes a transition to state3 if a MyBusinessException is thrown within the state. The handled exception will be put into flash scope under the key stateException, where it will be automatically exposed to the next view (typically an error view).

The following example illustrates a flow-level transition executing exception handler:

    <?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">

        <start-state idref="state1"/>

        <xxx-state id="state1">
            <transition on="event1" to="state2"/>
        </xxx-state>

        <xxx-state id="state2"/>

        <global-transitions>
            <transition on-exception="example.MyBusinessException" to="state3"/>
        </global-transitions>

        ...
        
    </flow>
    			

In this example, the exception handler is defined as a global transition. This reads "any time a MyBusinessException occurs during flow execution, transition the flow to state3".

Exception handlers attached at the state level take precedence over those defined at the flow level. This is illustrated by the following example:

    <?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">

        <start-state idref="state1"/>

        <xxx-state id="state1">
            <transition on="event1" to="state2"/>
            <transition on-exception="example.MyBusinessException" to="state4"/>
        </xxx-state>

        <xxx-state id="state2"/>

        <global-transitions>
            <transition on-exception="example.MyBusinessException" to="state3"/>
        </global-transitions>

        ...
        
    </flow>
    			

In this example, if MyBusinessException is thrown in state1 the flow will transition to state4. For any other state, the flow will transition to state3.

    <bean id="myCustomStateExceptionHandler" class="example.CustomFlowExecutionExceptionHandler"/>
    <bean id="myCustomFlowExceptionHandler" class="example.AnotherCustomFlowExecutionExceptionHandler"/>
  				

The creational strategy responsible for making a ViewSelection when an ViewState is entered is org.springframework.webflow.engine.ViewSelector. This provides a plugin-point for customizing how a response instruction is constructed.

Four ViewSelector implementations are provided with Spring Web Flow:

The class diagram below shows the ViewState and the associated types used to carry out the view selection process:

ViewState class diagram

The following example shows a view-state definition in XML that makes an application view selection when entered, selecting the searchForm view for display and, on resume, responding to two possible user input events (submit and cancel) in different ways:

    <?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">

        <start-state idref="displaySearchForm"/>

        <view-state id="displaySearchForm" view="searchForm">
            <transition on="submit" to="processFormSubmission"/>
            <transition on="cancel" to="processCancellation"/>
        </view-state>

        ...

    </flow>
    			

View name expressions may also be specified for the view attribute to achieve runtime view name calculation. For example, view="${requestScope.calculatedViewName}".

The following example shows the equivalent view state definition using the FlowBuilder API:

    public class SearchFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
    	    addViewState("displaySearchForm", "searchForm",
    	        new Transition[] {
    	            transition(on("submit"), to("processFormSubmission")),
    	            transition(on("cancel"), to("processFormCancellation"))
    	        }
    	    );
            ...
        }
    }
    			

The following example illustrates a view-state definition in XML that makes an flow execution redirect selection when entered, redirecting to the yourList view for display.

    <?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">

        <start-state idref="displayList"/>

        <view-state id="displayList" view="redirect:yourList">
            <transition on="add" to="addListItem"/>
        </view-state>

        ...

    </flow>
    			

This example is called a flow execution redirect because the application view selected is rendered only after a redirect to the flow execution. The redirect request is sent to a URL that refreshes the flow execution paused in the displayList view state. Refresh then triggers the rendering of the yourList application view on the next request into the server.

The following example shows the equivalent view state definition using the FlowBuilder API:

    public class SearchFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
    	    addViewState("displayList", viewSelector("redirect:yourView"),
   	            transition(on("add"), to("addListItem"))
    	    );
            ...
        }
    }
    			

The following example illustrates a view-state definition in XML that makes a null view selection when entered. This causes no additional response to be issued.

    <?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">

        <start-state idref="displayPdf"/>

        <view-state id="displayPdf">
            <render-actions>
                <action bean="pdfWriter" method="write"/>
            </render-actions>
        </view-state>

        ...

    </flow>
    			

The FlowDefinitionRedirect and ExternalRedirect are not generally used by a view state. They are typically used by an end state, either to start a new independent flow or redirect to an arbitrary external URL. Examples are provided in the discussion of the end state.

The following example illustrates a view-state definition in XML that encapsulates typical "form state" behavior.

Consider the requirements of typical input forms. Most forms require pre-render or setup logic to execute before the form is displayed. For example, such logic might load the backing form object from the database, install formatters for formatting form field values, and pull in supporting form data needed to populate drop-down menus.

In addition, most forms require post-back or submission logic to execute when the form is submitted. This logic typically involves binding form input to the backing form object and performing type conversion and data validation.

This "form state" behavior of form setup, display, and post-back is handled elegantly in Spring Web Flow by the capabilities of the view-state construct. See below:

    <?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">

        <start-state idref="displayForm"/>

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

        ...

    </flow>
    			

This reads "when this flow starts enter the displayForm state to execute the setupForm and loadFormReferenceData methods before rendering the form view. On submit, transition to the saveForm state if the bindAndValidate method executes successfully."

As outlined, the ActionState 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 org.springframework.webflow.execution.Action interface.

	Note
	The other points above 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.

An Action may be annotated with attributes by wrapping the Action in a decorator, an instance of org.springframework.webflow.engine.AnnotatedAction. These attributes may provide descriptive characteristics, or may be used to affect the action's execution in a specific usage context.

Support for setting several common attributes is provided for convenience. These include:

The class diagram below shows the ActionState and the associated types used to carry out the action execution process:

ActionState class diagram

The following example constructs an ActionState definition from XML that executes a single action when entered and then responds to its result:

    <?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">

        <start-state idref="executeSearch"/>

        <action-state id="executeSearch">
            <action bean="searchAction"/>
            <transition on="success" to="displayResults"/>
        </action-state>

        ...

    </flow>
    			

This state definition reads "when the executeSearch state is entered, execute the searchAction. On successful execution, transition to the displayResults state."

The binding between the searchAction id and an Action implementation is made at Flow build time by querying a service locator, typically a Spring BeanFactory. For example:

    <beans>
        <bean id="searchAction" class="example.webflow.SearchAction"/>
    </beans>
    			

... binds the searchAction action identifier to a singleton instance of the example.webflow.SearchAction class.

A simple SearchAction implementation might look like this:

    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");
        }
    }
    			

The following example constructs the equivalent action state definition using the FlowBuilder API:

    public class SearchFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
            ...
            addActionState("executeSearch", action("searchAction"),
                transition(on("success"), to("displayResults")));
            ...
        }
    }
    			

The next example constructs an ActionState definition from XML that executes a single action method on a org.springframework.webflow.action.MultiAction and then responds to its result:

    <?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">

        <start-state idref="executeSearch"/>

        <action-state id="executeSearch">
            <action bean="searchAction" method="executeSearch"/>
            <transition on="success" to="displayResults"/>
        </action-state>

        ...

    </flow>
    			

This state definition reads "when the executeSearch state is entered, call the executeSearch method on the searchFlowAction. On successful execution, transition to the displayResults state."

A SearchAction implementation containing multiple action methods might look like this:

    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();
        }
    }
    			

As you can see, this allows you to define one to many action methods per Action class. With this approach, there are two requirements:

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.

The following example constructs the equivalent action state definition using the FlowBuilder API:

    public class SearchFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
            ...
            addActionState("executeSearch", invoke("executeSearch", action("searchAction")),
                transition(on("success"), to("displayResults")));
            ...
        }
    }
    			

The next example constructs an ActionState definition from XML that executes a single method on a Plain Old Java Object (POJO) and then responds to the result:

    <?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">

        <start-state idref="executeSearch"/>

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

        ...

    </flow>
    			

This state definition reads "when the executeSearch state is entered, call the executeSearch method on the searchService passing it the object indexed by name criteria in flowScope. On successful execution, expose the method return value in the default scope (request) under the name results and transition to the displayResults state."

In this example the referenced bean searchService would be your application object, typically a transactional business service. Such a service implementation must have defined the the Collection executeSearch(SearchCriteria) method, typically by implementing a service interface:

    public interface SearchService {
        public Collection executeSearch(SearchCriteria criteria);
    }
    			

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 Action 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.

Spring Web Flow achieves this by automatically adapting the method on your existing application object to the Action interface and caring for exposing any return value in the correct scope.

This adaption process is shown graphically below:

Bean->Action adapter

The following example constructs an ActionState from XML that executes an action whose execution result forms the basis for the transition decision:

    <?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">

        ...

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

        ...

    </flow>
    			

This state definition reads "if the isShippingRequired method on the shippingService returns true, transition to the enterShippingDetails state, otherwise transition to the placeOrder state."

	Note
	Note how the boolean return value of the isShippingRequired method is converted to the event identifiers yes or no.

This conversion process is handled by the action adapter responsible for adapting the method on your application object to the org.springframework.webflow.execution.Action interface. By default, this adapter applies a number of rules for creating a result event from a method return value.

These conversion rules are:

You may customize these default conversion policies by setting a custom ResultEventFactory instance on the bean invoking action performing the adaption. Consult the JavaDoc documentation for more details on how to do this.

The following example constructs an ActionState from XML that executes a action that invokes a method on an application object that returns a java.lang.Enum:

    <?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">

        ...

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

        ...

    </flow>
    			

This state definition reads "if the calculateShippingMethod method on the shippingService returns BASIC for the current order, transition to the enterBasicShippingDetails state. If the return value is EXPRESS, transition to the enterExpressShippingDetails state. If the return value is NONE, transition to the placeOrder state."

The following example constructs an ActionState from XML that executes a action that evaluates an expression against the flow request context and exposes the evaluation result:

    <?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">


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

    </flow>
    			

This state definition reads "evaluate the flowScope.interview.nextQuestion() expression, and expose the result under name question in the default scope."

The expression can evaluate any object traversable from the flow's org.springframework.webflow.execution.RequestContext. This example expression evaluates the nextQuestion method on the interview business object in flow scope.

The next example constructs an ActionState from XML that executes an action on a success transition that sets an attribute in "flash scope":

    <?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">

        <view-state id="selectFile" view="fileUploadForm">
            <transition on="submit" to="uploadFile"/>
        </view-state>

        <action-state id="uploadFile">
            <action bean="uploadAction" method="uploadFile"/>
            <transition on="success" to="selectFile">
                <set attribute="fileUploaded" scope="flash" value="true"/>
            </transition>
        </action-state>

    </flow>
    			

This flow definition reads "display the fileUploadForm. On form submit, invoke the uploadFile method on the uploadAction. On success, allow the user to select another file to upload. Report that the last file was uploaded successfully by setting the fileUploaded attribute in flash scope to true.

	Note
	Flash scoped attributes are preserved until the next user event is signaled into the flow execution. In this example, this means the fileUploaded attribute is preserved across a redirect to the selectFile view state and any subsequent browser refreshes. Only when the submit event is signaled will the flash scope be cleared.

Simple action, Multi action, bean action, evaluate action, set? When to use one or the other?

The following example constructs a DecisionState from XML that evalutes a boolean expression to determine what transition to execute:

    <?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">
        ...

        <decision-state id="shippingRequired">
            <if test="${flowScope.order.needsShipping}" then="enterShippingDetails" else="placeOrder"/>
        </decision-state>

        ...

    </flow>
    			

This state definition reads "if the needsShipping property on the order object in flow scope is true, transition to the enterShippingDetails state, otherwise transition to the placeOrder state."

Note

Caution: flow definitions should not 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 itself embed the business rule defining how shipping status is calculated is a misuse. Instead, push such a calculation into business application code where it belongs and instruct the flow to invoke that code using an action.

The following example constructs an SubflowState from XML that spawns a shipping subflow:

    <?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">

        ...

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

        ...

    </flow>
    			

This subflow state definition reads "spawn the shipping flow, passing it the value of the shipping property on the order object in flow scope. When the shipping flow ends, respond to the finish result event by transitioning to the placeOrder state."

	Note
	The inner structure and behavior of the shipping 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 black boxes. Because any flow can be used as a subflow, it can be reused in other contexts without change.

The following illustrates the equivalent example using the FlowBuilder API:

    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;
        }
    }
    			

Within a flow definition, input attributes can be obtained by configuring an input-mapper. Any input attributes must be explictly mapped. The list of permitted input attributes defines the input contract for the flow.

	Tip
	If you think of calling a Flow as analogous to calling a Java method, it is helpful to think of input-attributes as analogous to method arguments.

    <?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">

        <input-mapper>
            <input-attribute name="shipping"/>
        </input-mapper>

        ...

    </flow>
    			

This short-form input mapper declaration reads "when a new execution of this flow starts, map the provided shipping input attribute into flowScope under the name shipping."

	Note
	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.

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 logical flow outcome to callers.

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 finish returns a result event with id finish. Also, any attributes in flow scope that have been explicitly mapped as output attributes are returned as result event attributes. This allows you to return data along with the logical flow outcome.

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:

The following example constructs an EndState from XML that terminates a shipping subflow and requests a redirect response to another flow:

    <?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">

        ...

        <end-state id="finish" view="flowRedirect:searchFlow"/>

    </flow>
    			

This end state definition reads "terminate the order flow, and redirect to a new execution of the searchFlow".

The following example constructs an EndState from XML that terminates a shipping subflow and requests a redirect response to an external URL:

    <?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">

        ...

        <end-state id="finish" view="externalRedirect:/orders/${flowScope.order.id}"/>

    </flow>
    			

This end state definition reads "terminate the order flow, and redirect to the URL returned by evaluating the /orders/${flowScope.order.id} expression."

This is an example of the familiar redirect after post pattern where after transaction completion a redirect is issued allowing the result of the transaction to be viewed (in this case using a REST-style URL).

The following example constructs an EndState from XML that terminates a shipping subflow:

    <?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">

        ...

        <end-state id="finish">
            <output-mapper>
                <output-attribute name="shipping"/>
            </output-mapper>
        </end-state>

    </flow>
    			

This end state definition reads "terminate the shipping flow, and expose the shipping property in flow scope as an output attribute with name shipping."

The following illustrates the equivalent example using the FlowBuilder API:

    public class ShippingFlowBuilder extends AbstractFlowBuilder {
    	public void buildStates() {
    	    ...
            addEndState("finish",
                new DefaultAttributeMapper().add(
                   mapping().source("flowScope.shipping").target("shipping").value()
                );
        }
    }
    			

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 finish result, and may choose to map the shipping output attribute into its own scope.

The next example shows how a subflow-state can respond to the ending result of a subflow, and map subflow output attributes into its own scope:

    <?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">

        ...

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

        ...

    </flow>
    			

This subflow state definition reads "spawn the shipping flow as a subflow. When the shipping flow ends, map the shipping output attribute into flow scope under the name shipping, then respond to the finish result event by transitioning to the placeOrder state."

	Note
	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.