diff --git a/spring-webflow/changelog.txt b/spring-webflow/changelog.txt index ee88d3cc..df67ee5a 100644 --- a/spring-webflow/changelog.txt +++ b/spring-webflow/changelog.txt @@ -15,6 +15,9 @@ Package org.springframework.webflow.execution * Made the Event class non-final to allow for extension (SWF-330). * Now allow multiple conversation containers per session in a manner that supports use in a cluster (SWF-378). +Package reference-manual +* Improved readability of reference manual in several sections (SWF-349). + Changes in version 1.0.4 (13.06.2007) ------------------------------------- diff --git a/spring-webflow/docs/reference/src/flow-definition.xml b/spring-webflow/docs/reference/src/flow-definition.xml index b466e799..4e0745e2 100644 --- a/spring-webflow/docs/reference/src/flow-definition.xml +++ b/spring-webflow/docs/reference/src/flow-definition.xml @@ -102,7 +102,7 @@ variables - The set of flow variables to create each time an execution of the flow is started. + The set of flow instance variables to create each time an execution of the flow is started. 0..* @@ -111,7 +111,7 @@ inputMapper - The service responsible for mapping flow input provided by a caller each time an + The service responsible for mapping flow input provided by the client each time an execution of the flow is started. @@ -138,8 +138,7 @@ outputMapper - The service responsible for mapping flow output to expose to the caller each time an - execution of the flow ends. + The service responsible for mapping flow output to expose to the client each time an execution of the flow ends. 0..1 @@ -242,7 +241,8 @@ 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. - The XML-based format is the most popular way to define flows. + The XML-based format is currently the most popular way to define flows, though + Groovy-based and Java-based formats are emerging. @@ -414,7 +414,7 @@ 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. + When a transitionable state is entered, it executes a behavior. For example, a transitionable state called "Display Form" may display a form to the user and wait for user input. The outcome of the state's execution, called an event, is used to drive execution of one of the state's transitions. For example, the user may press the form submit button which @@ -520,13 +520,12 @@ Action transition execution criteria - In the XML transition template above note the support for the action element within the transition element. + In the XML transition template above, note the support for the action element within the transition element. A transition may be configured with one or more actions that execute before the transition itself - 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 + executes. If one or more of these actions do not complete successfully, the transition will not be allowed. + This execution 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 form submit event. @@ -535,15 +534,14 @@ Dynamic transitions - A transition's target state resolver can be configured to dynamically calculate the - target state. For example: + A transition's target state resolver can be configured to dynamically calculate the target state. For example: - <transition on="back" to="${flowScope.lastStateId}" /> + <transition on="back" to="${flowScope.lastViewStateId}" /> This will transition the flow to the state resolved by evaluating the - flowScope.lastStateId expression. + flowScope.lastViewStateId expression. @@ -555,9 +553,9 @@ transitions are called global transitions. - 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 + 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. @@ -598,7 +596,7 @@ </flow> - In this mock example state1 defines one transition and also inherits + 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. @@ -651,7 +649,7 @@ </flow> - In this example state1 defines one transition and an exception handler + 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 using the key "stateException". That way it is available for processing in the flow or display in a view. @@ -694,7 +692,7 @@ ViewState - When entered a view state allows the user (or other external client) to participate + When entered, a view state allows the user (or other external client) to participate in a flow. This participation process goes as follows: @@ -717,7 +715,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,8 +723,8 @@ 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, + how a view state responds to a user input event. Spring Web Flow is currently not + concerned with rendering the actual response; 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. @@ -797,12 +795,12 @@ FlowExecutionRedirect 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. + 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. @@ -1005,17 +1003,15 @@ Browser navigational buttons may be used freely without browser warnings. - 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. + The execution attribute alwaysRedirectOnPause, which enforces this pattern by default, + is discussed later in this document. In that case, each time a view state is entered a redirect is always performed. ViewState API - flow execution redirect - The following example shows the equivalent view state definition using - the FlowBuilder API: + The following example shows the equivalent view state definition using the FlowBuilder API: public class SearchFlowBuilder extends AbstractFlowBuilder { @@ -1032,7 +1028,7 @@ ViewState XML - null view The following example illustrates a view-state definition in XML that makes a - null view selection when entered, which causes no additional response to be issued. + null view selection when entered. This causes no additional response to be issued. <?xml version="1.0" encoding="UTF-8"?> @@ -1059,9 +1055,9 @@ FlowDefinitionRedirect and ExternalRedirect The FlowDefinitionRedirect and ExternalRedirect are not - normally used with a view state. Instead they're used in an end state to continue with another, - independent flow or to redirect to an external URL. Examples are provided in the discussion of the - end state. + 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. @@ -1184,12 +1180,12 @@ 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 + At all of these points, the only requirement is that these actions implement the central org.springframework.webflow.execution.Action interface. - Other points in a Flow where an Action can be executed and how those points + Other points in a Flow where an Action can be executed, and how those points can be defined in a XML-based Flow definition. @@ -1264,7 +1260,7 @@ - The above other points in a flow where actions may be executed do not + 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. @@ -1280,8 +1276,7 @@ the action's execution in a specific usage context. - Support for setting several common attributes is provided for convenience. These - include: + Support for setting several common attributes is provided for convenience. These include:
Common Action attributes @@ -1298,7 +1293,7 @@ caption - A short description about the action, suitable for display as a tooltip. + A short description about the action, suitable for display as a tool-tip. @@ -1743,8 +1738,8 @@ 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." + state. If the return value is EXPRESS, transition to the enterExpressShippingDetails state. + If the return value is NONE, transition to the placeOrder state." @@ -1773,7 +1768,7 @@ </flow> - This state definition reads "evaluate the flowScope.interview.nextQuestion() expression + This state definition reads "evaluate the flowScope.interview.nextQuestion() expression, and expose the result under name question in the default scope." @@ -1812,8 +1807,8 @@ This flow definition reads "display the fileUploadForm. - On form submit invoke the uploadFile method - on the uploadAction. On success allow the user + 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. @@ -1821,7 +1816,7 @@ Flash scoped attributes are preserved until the next user event is signaled into - the flow execution. In this example this means the fileUploaded + 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. @@ -1975,7 +1970,7 @@ 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 + Instead, push such a calculation into business application code where it belongs and instruct the flow to invoke that code using an action. @@ -2001,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. @@ -2015,7 +2010,7 @@ 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 + 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. @@ -2142,10 +2137,9 @@ </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 + 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." @@ -2182,10 +2176,15 @@ Flow input mapping - input contract - 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: + 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. + + + 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"?> @@ -2204,8 +2203,8 @@ </flow> - This short-form input mapper declaration reads "when a new execution of this flow starts - map the shipping input attribute into flowScope under + 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." @@ -2223,19 +2222,19 @@ 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 + 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, a confirmation page, or a redirect request to another flow or an external URL). If the ended flow was acting as a subflow, the spawned subflow session ends and the calling parent flow resumes by responding to the end - result returned. In this case the responsibility for any ViewSelection + result returned. In this case, the responsibility for any ViewSelection falls on the parent flow. - Once a flow ends any attributes in flow scope go out of scope immediately + Once a flow ends, any attributes in flow scope go out of scope immediately and become eligible for garbage collection. @@ -2258,7 +2257,7 @@ 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 + are returned as result event attributes. This allows you to return data along with the logical flow outcome. @@ -2329,7 +2328,7 @@ </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". @@ -2355,14 +2354,14 @@ </flow> - This end state definition reads "terminate the order 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 REST-style URLs). + to be viewed (in this case using a REST-style URL). @@ -2390,7 +2389,7 @@ </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." @@ -2412,7 +2411,7 @@ } - Since this end-state does not make a view selection it is expected this flow will be always used + 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. @@ -2422,7 +2421,7 @@ SubflowState XML - mapping an output attribute 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: + result of a subflow, and map subflow output attributes into its own scope: <?xml version="1.0" encoding="UTF-8"?> @@ -2449,14 +2448,14 @@ 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. diff --git a/spring-webflow/docs/reference/src/flow-execution-repository.xml b/spring-webflow/docs/reference/src/flow-execution-repository.xml index a3408bcc..b6009062 100644 --- a/spring-webflow/docs/reference/src/flow-execution-repository.xml +++ b/spring-webflow/docs/reference/src/flow-execution-repository.xml @@ -15,12 +15,12 @@ challenges, as there must exist a stable mechanism for a new request to be associated with an existing execution in the view state that matches what the user expects. This problem is more difficult when you consider that many applications require use of browser - navigational buttons and their use involves updating local history without + navigational buttons, and use of these buttons involves updating local history without notifying the server. The problem of flow execution persistence is addressed by Spring Web Flow's flow - execution repository subsystem. In this chapter you will learn how to use the system + execution repository subsystem. In this chapter, you will learn how to use the system to manage the storage of active web conversations in a stable manner. @@ -34,9 +34,9 @@ When a flow execution reaches a ViewState it is said to have paused, - where it waits in that state for user input to be provided so it can continue. After pausing the + where it waits in that state for user input to be provided so it can continue. After pausing, the ViewSelection returned is used to issue a response to the user - that provides a vehicle for collecting the required input. + that provides a vehicle for collecting the required user input. @@ -49,7 +49,7 @@ - Each time an active flow execution is paused it is saved out to a + Each time an active flow execution is paused, it is saved out to a repository. When the next request comes in for that flow execution, it is restored from the repository, resumed, and continued. This process continues until the flow execution reaches an end state, at which time it is removed from the repository. @@ -83,11 +83,11 @@ Flow execution identity - When a flow execution is created it marks the start of a new conversation between a browser - and the server. As outlined, a new flow execution that is still active after startup + When a new flow execution is created, it marks the start of a new conversation between a browser + and the server. A new flow execution that is still active after startup processing indicates the start of a conversation that will span more than one request and needs to be persisted. When this is the case, that flow execution is assigned - an persistent identifer by the repository. By default the + an persistent identifer by the repository. By default, the structure of this identifier consists of a two-part composite key. This key is used by clients to restore the flow execution on subsequent requests. @@ -114,21 +114,21 @@ Together the conversation id plus the continuation id make up the unique two-part flow execution key that identifies a state of a conversation at a point in time. By submitting this key - in a subsequent request a browser can restore the conversation at that point + in a subsequent request, a browser can restore the conversation at that point and continue from there. - So on a subsequent request the conversation is resumed by restoring a flow execution - from the repository using the two-part key. After event processing if the + So on a subsequent request, the conversation is resumed by restoring a flow execution + from the repository using the two-part key. After event processing, if the flow execution is still active it is saved back out to the repository. - At this time a new flow execution key is generated. By default that key + At this time a new flow execution key is generated. By default, that key retains the same conversation identifier, as the same logical conversation is in progress; however the continuation identifier changes to provide an index into the state of the flow execution at this new point in time. - By submitting this new key in a subsequent request a browser can + By submitting this new key in a subsequent request, a browser can restore the conversation at that point and continue from there. This process continues until a flow execution reaches an end state during event processing signaling the end of the conversation. @@ -144,8 +144,8 @@ resulting in any flow execution continuations associated with the conversation being purged. - Once a conversation has been ended the conversation identifier is no longer valid - and cannot ever be used again. + Once a conversation has ended, the conversation identifier is no longer valid + and can never be used again. diff --git a/spring-webflow/docs/reference/src/flow-execution.xml b/spring-webflow/docs/reference/src/flow-execution.xml index 874a33b6..ed0a30bc 100644 --- a/spring-webflow/docs/reference/src/flow-execution.xml +++ b/spring-webflow/docs/reference/src/flow-execution.xml @@ -4,14 +4,14 @@ Introduction - Once a flow has been defined any number of executions of it can be launched in parallel + Once a flow has been defined, any number of executions of it can be launched in parallel at runtime. Execution of a flow is carried out by a dedicated system that is based internally on a state machine that runs atop the Java VM. As the life of a flow execution can span more than one request into the server, this system is also responsible for persisting execution state across requests. - This chapter documents Spring Web Flow's flow execution system. You'll + This chapter documents Spring Web Flow's flow execution system. You will learn the core constructs of the system and how to execute flows out-of-container within a JUnit test environment. @@ -20,9 +20,9 @@ FlowExecution A org.springframework.webflow.execution.FlowExecution is a runtime instantiation of a flow definition. - Given a single FlowDefinition any - number of independent flow executions may be created, typically by a - FlowExecutionFactory. + Given a single FlowDefinition, any + number of independent flow executions may be created. + These executions are typically created by a FlowExecutionFactory. A flow execution carries out the execution of program instructions defined within @@ -30,7 +30,7 @@ - It may be helpful to think of a flow definition as analagous to a Java Class and a + It may be helpful to think of a flow definition as analagous to a Java Class, and a flow execution as analagous to an object instance of that Class. Signaling an execution event can be considered analagous to sending an object a message. @@ -44,8 +44,8 @@ Once created, a new flow execution is initially inactive, waiting to be started. Once - started a flow execution becomes active by entering its startState. - From there it continues executing until it enters a state where user input is required + started, a flow execution becomes active by entering its startState. + From there, it continues executing until it enters a state where user input is required to continue or it terminates. @@ -57,10 +57,10 @@ ViewSelection startingView = execution.start(input, context); - When a flow execution reaches a state where input is required to continue it is said to have paused, - where it waits in that state for the input to be provided. After pausing the - ViewSelection returned is typically used to issue a response to the user - that provides a vehicle for collecting the required input. + When a flow execution reaches a state where input is required to continue, it is said to have paused, + where it waits in that state for user input to be provided. After pausing, the + ViewSelection returned is used to issue a response to the user + that provides a vehicle for collecting the required user input. User input is provided by signaling an event that @@ -69,7 +69,7 @@ resumes by consuming the event. - Once a flow execution has resumed it continues executing until it again enters a + Once a flow execution has resumed, it continues executing until it again enters a state where more input is needed or it terminates. Once a flow execution has terminated it becomes inactive and cannot be resumed. @@ -335,8 +335,7 @@ the session at the top of the stack. - The contextual properties associated with a FlowSession - are summarized below: + The contextual properties associated with a FlowSession are summarized below:
Flow Session properties @@ -422,7 +421,7 @@ - In this illustration a flow execution has been created for the Book Flight flow. + In this illustration, a flow execution has been created for the Book Flight flow. The execution is currently active and the activeSession indicates it is in the Display Seating Chart state of the Assign Seats flow, which was spawned as a subflow from the Enter Seat Assignments state. @@ -488,7 +487,7 @@ Spring Web Flow provides support within the org.springframework.webflow.test package for testing flow executions with JUnit. This support is provided as convenience but is entirely optional, as a flow execution is instantiable in any environment with the standard - new operator. + Java new operator. The general strategy for testing flows follows: @@ -595,13 +594,13 @@ - On form submit and successful data binding and validation the search is executed. + On form submit and successful data binding and validation, the search is executed. After search execution a results view is displayed. - From the results view the user may select a result they wish to browse additional details on + From the results view, the user may select a result they wish to browse additional details on or they may request a new search. On select, the "detail" flow is spawned and when it finishes the search is re-executed and it's results redisplayed. @@ -641,7 +640,7 @@ - To assist with writing these assertions Spring Web Flow ships with JUnit-based flow execution + To assist with writing these assertions, Spring Web Flow ships with JUnit-based flow execution test support within the org.springframwork.webflow.test package. These base test classes are indicated below: @@ -741,9 +740,9 @@ } - With a well-written flow execution test passing that covers the controller behavior scenarios - possible for your flow you have concrete evidence the flow will execute as expected when - deployed in a container. + With a well-written flow execution test passing that exercises the scenarios + possible for your flow, you have concrete evidence the flow will execute as expected when + deployed into a container. diff --git a/spring-webflow/docs/reference/src/flow-executor.xml b/spring-webflow/docs/reference/src/flow-executor.xml index f43ad0d3..4d626994 100644 --- a/spring-webflow/docs/reference/src/flow-executor.xml +++ b/spring-webflow/docs/reference/src/flow-executor.xml @@ -9,7 +9,7 @@ across a variety of environments. - In this chapter you'll learn how to execute flows within Spring MVC, Struts, + In this chapter, you will learn how to execute flows within Spring MVC, Struts, and Java Server Faces (JSF) based applications. @@ -48,19 +48,19 @@ Request that the last response issued by a flow execution be re-issued. Unlike start and signalEvent, the refresh operation is an idempotent operation - that does not affect the state of a flow execution. + that does not change the state of a flow execution. Each operation accepts an ExternalContext that provides normalized - access to properties of an external system that has called into Spring Web Flow, allowing - access to environment-specific request parameters as well as request, session, and - application-level attributes. + access to properties of an external system that has called into Spring Web Flow. + This context allows access to environment-specific request parameters as well as + externally-managed request, session, and application-level attributes. - Each operation returns a ResponseInstruction which the calling system is + Each operation returns a ResponseInstruction, which the calling system is expected to use to issue a suitable response. @@ -81,7 +81,7 @@ As you can see, an ExternalContext implementation exists for each of the environments Spring Web Flow supports. If a flow artifact such as an Action needs to access native constructs of the calling environment it can downcast a context to its - specific implementation. The need for such downcasting is considered a special case. + specific implementation. The need for such downcasting is considered a corner case. FlowExecutorImpl @@ -233,8 +233,7 @@ The alwaysRedirectOnPause attribute determines if a flow execution redirect occurs automatically each time an execution pauses (automated POST+REDIRECT+GET behavior). - Setting this attribute to false will disable the default 'true' behavior - where a flow execution redirect always occurs on pause. + Setting this attribute to false will disable the default 'true' behavior. @@ -303,7 +302,7 @@ core Spring Framework. Use of Portlet MVC requires Spring 2.0. - For both Servlet and Portlet MVC a FlowController acts as an adapter + For both Servlet and Portlet MVC, a FlowController acts as an adapter between Spring MVC and Spring Web Flow. As an adapter, this controller has knowledge of both systems and delegates to a flow executor for driving the execution of flows. One controller typically executes all flows of an application, relying on @@ -355,13 +354,6 @@ are extracted from an incoming controller request with the org.springframework.webflow.executor.support.FlowExecutorArgumentExtractor strategy. - - - The various flow controllers typically do not use this strategy directly but instead use a - convenient FlowExecutorArgumentHandler implementation that takes care - of argument extraction as well as exposing responsibilities (in callback URLs). - - The next several examples illustrate strategies for parameterizing flow controllers @@ -446,7 +438,7 @@ - In this case the eventId is determined by parsing the name of the + In this case, the eventId is determined by parsing the name of the button that was pressed. @@ -463,7 +455,7 @@ The request-path based argument extractor strategy relies on executor arguments being path elements as much as possible. This results in friendlier REST-style URLs such - as http://host/app/myflow instead of + as http://host/app/myflow, instead of http://host/app?_flowId=myflow. @@ -529,7 +521,7 @@ takes responsibility for view navigation handling and managing model state, adding power and simplicity to JSF's default navigation system and object scopes. Plain JSF views and components continue to work just as before, and are able to participate in flows with full access to flow state. In addition, other view technologies - such as Facelets and Ajax4JSF continue to plug-in normally. + such as Facelets continue to plug-in normally. The JSF integration relies on custom implementations of core JSF artifacts such as the PhaseListener @@ -566,13 +558,13 @@ The DelegatingFlowVariableResolver resolves JSF a value binding expression like {#someBean.someProperty} to a flow execution attribute. This resolver searches flash, flow, and conversation scope in that order until - it finds a match. If no match is found this resolver delegates to the next resolver in the chain. + it finds a match. If no match is found, this resolver delegates to the next resolver in the chain. Configuring the Web Flow system - The artifacts defined faces-config.xml use Spring to locate the Web Flow system. + The artifacts defined in the faces-config.xml use Spring to access the Web Flow system configuration. This requires a Spring Web Application Context to be bootstrapped using a ContextLoaderListener in the web.xml deployment descriptor: @@ -589,9 +581,8 @@ </listener> - In this example inside webflow-config.xml resides the configuration of the Web Flow system the JSF - artifacts will delegate to. A bean named flowExecutor is configured and - linked with a flow definition registry containing the flows eligible for execution: + This context should contain the Web Flow system configuration. + The example webflow-config.xml below shows a typical Web Flow configuration for a JSF environment: <?xml version="1.0" encoding="UTF-8"?> @@ -615,7 +606,12 @@ </beans> - Any executor property such as the flow execution repository type is configurable here, consistent + A bean named flowExecutor must be configured and linked with a flow definition registry + that contains the flows eligible for execution. Note the flowExecutor bean name is significant, + as that is bean name the Web Flow JSF extensions will expect. + + + Any flow executor property such as the flow execution repository type is configurable here, consistent with the other environments Spring Web Flow supports. @@ -677,7 +673,7 @@ </flow> - A primary benefit of using JSF is it a rich UI component framework, and components have behaviors. + A primary benefit of using JSF is it a rich UI component framework, and UI components have both data and behavior. As JSF components typically handle data binding and validation behaviors, the actual flow definition logic is often simpler and more focused as a result. diff --git a/spring-webflow/docs/reference/src/index.xml b/spring-webflow/docs/reference/src/index.xml index 60fcb289..eed9aea7 100644 --- a/spring-webflow/docs/reference/src/index.xml +++ b/spring-webflow/docs/reference/src/index.xml @@ -15,8 +15,8 @@ Spring Web Flow Reference Documentation - Version 1.0.5-SNAPSHOT - April 2007 + Version 1.0.5 + August 2007 Keith diff --git a/spring-webflow/docs/reference/src/overview.xml b/spring-webflow/docs/reference/src/overview.xml index 9e8be1d7..eb3b8b93 100644 --- a/spring-webflow/docs/reference/src/overview.xml +++ b/spring-webflow/docs/reference/src/overview.xml @@ -242,7 +242,7 @@ Support for working with registries of flow definitions. Flow definitions eligible for execution are typically stored in - a registry providing lookup services. + a registry that provides lookup services. definition.registry @@ -486,7 +486,7 @@ The Executor Layer - Stable higher-layer for driving and coordinating the execution of flow definitions. + Stable higher-level layer for driving and coordinating the execution of flow definitions. This layer is decoupled from the more-volatile engine implementation. @@ -513,7 +513,7 @@ Core - Stable, generic flow executor abstractions and support. + Generic flow executor abstractions and support. executor, @@ -619,7 +619,7 @@ As described above, some subsystem packages are optional depending on your use of the subsystem. For example, use of Spring Web Flow in a Servlet environment entails use of the ExternalContext context.servlet package which requires the - Servlet API to be in the classpath. In this case the context.portlet package is not + Servlet API to be in the classpath. In this case, the context.portlet package is not used and the Portlet API is not required. @@ -633,7 +633,7 @@ Support - Spring Web Flow 1.x is supported on Spring Framework 1.2.7 or > for the 1.x series and + Spring Web Flow 1.x is supported on Spring Framework 1.2.7 or > for the 1.x series, and supported on 2.0 or > for the 2.x series. diff --git a/spring-webflow/docs/reference/src/practical.xml b/spring-webflow/docs/reference/src/practical.xml index 74a197a6..b7bb957e 100644 --- a/spring-webflow/docs/reference/src/practical.xml +++ b/spring-webflow/docs/reference/src/practical.xml @@ -78,7 +78,7 @@ Java 1.5 (or greater) and Ant 1.6 (or greater) are prerequisites for building the sample applications. Ensure those are present in the system path or are passed on the command line. To build Web Flow samples from the command line, open a prompt, cd to the directory where Spring Web Flow was - unzipped and run the following: + unzipped, and run the following: cd projects/spring-webflow/build-spring-webflow ant dist @@ -94,15 +94,14 @@ ant dist Importing Projects into Eclipse Importing the sample projects into Eclipse is easy. With a new or an existing workspace select: - File > Import > Existing Projects into Workspace. In the resulting dialog browse to the project + File > Import > Existing Projects into Workspace. In the resulting dialog, browse to the project subdirectory where Spring Web Flow was unzipped and choose it as the root directory to import from. Select OK. Here Eclipse will list all projects it found including the sample application projects. Select the projects you're interested in, and select Finish. - If you previously built each project from the command line Eclipse will compile with no errors. - If not you will need to run the Ant build once for these errors to clear - and you can do that within Eclipse. + If you previously built each project from the command line, Eclipse will compile with no errors. + If not, you will need to run the Ant build once for these errors to clear. To build all projects inside Eclipse, import and expand the build-spring-webflow project, right-click on @@ -145,7 +144,7 @@ ant dist Other IDE's - Importing samples into other IDE's should be fairly straight-forward. If using another IDE + Importing samples into other IDE's should be fairly straight-forward. If using another IDE, running the Ant build from the command line first may help as it will populate the lib subdirectories of each sample project. Follow steps similar as those outlined for Eclipse above. @@ -349,8 +348,8 @@ public interface SaleProcessor { sparing the need to implement methods for all lifecycle events. - Looking inside SellItemFlowExecutionListener it implements the stateEntering - method executed whenever a new state is about to be entered. + Looking inside SellItemFlowExecutionListener, it implements the stateEntering + method executed for whenever a new state is about to be entered. The logic in this method checks if the current web flow state has an attribute named "role" and if so it ensures the user has that role: @@ -581,7 +580,7 @@ public void registerCustomEditors(PropertyEditorRegistry registry) { The Sellitem-JSF example uses Web Flow and JSF to build a shopping cart wizard. Navigation logic and supporting managed beans - are supplied by Spring Web Flow while UI views and + are supplied by Spring Web Flow, while UI views and overall servlet processing is based on JSF technology. @@ -590,7 +589,7 @@ public void registerCustomEditors(PropertyEditorRegistry registry) { examples are very similar. To avoid repetition the documentation for the Sellitem-JSF example focuses primarily on the points of integration between Web Flow and JSF. For further general information on Web Flow definitions - and supporting Java classes for the Sellitem example please refer to the + and supporting Java classes for the Sellitem example, please refer to the Sellitem example documentation. @@ -615,7 +614,7 @@ public void registerCustomEditors(PropertyEditorRegistry registry) { - In addition the web.xml loads a Spring root web application context containing the services + In addition, the web.xml loads a Spring root web application context containing the services used by the application: <context-param> @@ -642,7 +641,7 @@ public void registerCustomEditors(PropertyEditorRegistry registry) { Web Flow JSF Setup in faces-config.xml - To plug in Web Flow a few things must be added once to faces-config.xml. + To plug in Web Flow, a few things must be added once to faces-config.xml. This is demonstrated in the faces-config.xml of Sellitem-JSF: <application>