Spring Web Flow Reference Guide

For milestones and snapshots, you need to use the Spring Snapshot repository. Add the following repository to your Maven pom.xml:

Then you need to declare the following dependency:

If the expression returns a value, that value can be saved in the flow’s data model, called flowScope, as follows:

If the expression returns a value that may need to be converted, you can specify the desired type by using the result-type attribute, as follows:

The type attribute declares the input attribute’s type:

If an input value does not match the declared type, a type conversion is attempted.

The value attribute specifies an expression to which to assign the input value, as follows:

If the expression’s value type can be determined, that metadata is used for type coercion if no type attribute is specified.

The required attribute enforces that the input is not null or empty, as follows:

The value attribute denotes a specific output value expression, as follows:

The input element passes input to the subflow, as follows:

When a subflow completes, its end-state ID is returned to the calling flow as the event to use to continue navigation.

The sub-flow can also create output attributes to which the calling flow can refer within an outcome transition, as follows:

In the preceding example, guest is the name of an output attribute returned by the guestCreated outcome.

The first and most common type of expression is the standard expression. Such expressions are evaluated directly by the EL and need not be enclosed in delimiters, such as \#{}. The following example shows such a standard expression:

The preceding expression is a standard expression that invokes the nextPage method on the searchCriteria variable when evaluated. If you try to enclose this expression in a special delimiter (such as \#{}), you get an IllegalArgumentException. In this context, the delimiter is seen as redundant. The only acceptable value for the expression attribute is a single expression string.

The second type of expression is a template expression. A template expression allows mixing of literal text with one or more standard expressions. Each standard expression block is explicitly surrounded with the \#{} delimiters. The following example shows a template expression:

The preceding expression is a template expression. The result of evaluation is a string that concatenates literal text such as error- and .xhtml with the result of evaluating externalContext.locale. You need explicit delimiters here to demarcate standard expression blocks within the template.

Web Flow uses the Spring Expression Language (Spring EL). Spring EL was created to provide a single, well-supported expression language for use across all the products in the Spring portfolio. It is distributed as a separate jar (org.springframework.expression) in the Spring Framework.

Use of the Unified EL also implies a dependency on el-api, although that is typically provided by your web container. Although Spring EL is the default and recommended expression language to use, you can replace it with Unified EL. To do so, you need the following Spring configuration to plug in the WebFlowELExpressionParser to the flow-builder-services:

Note that, if your application registers custom converters, it is important to ensure WebFlowELExpressionParser is configured with the conversion service that has those custom converters, as follows:

You can use the flowScope to assign a flow variable. Flow scope gets allocated when a flow starts and destroyed when the flow ends. With the default implementation, any objects stored in flow scope need to be serializable. The following listing defines a flowScope variable:

You can use the viewScope to assign a view variable. View scope gets allocated when a view-state is entered and destroyed when the state exits. View scope is referenceable only from within a view-state. With the default implementation, any objects stored in view scope need to be serializable. The following listing defines a viewScope variable:

You can use requestScope to assign a request variable. Request scope gets allocated when a flow is called and destroyed when the flow returns. The following listing defines a requestScope variable:

You can use flashScope to assign a flash variable. Flash scope gets allocated when a flow starts, cleared after every view render, and destroyed when the flow ends. With the default implementation, any objects stored in flash scope need to be serializable. The following listing defines a flashScope variable:

You can use conversationScope to assign a conversation variable. Conversation scope gets allocated when a top-level flow starts and destroyed when the top-level flow ends. Conversation scope is shared by a top-level flow and all of its sub-flows. With the default implementation, conversation-scoped objects are stored in the HTTP session and should generally be serializable to account for typical session replication. The following listing defines a conversationScope variable:

The requestParameters variable accesses a client request parameter, as follows:

The currentEvent variable accesses attributes of the current Event, as follows:

The currentUser variable accesses the authenticated Principal, as follows:

The messageContext variable accesses a context to retrieve and create flow execution messages, including error and success messages. See the MessageContext Javadocs for more information. The following example uses the messageContext variable:

The resourceBundle variable accesses a message resource, as follows:

The flowRequestContext variable accesses the RequestContext API, which is a representation of the current flow request. See the API Javadocs for more information.

The flowExecutionContext variable accesses the FlowExecutionContext API, which is a representation of the current flow state. See the API Javadocs for more information.

The flowExecutionUrl variable accesses the context-relative URI for the current flow execution view-state.

The externalContext variable accesses the client environment, including user session attributes. See the ExternalContext API JavaDocs for more information. The following example uses the externalContext variable:

The view ID may be a relative path to view resource in the flow’s working directory, as follows:

The view ID may be a absolute path to a view resource in the webapp root directory, as follows:

With some view frameworks, such as Spring MVC’s view framework, the view ID may also be a logical identifier resolved by the framework, as follows:

See the Spring MVC integration section for more information on how to integrate with the MVC ViewResolver infrastructure.

You can use the var tag to declare a view variable. As with a flow variable, any @Autowired references are automatically restored when the view state resumes. The following listing declares a view variable:

You can use the on-render tag to assign a variable from an action result before the view renders, as follows:

Objects in view scope are often manipulated over a series of requests from the same view. The list is updated in view scope before each rendering. Asynchronous event handlers modify the current data page and then request re-rendering of the search results fragment. The following example pages through a search results list:

Starting with version 2.1, Spring Web Flow uses the type conversion and formatting system for nearly all type conversion needs. Previously, Web Flow applications used a type conversion mechanism that was different from the one in Spring MVC, which relied on the java.beans.PropertyEditor abstraction. Spring’s type conversion was actually influenced by Web Flow’s own type conversion system. Hence, Web Flow users should find it natural to work with Spring type conversion. Another obvious and important benefit of this change is that you can now use a single type conversion mechanism across Spring MVC And Spring Web Flow.

What does this mean, in practical terms, for existing applications? Existing applications are likely registering their own converters of type org.springframework.binding.convert.converters.Converter through a sub-class of DefaultConversionService available in Spring Binding. Those converters can continue to be registered as before. They have been adapted as the Spring GenericConverter types and registered with a Spring org.springframework.core.convert.ConversionService instance. In other words, existing converters are invoked through Spring’s type conversion service.

The only exception to this rule are named converters, which you can reference from a binding element in a view-state, as follows:

Named converters are not supported and cannot be used with the type conversion service available in Spring. Therefore, such converters are not adapted and continue to work as before. That is, they do not involve the Spring type conversion. However, this mechanism is deprecated, and applications are encouraged to favor Spring type conversion and formatting features.

Also note that the existing Spring Binding DefaultConversionService no longer registers any default converters. Instead, Web Flow now relies on the default type converters and formatters in Spring.

In summary, Spring type conversion and formatting is now used almost exclusively in Web Flow. Although existing applications should work without any changes, we encourage moving towards unifying the type conversion needs of Spring MVC and Spring Web Flow parts of applications.

In Spring MVC, an instance of a FormattingConversionService is created automatically through the custom MVC namespace, as follows:

Internally, that is done with the help of FormattingConversionServiceFactoryBean, which registers a default set of converters and formatters. You can customize the conversion service instance used in Spring MVC through the conversion-service attribute, as follows:

In Web Flow, an instance of a Spring Binding DefaultConversionService, which does not register any converters, is automatically created. Instead, it delegates to a FormattingConversionService instance for all type conversion needs. By default, this is not the same FormattingConversionService instance as the one used in Spring. However, that does not make a practical difference until you start registering your own formatters.

You can customize the DefaultConversionService used in Web Flow through the flow-builder-services element, as follows:

You can do the following to register your own formatters for use in both Spring MVC and in Spring Web Flow :

You can also mix and match. You can register new Spring Formatter types through the applicationConversionService. You can register existing Spring Binding Converter types through the defaultConversionService.

`` An important concept to understand is the difference between type converters and formatters.

Type converters in Spring, provided in org.springframework.core, are for general-purpose type conversion between any two object types. In addition to the most simple Converter type, two other interfaces are ConverterFactory and GenericConverter.

Formatters in Spring, provided in org.springframework.context, have the more specialized purpose of representing Object instances as String instances. The Formatter interface extends the Printer and Parser interfaces for converting an Object to a String and turning a String into an Object.

Web developers may find the Formatter interface to be most relevant, because it fits the needs of web applications for type conversion.

One of the best features of the type conversion is the ability to use annotations for better control over formatting in a concise manner. You can place annotations on model attributes and on the arguments of @Controller methods that are mapped to requests. Spring provides two annotations (@NumberFormat and @DateTimeFormat), but you can create your own and have them be registered, along with the associated formatting logic.

The @DateTimeFormat annotation implies use of Joda Time. If that is present on the classpath, the use of this annotation is enabled automatically. By default, neither Spring MVC nor Web Flow register any other date formatters or converters. Therefore, it is important for applications to register a custom formatter to specify the default way for printing and parsing dates. The @DateTimeFormat annotation, on the other hand, provides more fine-grained control where it is necessary to deviate from the default.

For more information on working with Spring type conversion and formatting, see the relevant sections of the Spring documentation.

Web Flow provides built-in support for the JSR-303 Bean Validation API, building on the equivalent support available in Spring MVC. To enable JSR-303 validation, configure the flow-builder-services with Spring MVC’s LocalValidatorFactoryBean, as follows:

With the preceding example in place, the configured validator is applied to all model attributes after data binding.

Note that JSR-303 bean validation and validation by convention (explained in the next section) are not mutually exclusive. In other words, Web Flow applies all available validation mechanisms.

There are two ways to perform model validation programatically. The first is to implement validation logic in your model object. The second is to implement an external Validator. Both ways provide you with a ValidationContext to record error messages and access information about the current user.

A ValidationContext lets you obtain a MessageContext to record messages during validation. It also exposes information about the current user, such as the signaled userEvent and the current user’s Principal identity. You can use this information to customize validation logic based on what button or link was activated in the UI or who is authenticated. See the API Javadoc for ValidationContext for more information.

A view-state transition can invoke one or more actions before running. These actions may return an error result to prevent the transition from exiting the current view-state. If an error result occurs, the view re-renders and should display an appropriate message to the user.

If the transition action invokes a plain Java method, the invoked method may return a boolean, whose value (true or false) indicates whether the transition should take place or be prevented from running. A method can also return a String where literal values of success, yes, or true indicate the transition should occur, and any other value means the opposite. You can use this technique to handle exceptions thrown by service-layer methods. The following example invokes an action that calls a service and handles an exceptional situation:

When there is more than one action defined on a transition, if one returns an error result, the remaining actions in the set are not executed. If you need to ensure one transition action’s result cannot impact the execution of another, define a single transition action that invokes a method that encapsulates all the action logic.

You can use the flow’s global-transitions element to create transitions that apply across all views. Global transitions are often used to handle global menu links that are part of the layout. The following example defines a global-transition element:

From a view-state, you can also define transitions without targets. Such transitions are called “event handlers”. The following example defines such a transition:

These event handlers do not change the state of the flow. They execute their actions and re-render the current view or one or more fragments of the current view.

You can use the render element within a transition to request partial re-rendering of the current view after handling the event, as follows:

The fragments attribute should reference the IDs of the view elements you wish to re-render. You can specify multiple elements to re-render by separating them with a comma delimiter.

Such partial rendering is often used with events signaled by Ajax to update a specific zone of the view.

You can add plain text messages to the context. The following example shows how to do so:

You can add internationalized (that is, localized) messages to the context. The following example shows how to do so:

Internationalized messages are defined in message bundles accessed by a Spring MessageSource. To create a flow-specific message bundle, define messages.properties files in your flow’s directory. Create a default messages.properties file and a .properties file for each additional Locale you need to support. The following example defines a few messages:

From within a view or a flow, you may also access message resources by using the resourceBundle EL variable, as follows:

There are several places where Web Flow itself generates messages to display to the user. One important place this occurs is during view-to-model data binding. When a binding error (such as a type conversion error) occurs, Web Flow maps that error to a message that is automatically retrieved from your resource bundle. To look up the message to display, Web Flow tries resource keys that contain the binding error code and the target property name.

As an example, consider a binding to the checkinDate property of a Booking object. Suppose the user typed in an alphabetic string. In this case, a type conversion error is raised. Web Flow maps the typeMismatch error code to a message by first querying your resource bundle for a message with the following key:

The first part of the key is the model class’s short name. The second part of the key is the property name. The third part is the error code. This allows for the lookup of a unique message to display to the user when a binding fails on a model property. Such a message might say:

If no such resource key of that form can be found, a more generic key is tried. This key is the error code. The field name of the property is provided as a message argument, as follows:

You can set the history attribute to discard to prevent backtracking to a view, as follows:

You can set the history attribute to invalidate to prevent backtracking to a view as well as all previously displayed views, as follows:

The following example shows how to invoke a POJO action:

The following example shows how to invoke a custom action implementation:

The following example shows how to invoke a MultiAction implementation:

The following example invokes an action that catches a business exception, adds an error message to the context, and returns a result event identifier. The result is treated as a flow event to which the calling flow can then respond.

The following example is functionally equivalent to the example in the previous section but is implemented as a MultiAction instead of a POJO action. The MultiAction requires its action methods to be of the signature Event ${methodName}(RequestContext), providing stronger type safety, while a POJO action allows for more freedom.

In general, you should catch exceptions in actions and return result events that drive standard transitions. You can also add an exception-handler sub-element to any state type with a bean attribute that references a bean of type FlowExecutionExceptionHandler. This is an advanced option that, if used incorrectly, can leave the flow execution in an invalid state. Consider the built-in TransitionExecutingFlowExecutionExceptionHandler as an example of a correct implementation.

The following example shows an action that creates a new Booking object by invoking a method on a service:

The following example shows a state entry action that sets the special fragments variable that causes the view-state to render a partial fragment of its view:

The following example shows a state exit action that releases a lock on a record being edited:

The following example shows object locking behavior that is equivalent to the example in the preceding section but uses flow start and end actions:

The following example shows a render action that loads a list of hotels to display before the view is rendered:

The following example shows a transition action that adds a sub-flow outcome event attribute to a collection:

The following example shows how to execute a chain of actions in an action-state. The name of each action becomes a qualifier for the action’s result event.

In this example, the flow transitions to showResults when thingTwo completes successfully.

Sometimes, an action needs to stream a custom response back to the client. An example might be a flow that renders a PDF document when handling a print event. This can be achieved by having the action stream the content and then record a status of Response Complete status on the ExternalContext. The responseComplete flag tells the pausing view-state not to render the response because another object has taken care of it. The following action shows such an action:

In this example, when the print event is raised, the flow calls the printBoardingPassAction method. The action renders the PDF and then marks the response as complete.

Another common task is to use Web Flow to handle multipart file uploads in combination with Spring MVC’s MultipartResolver. Once the resolver is set up correctly, as described here, and the submitting HTML form is configured with enctype="multipart/form-data", you can handle the file upload in a transition action.

Consider the form in the following listing:

Then consider the backing object for handling the upload:

You can process the upload by using a transition action, as follows:

The MultipartFile is bound to the FileUploadHandler bean as part of the normal form-binding process so that it is available to process during the execution of the transition action.

The value of attributes is a comma separated list of Spring Security authorization attributes. Often, these are specific security roles. The attributes are compared against the user’s granted attributes by a Spring Security access decision manager.

By default, an authority-based AuthorizationManager is used to determine if the user is allowed access. This needs to be overridden if your application is not using authorization roles.

There are two types of matching available: any and all. any allows access if at least one of the required security attributes is granted to the user. all allows access only if each of the required security attributes is granted to the user.

This attribute is optional. If not defined, the default value is any.

The match attribute is respected only if the default access decision manager is used.

If your application uses authorities that are not role-based, you need to configure a custom AuthorizaitonManager. You can override the AuthorityAuthorizationManager used by default through the authorizationManagerInitializer property on the security listener. For example:

Spring Security’s AccessDecisionManager is deprecated and will be removed in a future version. Therefore, it is recommended to configure an AuthorizationManager instead. However, if you must use an AccessDecisionManager, you can either set the accessDecisionManager property of the security listener, or override the createAccessDecisionManager(SecurityRule) protected method.

To learn more about Spring Security’s AuthorizationManager API, see Spring Security reference documentation.

The Spring configuration defines http specifics (such as protected URLs and login/logout mechanics) and the authentication-provider. For the sample applications, a local authentication provider is configured. The following example configures Spring Security for a web flow:

In the web.xml file, a filter is defined to intercept all requests. This filter listens for login and logout requests and processes them accordingly. It also catches AccesDeniedException instances and redirects the user to the login page. The following example defines such filters:

Flow level inheritance is defined by the parent attribute on the flow element. The attribute contains a comma-separated list of flow identifiers from which to inherit. The child flow inherits from each parent in the order it is listed, adding elements and content to the resulting flow. The resulting flow from the first merge is considered the child in the second merge, and so on.

If the elements are of the same type and their keyed attribute is identical, the content of the parent element is merged with the child element. The merge algorithm continues to merge each sub-element of the merging parent and child. Otherwise, the parent element is added as a new element to the child.

In most cases, the added elements from a parent flow are added after elements in the child flow. Exceptions to this rule include action elements (evaluate, render, and set) that are added at the beginning. This allows for the results of parent actions to be used by child actions.

The mergeable elements are:

The non-mergeable elements are:

You can register your flows in a FlowRegistry in XML, as follows:

You can register your flows in a FlowRegistry in Java, as follows:

You can deploy a FlowExecutor, the central service for executing flows in XML, as follows:

You can deploy a FlowExecutor, the central service for executing flows in Java:

See the Spring MVC Integration and JSF Integration sections of this guide on how to integrate the Web Flow system with the MVC and JSF environment, respectively.

You can use the location element to specify paths to flow definitions that you want to register. By default, flows are assigned registry identifiers equal to their filenames minus the file extension, unless a registry base path is defined (see Flow Location Base Path).

The following example specifies a flow location in XML:

The following example specifies a flow location in Java:

You can specify an ID to assign a custom registry identifier to a flow.

The following example shows how to assign custom flow identifiers in XML:

The following example shows how to assign custom flow identifiers in Java:

You can use the flow-definition-attributes element to assign custom meta-attributes to a registered flow.

The following example shows how to assign flow meta-attributes in XML:

The following example shows how to assign flow meta-attributes in Java:

You can use the flow-location-patterns element to register flows that match a specific resource location pattern.

The following example shows how to register a flow in XML:

The following example shows how to register a flow in Java:

You can use the base-path attribute to define a base location for all flows in the application. All flow locations are then relative to the base path. The base path can be a resource path (such as /WEB-INF) or a location on the classpath (such as classpath:org/springframework/webflow/samples).

The following example shows how to set the base path in XML:

The following example shows how to set the base path in Java:

With a base path defined, the algorithm that assigns flow identifiers changes slightly. Flows are now assigned registry identifiers equal to the the path segment between their base path and their file name. For example, if a flow definition is located at /WEB-INF/hotels/booking/booking-flow.xml and the base path is /WEB-INF, the remaining path to this flow is hotels/booking, which becomes the flow ID.

If no base path is not specified or if the flow definition is directly on the base path, flow ID assignment from the filename (minus the extension) is used. For example, if a flow definition file is booking.xml, the flow identifier is simply booking.

Location patterns are particularly powerful when combined with a registry base path. Instead of the flow identifiers becoming *-flow, they are based on the directory path. The following example combines a base path with a flow location pattern in XML:

The following example combines a base path with a flow location pattern in Java:

In the preceding example, suppose you had flows located in the /user/login, /user/registration, /hotels/booking, and /flights/booking directories within WEB-INF. You would end up with flow IDs of user/login, user/registration, hotels/booking, and flights/booking, respectively.

You can use the parent attribute to link two flow registries together in a hierarchy. When the child registry is queried, if it cannot find the requested flow, it delegates to its parent.

The following example establishes a parent relationship for two flow registries in XML:

The following example establishes a parent relationship for two flow registries in Java:

You can use the flow-builder-services attribute (in XML) or the FlowBuilderServices object (in Java) to customize the services and settings used to build flows in a flow-registry. If no flow-builder-services element is specified, the default service implementations are used. When the element is specified, you need only reference the services you want to customize.

The following example shows how to create a custom flow builder service in XML:

The following example shows how to create a custom flow builder service in Java:

The configurable services are the conversion-service, expression-parser, and view-factory-creator elements (in XML) and the ConversionService, ExpressionParser, and ViewFactoryCreator interfaces (in Java). These services are configured by referencing custom beans that you must define.

The following example shows how to define the configurable services in XML:

The following example shows how to define the configurable services in Java:

You can use the flow-execution-listeners element (in XML) or the addFlowExecutionListener method (in Java) to register listeners that observe the lifecycle of flow executions.

The following example shows how to create flow execution listeners in XML:

The folloiwng example shows how to create flow execution listeners in Java:

You can also configure a listener to observe only certain flows.

The following example shows how to configure a listener to monitor only two flows in XML:

The following example shows how to configure a listener to monitor only two flows in Java:

You can use the flow-execution-repository element (in XML) or the FlowExecutor interface (in Java) to tune flow execution persistence settings.

The following example tunes flow execution in XML:

The following example tunes flow execution in Java:

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

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, as follows:

Configuring this mapping lets the Dispatcher map application resource paths to flows in a flow registry. For example, accessing the /hotels/booking resource path would result in a registry query for the flow with an ID of hotels/booking. If a flow with that ID is found, that flow handles the request. If no flow is found, the next handler mapping in the dispatcher’s ordered chain is queried or a noHandlerFound response is 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. The adapter employs a number of defaults related to starting and resuming flow executions:

See the API documentation for FlowHandlerAdapter for more information. You may override these defaults by subclassing or by implementing your own FlowHandler, as 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. FlowHandler instances let this be done without coupling the flow definition itself with a specific controller URL. The following example FlowHandler redirects to a Spring MVC Controller:

Since this handler needs only to handle flow invocation outcomes in a custom manner, nothing else is overridden. The bookingConfirmed outcome results in a redirect to show the new booking. Any other outcome redirects back to the hotel’s index page.

To install a custom FlowHandler, you need to deploy it as a bean. The bean name must match the ID of the flow to which the handler should apply. The following example creates a bean that matches the hotels/booking flow:

With this configuration, accessing the resource /hotels/booking launches the hotels/booking flow by using the custom BookingFlowHandler. When the booking flow ends, the FlowHandler processes the flow execution outcome and redirects to the appropriate controller.

A FlowHandler that handles a FlowExecutionOutcome or FlowException returns a String to indicate the resource to which to redirect after handling. In the example shown in the previous section, the BookingFlowHandler redirects to the booking/show resource URI for bookingConfirmed outcomes and to 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 by 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 you use the externalRedirect: directive in conjunction with a view-state or an end-state — for example, view="externalRedirect:https://springframework.org".

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

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 following example shows a form that signals the proceed event when submitted:

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

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

Firing an event results in an 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 that a Spring MVC view implementation looks for a request parameter named _eventId. If no \_eventId parameter is found, the view looks for a parameter that starts with \_eventId_ and uses the remaining substring as the event ID. If neither case exists, 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 is no client-side redirect. 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.

For examples of a flow embedded on a page and within a modal dialog, see 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, as follows:

The key interface for integrating various Ajax libraries with the Ajax-aware behavior of Web Flow (such as not redirecting for a partial page update) is org.springframework.js.AjaxHandler. By default, a SpringJavascriptAjaxHandler is configured. It can detect an Ajax request submitted through the Spring JS client-side API and can respond appropriately when a redirect is required. To integrate a different Ajax library (be it a pure JavaScript library or a higher-level abstraction, such as an Ajax-capable JSF component library), you can inject a custom AjaxHandler into the FlowHandlerAdapter or FlowController.

To handle Ajax requests with Spring MVC controllers, you need to configure the provided Spring MVC extensions in your Spring application context for rendering the partial response (note that these extensions require the use of tiles for templating), as follows:

This configures the AjaxUrlBasedViewResolver, which, in turn, interprets Ajax requests and creates FlowAjaxTilesView objects to handle rendering of the appropriate fragments. Note that FlowAjaxTilesView is capable of handling the rendering for both Web Flow and pure Spring MVC requests. The fragments correspond to individual attributes of a tiles view definition. For example, consider the following tiles view definition:

An Ajax request could specify the body, hotelSearchForm or bookingsTable to be rendered as fragments in the request.

Spring Web Flow handles the optional rendering of fragments directly in the flow definition language through the use of the render element. The benefit of this approach is that the selection of fragments is completely decoupled from client-side code, such that no special parameters need to be passed with the request the way they currently must be with the pure Spring MVC controller approach. For example, if you wanted to render the hotelSearchForm fragment from the previous example tiles view into a rich Javascript popup, you could define the following view-state:

The easiest and most natural way to declare and manage the model is through the use of flow variables. You can declare these variables at the beginning of the flow, as follows:

You can then reference this variable in one of the flow’s JSF view templates through EL, as follows:

Note that you do not need to prefix the variable with its scope when referencing it from the template (though you can do so if you need to be more specific). As with standard JSF beans, all available scopes are searched for a matching variable, so you could change the scope of the variable in your flow definition without having to modify the EL expressions that reference it.

You can also define view instance variables that are scoped to the current view and that automatically get cleaned up upon transitioning to another view. This is quite useful with JSF, as views are often constructed to handle multiple in-page events across many requests before transitioning to another view.

To define a view instance variable, you can use the var element inside a view-state definition, as follows:

Though defining autowired flow instance variables provides nice modularization and readability, occasions may arise where you want to use the other capabilities of the Spring container, such as Aspect-oriented Programming (AOP). In these cases, you can define a bean in your Spring ApplicationContext and give it a specific web flow scope, as follows:

The major difference with this approach is that the bean is not fully initialized until it is first accessed through an EL expression. This sort of lazy instantiation through EL is quite similar to how JSF-managed beans are typically allocated.

The need to initialize the model before view rendering (such as by loading persistent entities from a database) is quite common, but JSF itself does not provide any convenient hooks for such initialization. The flow definition language provides a natural facility for this through its actions . Spring Web Flow provides some extra conveniences for converting the outcome of an action into a JSF-specific data structure. The following example shows how to do so:

The preceding example takes the result of the bookingService.findBookings method and wraps it in a custom JSF DataModel so that the list can be used in a standard JSF DataTable component, as follows:

In the example shown in the preceding section, result-type="dataModel" results in the wrapping of List<Booking> with a custom DataModel type. The custom DataModel provides extra conveniences, such as being serializable for storage beyond request scope as well as access to the currently selected row in EL expressions. For example, on postback from a view where the action event was fired by a component within a DataTable, you can take action on the selected row’s model instance, as follows:

Spring Web Flow provides two custom DataModel types: OneSelectionTrackingListDataModel and ManySelectionTrackingListDataModel. As the names indicate, they keep track of one or multiple selected rows. This is done with the help of a SelectionTrackingActionListener listener, which responds to JSF action events and invokes the appropriate methods on the SelectionAware data models to record the currently clicked row.

To understand how this is configured, keep in mind that the FacesConversionService registers a DataModelConverter against the alias dataModel on startup. When result-type="dataModel" is used in a flow definition, it causes the DataModelConverter to be used. The converter then wraps the given List with an instance of OneSelectionTrackingListDataModel. To use the ManySelectionTrackingListDataModel, you need to register your own custom converter.

A simple but common case in JSF is the need to signal an event that causes manipulation of the model in some way and then redisplays the same view to reflect the changed state of the model. The flow definition language has special support for this in the transition element.

A good example of this is a table of paged list results. Suppose you want to be able to load and display only a portion of a large result list and let the user page through the results. The initial view-state definition to load and display the list would be as follows:

You can construct a JSF DataTable that displays the current hotels list and then place a More Results link below the table, as follows:

This commandLink signals a next event from its action attribute. You can then handle the event by adding to the view-state definition, as follows:

Here, you handle the next event by incrementing the page count on the searchCriteria instance. The on-render action is then called again with the updated criteria, which causes the next page of results to be loaded into the DataModel. The same view is re-rendered, since there was no to attribute on the transition element, and the changes in the model are reflected in the view.

The next logical level beyond in-page events are events that require navigation to another view, with some manipulation of the model along the way. Achieving this with pure JSF would require adding a navigation rule to faces-config.xml and likely some intermediary Java code in a JSF managed bean (both tasks requiring a re-deploy). With the flow definition language, you can handle such a case concisely in one place in a way similar to how in-page events are handled.

Continuing with our use case of manipulating a paged list of results, suppose we want each row in the displayed DataTable to contain a link to a detail page for that row instance. You can add a column to the table containing the following commandLink component, as follows:

This raises the select event, which you can then handle by adding another transition element to the existing view-state, as follows:

Here, the select event is handled by pushing the currently selected hotel instance from the DataTable into flow scope so that it may be referenced by the reviewHotel view-state .

JSF provides useful facilities for validating input at field-level before changes are applied to the model. However, when you need to then perform more complex validation at the model-level after the updates have been applied, you are generally left with having to add more custom code to your JSF action methods in the managed bean. Validation of this sort is something that is generally a responsibility of the domain model itself, but it is difficult to get any error messages propagated back to the view without introducing an undesirable dependency on the JSF API in your domain layer.

With Web Flow, you can use the generic and low-level MessageContext in your business code, and any messages added there are then available to the FacesContext at render time.

For example, suppose you have a view where the user enters the necessary details to complete a hotel booking, and you need to ensure the Check In and Check Out dates adhere to a given set of business rules. You can invoke such model-level validation from a transition element, as follows:

Here, the proceed event is handled by invoking a model-level validation method on the booking instance, passing the generic MessageContext instance so that messages may be recorded. The messages can then be displayed along with any other JSF messages in the h:messages component.

JSF provides built-in support for sending Ajax requests and performing partial processing and rendering on the server-side. You can specify a list of IDs for partial rendering through the <f:ajax> facelets tag.

In Spring Web Flow, you also have the option to specify the IDs to use for partial rendering on the server side with the render action, as follows: