11. Spring MVC Integration

The first step to dispatching requests to flows is to enable flow handling within Spring MVC. To this, install the FlowHandlerAdapter:

<!-- Enables FlowHandler URL mapping -->
<bean class="org.springframework.webflow.mvc.servlet.FlowHandlerAdapter">
	<property name="flowExecutor" ref="flowExecutor" />
</bean>
			

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:

<!-- Maps request paths to flows in the flowRegistry;
	e.g. a path of /hotels/booking looks for a flow with id "hotels/booking" -->
<bean class="org.springframework.webflow.mvc.servlet.FlowHandlerMapping">
	<property name="flowRegistry" ref="flowRegistry"/>
	<property name="order" value="0"/>
</bean>
			

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:

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.

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:

public class BookingFlowHandler extends AbstractFlowHandler {
	public String handleExecutionOutcome(FlowExecutionOutcome outcome,
										HttpServletRequest request, HttpServletResponse response) {
		if (outcome.getId().equals("bookingConfirmed")) {
			return "/booking/show?bookingId=" + outcome.getOutput().get("bookingId");
		} else {
			return "/hotels/index";
		}
	}
}
			

Since this handler only needs to handle flow execution outcomes in a custom manner, nothing else is overridden. The bookingConfirmed outcome will result in a redirect to show the new booking. Any other outcome will redirect back to the hotels index page.

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.

<bean name="hotels/booking" class="org.springframework.webflow.samples.booking.BookingFlowHandler" />
			

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.

A FlowHandler handling a FlowExecutionOutcome or FlowException returns a String to indicate the resource to redirect to after handling. In the previous example, the BookingFlowHandler redirects to the booking/show resource URI for bookingConfirmed outcomes, and the hotels/index resource URI for all other outcomes.

By default, returned resource locations are relative to the current servlet mapping. This allows for a flow handler to redirect to other Controllers in the application using relative paths. In addition, explicit redirect prefixes are supported for cases where more control is needed.

The explicit redirect prefixes supported are:

These same redirect prefixes are also supported within a flow definition when using the externalRedirect: directive in conjunction with a view-state or end-state; for example, view="externalRedirect:http://springframework.org"

The example below shows two buttons on the same form that signal proceed and cancel events when clicked, respectively.

<input type="submit" name="_eventId_proceed" value="Proceed" />
<input type="submit" name="_eventId_cancel" value="Cancel" />
			

When a button is pressed Web Flow finds a request parameter name beginning with _eventId_ and treats the remaining substring as the event id. So in this example, submitting _eventId_proceed becomes proceed. This style should be considered when there are several different events that can be signaled from the same form.

The example below shows a form that signals the proceed event when submitted:

<input type="submit" value="Proceed" />
<input type="hidden" name="_eventId" value="proceed" />
			

Here, Web Flow simply detects the special _eventId parameter and uses its value as the event id. This style should only be considered when there is one event that can be signaled on the form.

The example below shows a link that signals the cancel event when activated:

<a href="${flowExecutionUrl}&_eventId=cancel">Cancel</a>
			

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. Recall 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.

By default Web Flow does a client-side redirect upon entering every view state. However if you remain in the same view state -- for example a transition without a "to" attribute -- during an Ajax request there will not be a client-side redirect. This behavior should be quite familiar to Spring Web Flow 2 users. It is appropriate for a top-level flow that supports the browser back button while still taking advantage of Ajax and partial rendering for use cases where you remain in the same view such as form validation, paging trough search results, and others. However transitions to a new view state are always followed with a client-side redirect. That makes it impossible to embed a flow on a page or within a modal dialog and execute more than one view state without causing a full-page refresh. Hence if your use case requires embedding a flow you can launch it in "embedded" mode.

If you'd like to see examples of a flow embedded on a page and within a modal dialog please refer to the webflow-showcase project. You can check out the source code locally, build it as you would a Maven project, and import it into Eclipse:

cd some-directory
svn co https://src.springframework.org/svn/spring-samples/webflow-showcase
cd webflow-showcase
mvn package
# import into Eclipse