From dfab2a1919e4ccaabcc6af570a28297fda587910 Mon Sep 17 00:00:00 2001 From: Keith Donald Date: Mon, 22 Sep 2008 22:26:20 +0000 Subject: [PATCH] doc polish --- spring-webflow-reference/src/spring-mvc.xml | 147 ++++++++++++------ .../WEB-INF/hotels/booking/bookingForm.jsp | 2 +- 2 files changed, 99 insertions(+), 50 deletions(-) diff --git a/spring-webflow-reference/src/spring-mvc.xml b/spring-webflow-reference/src/spring-mvc.xml index 09188496..2aedd325 100644 --- a/spring-webflow-reference/src/spring-mvc.xml +++ b/spring-webflow-reference/src/spring-mvc.xml @@ -41,69 +41,77 @@ The DispatcherServlet maps requests for application resources to handlers. A flow is one type of handler. - - The first step to dispatching requests to flows is to enable flow handling within Spring MVC. - To this, install the FlowHandlerAdapter: - - + Registering the FlowHandlerAdapter + + The first step to dispatching requests to flows is to enable flow handling within Spring MVC. + To this, install the FlowHandlerAdapter: + + - -]]> - - - 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 FlowHandlerMapping: - - ]]> + + + + Defining flow mappings + + 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 FlowHandlerMapping: + + ]]> - - - Configuring this mapping allows the Dispatcher to map application resource paths to flows in a flow registry. - For example, accessing the resource path /hotels/booking would result in a registry query for the flow with id hotels/booking. - 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. - + + + Configuring this mapping allows the Dispatcher to map application resource paths to flows in a flow registry. + For example, accessing the resource path /hotels/booking would result in a registry query for the flow with id hotels/booking. + 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. + + + + Flow handling workflow + + 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 FlowHandler is the extension point that can be used to customize how flows are executed in a HTTP servlet environment. - A FlowHandler is used by the FlowHandlerAdapter and responsible for: + A FlowHandler is used by the FlowHandlerAdapter and is responsible for: @@ -192,6 +200,9 @@ public class BookingFlowHandler extends AbstractFlowHandler { The bookingConfirmed outcome will result in a redirect to show the new booking. Any other outcome will redirect back to the hotels index page. + + + Deploying a custom FlowHandler 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. @@ -250,4 +261,42 @@ public class BookingFlowHandler extends AbstractFlowHandler { ]]> + + Signaling an event from a View + + When a flow enters a view-state it pauses, redirects the user to its execution URL, and waits for a user event to resume. + Events are generally signaled by activating buttons, links, or other user interface commands. + How events are decoded server-side is specific to the view technology in use. + This section shows how to trigger events from HTML-based views generated by templating engines such as JSP, Velocity, or Freemarker. + + + Using a named HTML button to signal an event + +]]> + + + + Using a hidden HTML form parameter to signal an event + +]]> + + + + Using a HTML link to signal an event + Cancel]]> + + + + Firing an event results in a HTTP request being sent back to the server. + On the server-side, the flow handles decoding the event from within its current view-state. + How this decoding process works is specific to the view implementation. + A Spring MVC view implementation simply looks for a request parameter named _eventId. + If no _eventId parameter is found, the view will look for a parameter that + starts with _eventId_ and will use the remaining substring as the event id. + If neither cases exist, no flow event is triggered. + + \ No newline at end of file diff --git a/spring-webflow-samples/booking-mvc/src/main/webapp/WEB-INF/hotels/booking/bookingForm.jsp b/spring-webflow-samples/booking-mvc/src/main/webapp/WEB-INF/hotels/booking/bookingForm.jsp index 3af4f1d1..59555a55 100644 --- a/spring-webflow-samples/booking-mvc/src/main/webapp/WEB-INF/hotels/booking/bookingForm.jsp +++ b/spring-webflow-samples/booking-mvc/src/main/webapp/WEB-INF/hotels/booking/bookingForm.jsp @@ -175,7 +175,7 @@ -   +   \ No newline at end of file