From 56d12e56cbe001de1ec7ceb7485b7befa0068aa8 Mon Sep 17 00:00:00 2001 From: Erwin Vervaet Date: Sat, 6 Jan 2007 08:56:58 +0000 Subject: [PATCH] Fix for SWF-234. --- .../docs/reference/src/flow-definition.xml | 496 +++++++++--------- 1 file changed, 248 insertions(+), 248 deletions(-) diff --git a/spring-webflow/docs/reference/src/flow-definition.xml b/spring-webflow/docs/reference/src/flow-definition.xml index 736fb3a0..647b4757 100644 --- a/spring-webflow/docs/reference/src/flow-definition.xml +++ b/spring-webflow/docs/reference/src/flow-definition.xml @@ -9,7 +9,7 @@ the execution of application code to complete a business goal. - Flows are defined declaratively using a rich domain-specific language (DSL) + 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. @@ -27,12 +27,12 @@ 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 + 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. - Exactly one of a flow's states is the startState + Exactly one of a flow's states is the startState 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. @@ -77,7 +77,7 @@ 1 - + attributes Additional custom attributes about the flow. @@ -198,25 +198,25 @@ </start-actions> <start-state idref="yourStartingStateId"/> - + <-- your state definitions go here --> + <global-transitions> + ... + </global-transitions> + <end-actions> ... </end-actions> <output-mapper .../> - - <global-transitions> - ... - </global-transitions> <exception-handler .../> <inline-flow> ... </inline-flow> - + </flow> @@ -237,8 +237,8 @@ flow.addInlineFlow(...); - A Flow is typically built by a FlowBuilder rather than assembled - by hand. The flow building subsystem is contained within the + A Flow is typically built by a FlowBuilder rather than assembled + by hand. The flow building subsystem is contained within the org.springframework.webflow.engine.builder package. The XML Flow Builder and spring-webflow.xsd schema are located within the org.springframework.webflow.engine.builder.xml package. @@ -353,7 +353,7 @@ - Below is a mock flow definition snippet showing how properties may be configured for + Below is a mock flow definition snippet showing how properties may be configured for a TransitionableState in XML and in Java code: @@ -367,24 +367,24 @@ http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"> <start-state idref="myStateId"/> - + <xxx-state id="myStateId"> <attribute name="..." value="..."/> - + <entry-actions> ... </entry-actions> <transition on="..." to="..."/> <transition on-exception="..." to="..."/> - + <exit-actions> ... </exit-actions> <exception-handler .../> </xxx-state> - + </flow> @@ -399,8 +399,8 @@ state.getExitActionList().add(...); - A State is typically constructed by a FlowArtifactFactory, used by - a FlowBuilder during flow assembly. The flow building subsystem is contained within the + A State is typically constructed by a FlowArtifactFactory, used by + a FlowBuilder during flow assembly. The flow building subsystem is contained within the org.springframework.webflow.engine.builder package. @@ -412,11 +412,11 @@ This is modeled using a TransitionDefinition. - Recall that all TransitionableStates have a set of one or more transitions, each defining a + 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 + 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 submit event that matches the transition to the "Process Submit" state. @@ -503,7 +503,7 @@ Transition XML template <transition on="event" to="targetState"> - <attribute ... /> + <attribute ... /> <action ... /> </transition> @@ -527,15 +527,15 @@ executes as executionCriteria. If one or more of these actions do not complete successfully the transition will not be allowed. This action transition criteria 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 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. Dynamic transitions - A transition's target state resolver can be configured to dynamically calculate the + A transition's target state resolver can be configured to dynamically calculate the target state. For example: @@ -549,27 +549,27 @@ Global transitions - As outlined, one or more transitions are added to all TransitionableState types, + 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 flow-level where they are shared by all states. These shared transitions are called global transitions. - When an event is signaled in a transitionable state the state will first try and + 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 NoMatchingTransitionException will be thrown. - 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 + 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. Global transitions - XML example - The following example shows transitions defined at the state level, as well as + The following example shows transitions defined at the state level, as well as global transitions defined at the flow level. @@ -579,9 +579,9 @@ 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> @@ -589,18 +589,18 @@ <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 + Any other states defined within this flow would also inherit those global transitions. @@ -616,14 +616,14 @@ Global transitions - + Transition executing state exception handlers The <transition/> element contains an exclusive on-exception - attribute used to specify an exception-based criteria for transition execution. This allows you to + 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. @@ -640,14 +640,14 @@ 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> @@ -661,8 +661,8 @@ Concrete state types - Spring Web Flow has five (5) built-in concrete state types, all contained within the - org.springframework.webflow.engine package. These states execute common + Spring Web Flow has five (5) built-in concrete state types, all contained within the + org.springframework.webflow.engine package. These states execute common controller behaviors including: allowing the user to participate in a flow (ViewState) @@ -689,7 +689,7 @@ As you will see, with these five basic state types you can develop rich controller modules. - + ViewState @@ -698,13 +698,13 @@ - The entered view state makes a org.springframework.webflow.execution.ViewSelection + The entered view state makes a org.springframework.webflow.execution.ViewSelection that represents a logical response to issue to the caller. - The flow execution 'pauses' in this state, and control is returned to the calling + The flow execution 'pauses' in this state, and control is returned to the calling system. @@ -716,7 +716,7 @@ - After some 'think time' the user signals an input event to resume the flow execution + After some 'think time' the user signals an input event to resume the flow execution from the 'paused' point. @@ -725,7 +725,7 @@ 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 not - responsible for response rendering--as a controller, a flow makes a logical view selection when user input is required, + responsible for response rendering--as a controller, a flow makes a logical 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. @@ -771,8 +771,8 @@ - The org.springframework.webflow.execution.ViewSelection base class is abstract, - acting as a marker indicating a response should be issued to the client interacting + The org.springframework.webflow.execution.ViewSelection 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: @@ -795,13 +795,13 @@ FlowExecutionRedirect - Requests a redirect back to the ViewState at a unique flow execution URL. + Requests a redirect back to the ViewState at a unique flow execution URL. 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. - + 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 + 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. @@ -811,21 +811,21 @@ FlowDefinitionRedirect - Requests a redirect that launches an entirely new flow execution. Used to support + Requests a redirect that launches an entirely new flow execution. Used to support redirect to flow (flow chaining) and restart flow use cases. ExternalRedirect - Requests a redirect to an arbitrary external URL, typically used to inteface + Requests a redirect to an arbitrary external URL, typically used to inteface with an external system. NullView - Requests that no response be issued; for use in corner cases where the flow itself has already + Requests that no response be issued; for use in corner cases where the flow itself has already issued the response. @@ -868,7 +868,7 @@ FlowDefinitionRedirectSelector - Returns a FlowDefinitionRedirect with a flowId and executionInput map requesting + Returns a FlowDefinitionRedirect with a flowId and executionInput map requesting the launch of an entirely new flow execution (an instance of the FlowDefinition identified by the flowId). Useful for redirect after flow completion, where one flow ending should trigger the start of another flow independently. @@ -891,7 +891,7 @@ - + ViewState class diagram @@ -914,8 +914,8 @@ ViewState XML - application view selection - 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 + 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: @@ -927,14 +927,14 @@ 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> @@ -942,11 +942,11 @@ achieve runtime view name calculation. For example, view="${requestScope.calculatedViewName}". - + ViewState API - application view selection - The following example shows the equivalent view state definition using + The following example shows the equivalent view state definition using the FlowBuilder API: @@ -958,9 +958,9 @@ transition(on("cancel"), to("processFormCancellation")) } ); - ... + ... } - } + } @@ -979,17 +979,17 @@ 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 + 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 @@ -1000,20 +1000,20 @@ The above example is one way to achieve the POST+REDIRECT+GET pattern in Spring Web Flow. When the redirect is performed, the GET request issued hits a stable flow execution URL - which remains active for the duration of the conversation. This URL may be freely refreshed. + 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. - Later in this document the execution attribute alwaysRedirectOnPause is discussed, + Later in this document the execution attribute alwaysRedirectOnPause is discussed, which enforces this pattern by default. In that case each time a view state is entered a redirect is always performed--automatically. - + ViewState API - flow execution redirect - The following example shows the equivalent view state definition using + The following example shows the equivalent view state definition using the FlowBuilder API: @@ -1022,9 +1022,9 @@ addViewState("displayList", viewSelector("redirect:yourView"), transition(on("add"), to("addListItem")) ); - ... + ... } - } + } @@ -1050,7 +1050,7 @@ </view-state> ... - + </flow> @@ -1066,22 +1066,22 @@ ViewState XML - form state behavior - The following example illustrates a view-state definition in XML that encapsulates + 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 + 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 + 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 + 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: @@ -1098,14 +1098,14 @@ <render-actions> <action bean="formAction" method="setupForm"/> <action bean="formAction" method="loadFormReferenceData"/> - </render-actions> + </render-actions> <transition on="submit" to="saveForm"> <action bean="formAction" method="bindAndValidate"/> </transition> </view-state> ... - + </flow> @@ -1119,32 +1119,32 @@ ActionState - When entered, an action state executes business application code, then responds to the result of that + 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: The entered action state executes an ordered list of one or more - org.springframework.webflow.execution.Action - instances. This Action interface is the central abstraction that + org.springframework.webflow.execution.Action + instances. This Action interface is the central abstraction that encapsulates the execution of a logical unit of application code. - 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 + 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. - Spring Web Flow gives you full control over implementing your own actions and configuring when they should be invoked + 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 automatically adapt methods on your existing application objects (POJOs) to the Action 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 + 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. @@ -1180,7 +1180,7 @@ Action execution points - As outlined, the ActionState is the dedicated state type for invoking one + 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 @@ -1219,7 +1219,7 @@ A state's <entry-actions/> - + on transition @@ -1228,7 +1228,7 @@ A transition <action/> - + on state exit @@ -1237,7 +1237,7 @@ A transitionable state's <exit-actions/> - + before view rendering @@ -1246,7 +1246,7 @@ A view state's <render-actions/> - + on flow end @@ -1255,7 +1255,7 @@ A flow's <end-actions/> - + @@ -1266,18 +1266,18 @@ 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. - + Action attributes - An Action may be annotated with attributes by wrapping the Action + 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 + Support for setting several common attributes is provided for convenience. These include: @@ -1310,7 +1310,7 @@ The name of the action, used to qualify the action's result event. For example, an Action named placeOrder that returns success would be assigned a result event identified by placeOrder.success. - This allows you to distinguish logical execution outcomes by action, useful when + This allows you to distinguish logical execution outcomes by action, useful when invoking multiple actions as part of a chain. @@ -1318,14 +1318,14 @@ method The name of the target method on the Action instance to invoke to carry out execution. - This facilitates multiple action methods per Action instance, + This facilitates multiple action methods per Action instance, supported by the org.springframework.webflow.action.MultiAction. -
- + + ActionState class diagram @@ -1358,14 +1358,14 @@ 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 @@ -1373,7 +1373,7 @@ transition to the displayResults state." - The binding between the searchAction id and an + 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: @@ -1389,33 +1389,33 @@ 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"); } } - + ActionState API - standard action - The following example constructs the equivalent action state definition using + The following example constructs the equivalent action state definition using the FlowBuilder API: @@ -1424,15 +1424,15 @@ ... addActionState("executeSearch", action("searchAction"), transition(on("success"), to("displayResults"))); - ... + ... } - } + } - + ActionState XML - multi action - The next example constructs an ActionState definition from XML that + 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: @@ -1442,16 +1442,16 @@ 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 @@ -1460,27 +1460,27 @@ transition to the displayResults state." - A SearchAction implementation containing multiple action methods + 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(); } @@ -1494,15 +1494,15 @@ ... return success(); } - } + } - As you can see, this allows you to define one to many action methods per Action class. + As you can see, this allows you to define one to many action methods per Action class. With this approach, there are two requirements: - Your Action class must extend from org.springframework.webflow.MultiAction, or - another class that extends from MultiAction. The multi action cares + Your Action class must extend from org.springframework.webflow.MultiAction, or + another class that extends from MultiAction. The multi action cares for the action method dispatch that is based on the value of the method property. @@ -1511,18 +1511,18 @@ Each action method must conform to the signature illustrated above: public Event ${method}(RequestContext) { ... } - - + + - MultiActions are useful for centralizing command logic on a per-flow definition basis, as + 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. - + ActionState API - multi action - The following example constructs the equivalent action state definition using + The following example constructs the equivalent action state definition using the FlowBuilder API: @@ -1531,15 +1531,15 @@ ... addActionState("executeSearch", invoke("executeSearch", action("searchAction")), transition(on("success"), to("displayResults"))); - ... + ... } - } + } - + ActionState XML - bean action - The next example constructs an ActionState definition from XML that + 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"?> @@ -1562,32 +1562,32 @@ </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 + 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, + 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 + 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 + 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. @@ -1610,7 +1610,7 @@ Bean->Action adapter - + ActionState XML - decision bean action @@ -1624,25 +1624,25 @@ 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> + </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 + This state definition reads "if the isShippingRequired method on the shippingService returns true, transition to the enterShippingDetails state, otherwise transition to the placeOrder state." @@ -1653,7 +1653,7 @@ - This conversion process is handled by the action adapter responsible for adapting the method on your + 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. @@ -1709,7 +1709,7 @@ ActionState XML - decision bean action with enum return value The following example constructs an ActionState from - XML that executes a action that invokes a method on an application object that + XML that executes a action that invokes a method on an application object that returns a java.lang.Enum: @@ -1719,9 +1719,9 @@ 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> @@ -1734,11 +1734,11 @@ </action-state> ... - + </flow> - This state definition reads "if the calculateShippingMethod method on the + 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." @@ -1748,7 +1748,7 @@ ActionState XML - evaluate action The following example constructs an ActionState from - XML that executes a action that evaluates an expression against the + XML that executes a action that evaluates an expression against the flow request context and exposes the evaluation result: @@ -1758,8 +1758,8 @@ 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"/> @@ -1775,7 +1775,7 @@ The expression can evaluate any object traversable from the flow's - org.springframework.webflow.execution.RequestContext. This example expression evaluates the + org.springframework.webflow.execution.RequestContext. This example expression evaluates the nextQuestion method on the interview business object in flow scope. @@ -1793,11 +1793,11 @@ 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"> @@ -1810,7 +1810,7 @@ This flow definition reads "display the fileUploadForm. On form submit invoke the uploadFile method - on the uploadAction. On success allow the user + 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. @@ -1818,8 +1818,8 @@ 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 + 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. @@ -1854,11 +1854,11 @@ MultiAction - To group related command logic together. Particularly - useful for when there are multiple related behaviors + To group related command logic together. Particularly + useful for when there are multiple related behaviors called by a flow. - + Bean action @@ -1872,22 +1872,22 @@ EvaluateAction - When you need to invoke a bean in flow scope or evaluate + When you need to invoke a bean in flow scope or evaluate any other flow expression. - + SetAction - When you need to set an attribute in flow or other scope + When you need to set an attribute in flow or other scope during the course of flow execution. - + - + @@ -1897,7 +1897,7 @@ - Evaluating one or more boolean expressions against the executing flow to decide + Evaluating one or more boolean expressions against the executing flow to decide what state to transition to next. @@ -1925,7 +1925,7 @@ transitions (inherited from TransitionableState) - The transitions that are evaluated on an event occurrence that + The transitions that are evaluated on an event occurrence that forms the basis for the decision. @@ -1934,12 +1934,12 @@ - + DecisionState XML - expression evaluation The following example constructs a DecisionState from - XML that evalutes a boolean expression to determine what transition + XML that evalutes a boolean expression to determine what transition to execute: @@ -1950,26 +1950,26 @@ 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 + 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." - Caution: flow definitions should not be vehicles for + 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 + 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 application code where it belongs and instruct the flow to invoke that code using an action. @@ -1984,7 +1984,7 @@ Recall that a flow is a reusable, self-contained controller module. The ability for one flow to call another flow - gives you the ability to compose independent modules together to create complex controller workflows. Any flow can be used as subflow + 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: @@ -1996,7 +1996,7 @@ - A newly launched flow can be passed input attributes which it may choose + A newly launched flow can be passed input attributes which it may choose to map into its own local scope. @@ -2009,8 +2009,8 @@ - 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 + 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. @@ -2045,7 +2045,7 @@ attributeMapper - The strategy responsible for mapping input attributes to the subflow and + The strategy responsible for mapping input attributes to the subflow and mapping output attributes from the subflow. @@ -2075,13 +2075,13 @@ - When the subflow ends, a result event is returned describing the flow outcome + When the subflow ends, a result event is returned describing the flow outcome that occurred. The parent flow resumes back in the subflow state. - The resumed subflow state messages its attributeMapper to + The resumed subflow state messages its attributeMapper to map any output attributes returned by the subflow into flow scope, if necessary. @@ -2122,7 +2122,7 @@ http://www.springframework.org/schema/webflow/spring-webflow-1.0.xsd"> ... - + <subflow-state id="enterShippingDetails" flow="shipping"> <attribute-mapper> <input-mapper> @@ -2131,22 +2131,22 @@ </attribute-mapper> <transition on="finish" to="placeOrder"/> </subflow-state> - + ... - + </flow> - This subflow state definition reads "spawn the shipping flow + This subflow state definition reads "spawn the shipping flow and pass it the value of the shipping property on the order object in flow scope as an input attribute with the name shipping. - When the shipping flow ends, respond to the finish + When the shipping flow ends, respond to the finish result event by transitioning to the placeOrder state." - 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 + 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. @@ -2163,21 +2163,21 @@ ... 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; } - } + } Flow input mapping - input contract - Internally within the definition of the shipping flow referenced above, the flow + Internally within the definition of the shipping flow referenced above, the flow may choose to map the shipping 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: @@ -2193,19 +2193,19 @@ <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 shipping input attribute into flowScope under - the name shipping." + the name shipping." - Had this input mapping not been defined the shipping attribute made available as input + 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. @@ -2214,13 +2214,13 @@ EndState - When entered, an end state terminates a flow. A EndState represents exactly one logical + When entered, an end state terminates a flow. A EndState represents exactly one logical flow outcome; for example, "finish", or "cancel". If the ended flow was acting as a top-level or root flow the entire flow execution ends and cannot be resumed. In this case the end state is responsible - for making a ViewSelection that is the basis for the ending response (for example, + for making a ViewSelection that is the basis for the ending response (for example, a confirmation page, or a redirect request to another flow or an external URL). @@ -2235,7 +2235,7 @@ As outlined, an end state entered as part of a root flow messages its ViewSelector - to make a ending view selection. Typically this is a redirect-based ViewSelector, + to make a ending view selection. Typically this is a redirect-based ViewSelector, allowing for redirect after flow completion. An end state entered as part of a subflow is not responsible for a view selection; this responsibility falls on the calling flow. @@ -2243,18 +2243,18 @@ EndState result events 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 + 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 + 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 parameters. This allows you to return data along - with the logical flow outcome. + are returned as result event parameters. 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 @@ -2306,7 +2306,7 @@ EndState XML - redirect to flow after completion The following example constructs an EndState from - XML that terminates a shipping subflow and requests a + XML that terminates a shipping subflow and requests a redirect response to another flow: @@ -2316,23 +2316,23 @@ 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 + This end state definition reads "terminate the order flow and redirect to a new execution of the searchFlow". - + EndState XML - redirect after flow completion The following example constructs an EndState from - XML that terminates a shipping subflow and requests a + XML that terminates a shipping subflow and requests a redirect response to an external URL: @@ -2342,21 +2342,21 @@ 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} + 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 + 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 REST-style URLs). @@ -2373,19 +2373,19 @@ 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 + This end state definition reads "terminate the shipping flow and expose the shipping property in flow scope as an output attribute with name shipping." @@ -2404,19 +2404,19 @@ 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 + 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. SubflowState XML - mapping an output attribute - The next example shows how a subflow-state can respond to the ending + The next example shows how a subflow-state can respond to the ending result of a subflow and map output attributes into its own scope: @@ -2426,9 +2426,9 @@ 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> @@ -2437,25 +2437,25 @@ </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 + 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." - Had this output mapping not been defined the shipping attribute made available as output + 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. - + \ No newline at end of file