This Schema defines the Spring Web Flow (SWF) XML syntax.
The root "flow" element of this document defines exactly one flow definition. A flow definition is a blueprint for an executable task that involves a single user (aka conversation or dialog).
A flow is composed of one or more states that form the steps of the flow. Each state executes behavior when entered. What behavior is executed is a function of the state's type. Core state types include view states, action states, subflow states, decision states, and end states.
Each flow definition must specify exactly one start state. Events that occur in transitionable states drive state transitions. ]]> The action referenced by this element must implement the org.springframework.webflow.execution.Action interface. The action may be a MultiAction and if so the 'method' attribute can be used to specify the target method to invoke.
An action may be annotated with attributes that can be used to affect the action's execution. ]]> The bean to invoke is typically an arbitrary "POJO" (Plain Old Java Object) with no dependency on Spring Web Flow.
Use this element when the logic to invoke is encapsulated within an object you define. This element can be used to invoke *any* public method on any bean.
If the target method accepts arguments they may be specified in order by using the 'method-arguments' sub-element.
If the target method returns a value that value may be exposed to the flow using the 'method-result' sub-element.
For example: 
	<bean-action bean="orderClerk" method="placeOrder">
		<method-arguments>
			<argument expression="flowScope.order"/>
		</method-arguments>
		<method-result name="orderConfirmation"/>
	</bean-action>
The above example instructs this flow to invoke the "placeOrder" method on the "orderClerk" bean, passing the value of "flowScope.order" as the method argument. After method invocation the method return value is exposed in the default scope under the name "orderConfirmation". ]]> Use this element when the logic to invoke is encapsulated within an object inside the flow request context. This element can be used to invoke *any* public method on a flow-managed bean.
For example: 
	<evaluate-action expression="flowScope.interview.nextQuestion()">
	    <evaluation-result name="question"/>
	</evaluate-action>
The above example instructs this flow to invoke the "nextQuestion" method on the "interview" bean in flow scope. After method invocation the method return value is exposed in the default scope under the name "question". ]]> For example: 
	<set attribute="fileUploaded" scope="flash" value="true"/>
The above example instructs this flow to set the "fileUploaded" attribute in "flash scope" to "true". This action always returns a "success" event unless an exception is thrown. ]]> A flow may also exhibit the following characteristics:
  • Be annotated with attributes that define descriptive properties that may affect flow execution. (See the <attribute/> element)
  • Instantiate a set of application variables when started. (See the <var/> element)
  • Map input provided by callers that start it (See the <input-mapper/> element)
  • Return output to callers that end it. (See the <output-mapper/> element)
  • Execute custom behaviors at start time and end time. (See the <start-actions/> and <end-actions/> elements)
  • Define transitions shared by all states. (See the <global-transitions/> element)
  • Handle exceptions thrown by its states during execution. (See the <exception-handler/> element)
  • Import one or more local bean definition files defining custom flow artifacts (such as actions, exception handlers, view selectors, transition criteria, etc). (See the <import/> element)
  • Finally, a flow may nest one or more other flows within this document to use as subflows, referred to as 'inline flows'. (See the <inline-flow/> element)
]]>
  • The 'source' of each mapping is a Map containing all the input provided by the caller that launched this flow.
  • The 'target' of each mapping is this flow execution's RequestContext, exposing access to data structures such as 'flowScope'.
    For example: 
        <input-mapper>
        <input-attribute name="id"/>
    </input-mapper>
    ... maps the value of "id" input attribute to the "id" attribute in this flow's scope. ]]> Once paused a view-state may be 'refreshed' by the user, for example, when the browser refresh button is clicked. A refresh causes the response to be reissued, at which point control goes back to the user.
    A view state may be configured with one or more <render-action/> elements. Render actions are executed before the view is rendered. Such actions are often idempotent and execute without side effects.
    A view state is a transitionable state. A view state transition is triggered by a user input event. ]]>     A decision state is a transitionable state. A decision state transition can be triggered by evaluating a boolean expression against the flow execution request context. To define expressions, use the 'if' element.
    Examples:
    A simple boolean expression test, using the convenient 'if' element: 
        <decision-state id="requiresShipping">
	    <if test="flowScope.sale.shipping" then="enterShippingDetails" else="processSale"/>
    </decision-state>
    ]]>     A subflow state is a transitionable state. A state transition is triggered by a subflow result event, which describes the logical subflow outcome that occurred. Typically the criteria for this transition is the id of the subflow end state that was entered.
    While the subflow is active, this flow is suspended waiting for the subflow to complete execution. When the subflow completes execution by reaching an end state, this state is expected to respond to the result of that execution. The result of subflow execution, the end state that was reached, should be used as grounds for a transition out of this state. ]]>     A end state is not transitionable--there are never transitions out of an end state. When an end-state is entered, an instance of this flow is terminated.
    When this flow terminates, if it was acting as the "root" or top-level flow the entire execution (conversation) is terminated. If this flow was acting as a subflow the subflow session ends and the calling parent session resumes. To resume, the parent session responds to the result of the subflow, typically by reasoning on the id of the end state that was reached. ]]>     For the output mapper the following mapping characteristics apply:
    • The 'source' of each mapping is this flow execution's RequestContext, exposing access to internal data structures such as 'flowScope'.
    • The 'target' of each mapping is the flow output map that will contain the output returned to the caller that launched this flow.

    For example: 
        <output-mapper>
        <mapping source="flowScope.myFlowAttribute" target="clientOutputAttribute"/>
    </output-mapper>
    ... maps the value of "myFlowAttribute" in flow scope to "clientOutputAttribute" in this flow's output map. ]]>     When specified without the 'class' or 'bean' attributes, this name is also used as the bean name of a non-singleton bean in the configured Bean Factory to use as the initial variable value. ]]>
  • request - The variable goes out of scope when a call to start this flow completes.
  • flash - The variable goes out of scope when the next user event is signaled.
  • flow - The variable goes out of scope when this flow session ends.
  • conversation - The variable goes out of scope when the overall conversation governing this flow ends.
    If not specified the default scope type is used ('flow' by default). ]]> A transition defines a supported path through the flow. Transitions may be annotated with attributes and may execute one or more actions before executing. ]]> If the referenced bean implements the org.springframework.webflow.execution.Action interface it is retrieved from the factory and used as is. If the bean is not an Action an exception is thrown.
    This is similar to the <ref bean="myBean"/> notation of the Spring beans DTD. ]]>     This can be used to execute actions in an ordered chain, where the flow responds to the the last action result in the chain: 
        <action-state id="setupForm">
        <action name="setupForm" bean="formAction" method="setupForm"/>
        <action name="loadReferenceData" bean="formAction" method="loadReferenceData"/>
        <transition on="loadReferenceData.success" to="displayForm">
    </action-state>
    ... will execute 'setupForm' followed by 'loadRefenceData', then transition the flow to the 'displayForm' state on a successful 'loadReferenceData' invocation.
    An action with a name is often referred to as a "named action". ]]>     Use this attribute when the action is a "multi action" extending org.springframework.webflow.action.MultiAction. The value should be name of the method to invoke on the multi-action instance. The method's implementation must have the following signature: 
        public Event <methodName>(RequestContext context);
    As an example: 
    	<action bean="formAction" method="setupForm"/>
    ... might invoke: 
    	public class FormAction extends MultiAction {
		public Event setupForm(RequestContext context) {
			return success();
		}
	}
    ]]>     It is expected the referenced bean be a simple POJO that does not implement the Spring Web Flow Action interface. The method to invoke, specified using the 'method' attribute, will be adapted to the Action interface automatically.
    This is similar to the <ref bean="myBean"/> notation of the Spring beans DTD. ]]>     This can be used to execute actions in an ordered chain, where the flow responds to the the last action result in the chain: 
        <action-state id="setupForm">
        <action name="setupForm" bean="formAction" method="setupForm"/>
        <action name="loadReferenceData" bean="formAction" method="loadReferenceData"/>
        <transition on="loadReferenceData.success" to="displayForm">
    </action-state>
    ... will execute 'setupForm' followed by 'loadRefenceData', then transition the flow to the 'displayForm' state on a successful 'loadReferenceData' invocation.
    An action with a name is often referred to as a "named action". ]]>     If the method has parameters the arguments to those parameters should be specified using the 'method-arguments' element.
    If the method returns a value that should be exposed to this flow, the 'method-result' element should be specified. ]]>     Typically used to pass a value from a flow scope type into this bean method as an argument.
    Examples: 
    	<argument expression="flowScope.order"/>
    ... passes in the value of the 'order' attribute in flow scope. 
    	<argument expression="'a constant'"/>
    ... passes in the 'a constant' literal. ]]>
  • request - The result goes out of scope when the call into this flow that invoked this method completes.
  • flash - The result goes out of scope when the next user event is signaled.
  • flow - The result goes out of scope when this local flow session ends.
  • conversation - The result goes out of scope when the overall conversation governing this flow execution ends.
    If not specified the default scope type is used ('request' by default). ]]> This can be used to execute actions in an ordered chain, where the flow responds to the the last action result in the chain: 
        <action-state id="setupForm">
        <evaluate-action name="firstInterviewQuestion" bean="flowScope.interview.firstQuestion()"/>
        <action name="setupForm" bean="formAction" method="setupForm"/>
        <transition on="setupForm.success" to="displayForm">
    </action-state>
    ... will execute 'firstInterviewQuestion' followed by 'setupForm', then transition the flow to the 'displayForm' state on a successful 'setupForm' invocation.
    An action with a name is often referred to as a "named action". ]]>
  • request - The result goes out of scope when the call into this flow that evaluated this expression completes.
  • flash - The result goes out of scope when the next user event is signaled.
  • flow - The result goes out of scope when this local flow session ends.
  • conversation - The result goes out of scope when the overall conversation governing this flow execution ends.
    If not specified the default scope type is used ('request' by default). ]]>
  • request - The attribute goes out of scope when the call into this flow that sets the attribute completes.
  • flash - The attribute goes out of scope when the next user event is signaled.
  • flow - The attribute goes out of scope when this local flow session ends.
  • conversation - The attribute goes out of scope when the overall conversation governing this flow execution ends.
    If not specified the default scope type is used ('request' by default). ]]> This can be used to execute actions in an ordered chain, where the flow responds to the the last action result in the chain: 
        <action-state id="processSubmit">
        <action name="processSubmit" bean="formAction" method="processSubmit"/>
        <set name="setFormSubmitted" attribute="formSubmitted" value="true"/>
        <transition on="setFormSubmitted.success" to="thankYou">
    </action-state>
    ... will execute 'processSubmit' followed by 'setFormSubmitted', then transition the flow to the 'thankYou' state on a successful 'setFormSubmitted' invocation.
    An action with a name is often referred to as a "named action". ]]>     The most basic value is a static event id: 
    	<transition on="submit" to="state"/>
    ... which reads "on an occurrence of the 'submit' event transition to 'state'"
    Sophisticated transitional expressions are also supported when enclosed within ${brackets}: 
    	<transition on="${#result == 'submit' &;amp;& flowScope.attribute == 'foo'}" to="state"/>
    Custom transition criteria implementations can be referenced by id: 
    	<transition on="bean:myCustomCriteria" to="state"/>
    The exact interpretation of this attribute value depends on the TextToTransitionCriteria converter that is installed. ]]>     The value must be a fully-qualified Exception class name (e.g. example.booking.ItineraryExpiredException). When an exception is thrown, superclasses of the configured exception class match by default.
    Use of this attribute results in an exception handler being attached to the object associated with this transition definition. Use this attribute or the 'on' attribute, not both. ]]>     The value of this attribute may be a static state identifier (e.g. to="displayForm") or an expression to be evaluated at runtime against the request context (e.g. to="${flowScope.previousViewState}"). Custom target state resolvers implementations can be referenced by id (e.g. to="bean:myCustomTargetStateResolver"). The exact interpretation of this attribute value depends on the installed TextToTargetStateResolver. ]]>     A transition defines a supported path through the flow. Transitions may be annotated with attributes and may execute one or more actions before executing. ]]> This value may be a logical application view name which gets resolved to a template: 
    	priceForm
    It may even be a direct pointer to a view template: 
    	/WEB-INF/jsp/priceForm.jsp
    This value may also be a view name expression evaluated against the request context: 
    	${flowScope.view}
    Use of the "redirect:" prefix indicates this view state should trigger a redirect to a unique "flow execution URL". This causes the application view to render on the redirected request to that URL. This allows browsers to refresh a specific state of the conversation while it remains active: 
    	redirect:priceForm
    Use of the "externalRedirect:" prefix indicates this view state should trigger a redirect to an absolute external URL, typically to interface with an external system. External redirect query parameters may be specified using ${expressions} that evaluate against the request context: 
    	externalRedirect:/someOtherSystem.htm?orderId=${flowScope.order.id}
    Use of the "flowRedirect:" prefix has this view state generate a redirect to a URL that launches a new flow execution of an identified flow: 
    	flowRedirect:editOrderFlow?orderId=${flowScope.order.id}
    Use of the "bean:" prefix references a custom ViewSelector implementation you define, exposed by id in either a flow-local context using the "import" element or in the parent context. 
    	bean:myCustomViewSelector
    The exact semantics regarding the interpretation of this value are determined by the installed TextToViewSelector converter.
    Note when no view name is provided, this view state will make a "null" view selection. A null view does not request the rendering of a view, it only pauses the flow and returns control the client. Use a null view when another state is expected to generate the response. ]]>     The form is: 
    	<if test="${criteria}" then="trueStateId" else="falseStateId"/>
    ]]>     For example: 
    	<if test="${flowScope.sale.shipping} then="enterShippingDetails"/>
	<if test="${lastEvent.id == 'search'} then="bindSearchParameters"/>
    ]]>     The value of this attribute may be a static state identifier (e.g. then="displayForm") or an expression to be evaluated at runtime against the request context (e.g. then="${flowScope.previousViewState}"). Custom target state resolvers implementations can be referenced by id (e.g. to="bean:myCustomTargetStateResolver"). The exact interpretation of this attribute value depends on the installed TextToTargetStateResolver. ]]>     For the input mapper the following mapping characteristics apply:
    • The 'source' of each mapping is the RequestContext, exposing access to internal data structures of this flow such as flowScope.
    • The 'target' of each input mapping is the subflow's input Map.

    For the output mapper the following mapping characteristics apply:
    • The 'source' of each output mapping is the subflow's output Map.
    • The 'target' of each output mapping is the RequestContext, exposing access to internal data structures of this flow such as flowScope.

    For example: 
        <attribute-mapper>
	    <input-mapper>
		    <input-attribute name="myFlowAttribute"/>
    	</input-mapper>
    	<output-mapper>
    		<output-attribute name="aSubflowOutputAttribute"/>
    	</output-mapper>
    </attribute-mapper>
    ]]>     A transition defines a supported path through the flow. Transitions may be annotated with attributes and may specify one or more actions to execute before executing. ]]>
  • The 'source' of each mapping is the RequestContext, exposing access to internal data structures of this flow such as flowScope.
  • The 'target' of each input mapping is the subflow's input map.
    For example: 
        <input-mapper>
	    <mapping source="flowScope.myFlowAttribute" target="subflowInputAttribute"/>
    </input-mapper>
    ... maps the value of "flowScope.myFlowAttribute" to the "subflowInputAttribute" in the subflow input map. ]]>
  • The 'source' of each output mapping is the subflow's output map.
  • The 'target' of each output mapping is the RequestContext, exposing access to internal data structures of this flow such as flowScope.
    For example: 
        <output-mapper>
	    <mapping source="aSubflowOutputAttribute" target="flowScope.myFlowAttribute"/>
    </output-mapper>
    ... maps the value of "aSubflowOutputAttribute" in the subflow output map to "myFlowAttribute" in flow scope. ]]> Use this as an alternative to the child input-mapper and output-mapper elements when you need full control of attribute mapping behavior for this subflow state. ]]> For the output mapper the following mapping characteristics apply:
    • The 'source' of each mapping is this flow execution's RequestContext, exposing access to internal data structures such as 'flowScope'.
    • The 'target' of each mapping is the flow output map that will contain the output returned to the caller that launched this flow.

    For example: 
        <output-mapper>
        <mapping source="flowScope.myFlowAttribute" target="clientOutputAttribute"/>
    </output-mapper>
    ... maps the value of "myFlowAttribute" in flow scope to "clientOutputAttribute" in this flow's output map. ]]>     This value may be a logical application view name which gets resolved to a template: 
    	priceForm
    It may even be a direct pointer to a view template: 
    	/WEB-INF/jsp/priceForm.jsp
    This value may also be a view name expression evaluated against the request context: 
    	${flowScope.view}
    Use of the "externalRedirect:" prefix triggers a redirect to a specific "after conversation completion" external URL: 
        externalRedirect:/home.html
    Redirect query parameters may also be specified using ${expressions} that evaluate against the request context: 
        externalRedirect:/thankyou.htm?confirmationNumber=${flowScope.order.confirmation.id}
    Use of the "flowRedirect:" prefix indicates this end state should trigger a redirect that starts another flow. Flow input parameters may be specified using ${expressions} that evaluate against the request context: 
    	flowRedirect:search-flow?firstName=${flowScope.searchCriteria.firstName}
    Use of the "bean:" prefix references a custom ViewSelector implementation you define, exposed by id in either a flow-local context using the "import" element or in the parent context. 
        bean:myCustomViewSelector
    The exact semantics regarding the interpretation of this value are determined by the installed TextToViewSelector converter.
    Note when no view name is provided, this view state will make a "null" view selection. A null view does not request the rendering of a view, it only pauses the flow and returns control the client. Use a null view when another state is expected to generate the response. ]]>     A transition defines a supported path through the flow. Transitions may be annotated with attributes and may execute one or more actions before executing. ]]> For example: 
        <import resource="orderitem-flow-beans.xml"/>
    ... would look for 'orderitem-flow-beans.xml' in the same directory as this document. ]]>