diff --git a/spring-webflow-reference/src/spring-mvc.xml b/spring-webflow-reference/src/spring-mvc.xml index 2089d0ca..2f0eb555 100644 --- a/spring-webflow-reference/src/spring-mvc.xml +++ b/spring-webflow-reference/src/spring-mvc.xml @@ -54,10 +54,11 @@ Once flow handling is enabled, the next step is to map specific application resources to your flows. - The simplest way to do this is to define a FlowIdHandlerMapping + The simplest way to do this is to define a FlowIdHandlerMapping: + @@ -69,25 +70,53 @@ If a flow is found with that id, that flow will handle the request. If no flow is found, the next handler mapping in the Dispatcher's ordered chain will be queried or a "noHandlerFound" response will be returned. + + When a valid flow mapping is found, the FlowHandlerAdapter figures out whether to + start a new execution of that flow or resume an existing execution based on information present the HTTP request. + There are a number of defaults related to starting and resuming flow executions the adapter employs: + + + + + HTTP request parameters are made available in the input map of all starting flow executions. + + + + + When a flow execution ends without sending a final response, the default handler will attempt + to start a new execution in the same request. + + + + + Unhandled exceptions are propagated to the Dispatcher unless the exception is a NoSuchFlowExecutionException. + The default handler will attempt to recover from a NoSuchFlowExecutionException by starting over a new execution. + + + + + Consult the API documentation for FlowHandlerAdapter for more information. + You may override these defaults by subclassing or by implementing your own FlowHandler, discussed in the next section. + Implementing custom FlowHandlers - A FlowHandler manages the execution of a single flow definition in a servlet environment. - A FlowHandler is responsible for: + FlowHandler is the extension point that can be used to customize how executions of a flow are managed in a HTTP servlet environment. + A FlowHandler is used by the FlowHandlerAdapter and responsible for: - Providing the id of the flow definition to execute + Returning the id of a flow definition to execute - Creating the input to pass new flow executions + Creating the input to pass new executions of that flow as they are started - Handling flow execution outcomes + Handling outcomes returned by executions of that flow as they end - Handling flow execution exceptions + Handling any exceptions thrown by executions of that flow as they occur @@ -108,15 +137,15 @@ public interface FlowHandler { } - To implement a FlowHandler, subclass AbstractFlowHandler. You only need to override the methods that you need. - Specifically: + To implement a FlowHandler, subclass AbstractFlowHandler. All these operations are optional, and if not implemented + the defaults will apply. You only need to override the methods that you need. Specifically: - Override getFlowId(HttpServletRequest) when the id of your flow cannot be derived from the URL. - By default, the flow id is derived from the last path element in the request URI, before any query parameters. - For example, http://localhost/hotels/booking?hotelId=1 results in a flow id of booking by default. + Override getFlowId(HttpServletRequest) when the id of your flow cannot be directly derived from the HTTP request. + By default, the id of the flow to execute is derived from the pathInfo portion of the request URI. + For example, http://localhost/app/hotels/booking?hotelId=1 results in a flow id of hotels/booking by default. @@ -142,8 +171,8 @@ public interface FlowHandler { Example FlowHandler - A common interaction pattern between Spring MVC And Web Flow is for a Flow to redirect to a Controller when it ends. - FlowHandlers allow this to be done without coupling the flow definition with a specific controller URL. + A common interaction pattern between Spring MVC And Web Flow is for a Flow to redirect to a @Controller when it ends. + FlowHandlers allow this to be done without coupling the flow definition itself with a specific controller URL. An example FlowHandler that redirects to a Spring MVC Controller is shown below: - To use your FlowHandler, first deploy an instance to Spring so it can be mapped to a URL: + To install a custom FlowHandler, simply deploy it as a bean. + The bean name must match the id of the flow the handler should apply to. ]]> +]]> - With this configuration, accessing the URL /hotels/booking will launch the hotels/booking flow. + With this configuration, accessing the resource /hotels/booking will launch the hotels/booking flow using the custom BookingFlowHandler. When the booking flow ends, the FlowHandler will process the flow execution outcome and redirect to the appropriate controller.