diff --git a/spring-webflow-reference/src/spring-mvc.xml b/spring-webflow-reference/src/spring-mvc.xml index 5b20b3f7..0b60c252 100644 --- a/spring-webflow-reference/src/spring-mvc.xml +++ b/spring-webflow-reference/src/spring-mvc.xml @@ -12,10 +12,13 @@ Configuring web.xml - The first step to using Spring MVC is to route requests to the DispatcherServlet in the web.xml file. - In this example, we map all URLs that begin with /spring/ to the servlet. - An init-param is used to pass the contextConfigLocation. - This is the location of the Spring configuration for the application. + The first step to using Spring MVC is to configure the DispatcherServlet in web.xml. + You typically do this once per web application. + + + The example below maps all requests that begin with /spring/ to the DispatcherServlet. + An init-param is used to provide the contextConfigLocation. + This is configuration file for the web application. @@ -25,121 +28,207 @@ contextConfigLocation /WEB-INF/web-application-config.xml - 1 Spring MVC Dispatcher Servlet /spring/* - - ]]> +]]> - - Configuring Spring - - URL Mapping - - Inside the DispatcherServlet request need to be mapped with finer grain. - Using a SimpleUrlHandlerMapping, request URLs are mapped to controllers and handlers. - - + + Mapping URLs to Flows + + The DispatcherServlet maps request URLs to handlers. + A simple way to create URL mapping rules is to define a SimpleUrlHandlerMapping: + + - /hotels/*=hotelsController /hotels/booking=bookingFlowHandler - - ]]> +]]> + + + The example above maps the servlet-relative request URL /hotels/booking to the bookingFlowHandler. + + + + Flow Handlers + + A FlowHandler manages executions of a single flow definition. + A FlowHandler is responsible for: + + + + Providing the id of the flow definition to execute + + + Creating the input to pass new flow executions + + + Handling flow execution outcomes + + + Handling flow execution exceptions + + + + These responsibilities are illustrated in the definition of the org.springframework.mvc.servlet.FlowHandler interface: + + +public interface FlowHandler { + public String getFlowId(); + public MutableAttributeMap createExecutionInputMap(HttpServletRequest request); + public String handleExecutionOutcome(String outcome, AttributeMap output, HttpServletRequest request, HttpServletResponse response); + public ModelAndView handleException(FlowException e, HttpServletRequest request, HttpServletResponse response); +} + + + To implement a FlowHandler, subclass AbstractFlowHandler. 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 createExecutionInputMap(HttpServletRequest) when you need fine-grained control over extracting + flow input parameters from the HttpServletRequest. By default, all request parameters are treated as flow input parameters. + + + + + Override handleExecutionOutcome when you need to handle specific flow execution outcomes in a custom manner. + The default behavior sends a redirect to the ended flow's URL to restart a new execution of the flow. + + + + + Override handleException when you need fine-grained control over unhandled flow exceptions. + The default behavior attempts to restart the flow when a client attempts to access an ended or expired flow execution. + Any other exception is rethrown to the Spring MVC ExceptionResolver infrastructure by default. + + + + + Example FlowHandler - In this example both a standard MVC controller and a Web Flow handler are configured. - The hotelsController supports the free navigation aspects of searching and viewing hotels. - The bookingFlowHandler supports the controlled navigation aspect of booking a hotel room. + 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. + An example FlowHandler that redirects to a Spring MVC Controller is shown below: - - - Flow Controllers - - Flow controllers provide a basic hook from Spring MVC into Web Flow. - The FlowController class is an implementation of MVC's Controller interface. - - - - - ]]> - - Web Flow 1.0 used controllers as the only way to hook Web Flow into Spring MVC. - With Web Flow 2.0 flow controllers should be used when the flow is self contained and does not need to interact with the environment. - - - - Flow Adapters - - Flow adapters provide a richer integration point between Spring MVC and Web Flow. - The flow adapter provides hooks into the flow execution that can: - - - select the flow to execute (by default the flow id is inferred from the URL) - - - pass input parameters to the flow on initialization - - - handle the flow execution outcome - - - handle exceptions - - - - - A flow handler should be used whenever integration with any of these hooks is desired. - - - The AbstractFlowHandler class is an implementation of FlowHandler that provides default implementations for these hooks. - - - A common pattern to handle a flow outcome is to redirect to a new page instead of rendering a view in the end-state. - This allows the URL to be refreshed without throwing an exception. - - - ]]> - - - View Resolution +}]]> + - Views in Web Flow 2.0 attempt to automatically resolve unless explicitly specified. - In a Spring MVC environment, a view-state will try to find a JSP view based on the id of the state. - For example, <view-state id="intro"> will resolve to intro.jsp in the same directory as the flow definition. - By specifying the view attribute, a different file name can be selected, however, it must still be a JSP file. + 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. - A custom view resolver is required if different behavior is needed. - To create a custom view resolver the flow-builder-services attribute on flow-registry must define a new webflow:flow-builder-services element with a view-factory-creator. + To use your FlowHandler, first deploy an instance to Spring so it can be mapped to a URL: ]]> + + + Then add the URL mapping rule: + + + + /hotels/booking=bookingFlowHandler + +]]> + + + With this configuration, accessing the URL /hotels/booking will launch the booking flow. + When the booking flow ends, the FlowHandler will process the flow execution outcome and redirect to the appropriate controller. + + + + Registering the FlowHandlerAdapter + + To enable flow handlers, make sure you define the special FlowHandlerAdapter. You only need to do this once. + + + + + +]]> + + + + + Flow Controller + + With the FlowHandler MVC integration approach, you define one handler per flow. + This is overkill in the cases where default flow handling rules are sufficient. + + + For simple cases, consider using the FlowController to map flow requests to a single handler. + You only have to configure this controller once and it will apply the flow handling defaults outlined in the previous section. + Also, you can still override these defaults by configuring the controller's flowHandlers property. + + + Below is a typical FlowController definition: + + + +]]> + + + Below illustrates several URLs mapped to this controller: + + + + + /hotels/booking=flowController + /login=flowController + + +]]> + + + With this configuration, accessing /login launches the login flow. + Accessing /hotels/booking launches the booking flow. + + + + View Resolution + + Web Flow 2 maps selected view identifiers to files located within the flow's working directory unless otherwise specified. + For existing Spring MVC + Web Flow applications, an external ViewResolver is likely already handling this mapping for you. + Therefore, to continue using that resolver and to avoid having to change how your existing flow views are packaged, configure Web Flow as follows: + + ... - - - - ]]> - + + +]]> + - + \ No newline at end of file diff --git a/spring-webflow-reference/src/upgrade-guide.xml b/spring-webflow-reference/src/upgrade-guide.xml index 60f1753c..c980c12b 100644 --- a/spring-webflow-reference/src/upgrade-guide.xml +++ b/spring-webflow-reference/src/upgrade-guide.xml @@ -4,23 +4,23 @@ Introduction - This chapter shows you how to upgrade existing Web Flow 1.0 application to Web Flow 2.0. + This chapter shows you how to upgrade existing Web Flow 1 application to Web Flow 2. Flow Definition Language - The core concepts behind the flow definition language have not changed between Web Flow 1.0 and 2.0. - However, many of the element and attribute names have changed. + The core concepts behind the flow definition language have not changed between Web Flow 1 and 2. + However, some of the element and attribute names have changed. These changes allow for the language to be both more concise and expressive. - A complete mapping of changes is available as an appendix. + A complete list of mapping changes is available as an appendix. Flow Definition Updater Tool - An automated tool is available to aid in the conversion of existing 1.0 flows to the new 2.0 style. + An automated tool is available to aid in the conversion of existing 1.x flows to the new 2.x style. The tool will convert all the old tag names to their new equivalents, if needed. - While the tool will make a best effort attempt at conversion, there is not a one-to-one mapping for all 1.0 concepts. + While the tool will make a best effort attempt at conversion, there is not a one-to-one mapping for all version 1 concepts. If the tool was unable to convert a portion of the flow, it will be marked with a WARNING comment in the resulting flow. @@ -34,7 +34,7 @@ The resulting converted flow will be sent to standard output. -java org.springframework.webflow.engine.model.builder.xml.WebFlowUpgrader flowToUpgrade.xml +java org.springframework.webflow.upgrade.WebFlowUpgrader flow-to-upgrade.xml Flow Definition Updater Tool Warnings @@ -92,14 +92,14 @@ java org.springframework.webflow.engine.model.builder.xml.WebFlowUpgrader flowTo Web Flow Configuration - In Web Flow 1.0 there were two options available for configuring Web Flow, with standard spring bean XML or with the webflow-config schema. - The schema configuration option simplifies the configuration process keeping long internal class name hidden and provides contextual auto-complete. - The schema configuration option is the standard way to configure Web Flow 2.0. + In Web Flow 1 there were two options available for configuring Web Flow, one using standard spring bean XML and the other using the webflow-config-1.0 schema. + The schema configuration option simplifies the configuration process by keeping long internal class names hidden and enabling contextual auto-complete. + The schema configuration option is the only way to configure Web Flow 2. Web Flow Bean Configuration - The bean configuration method used in Web Flow 1.0 is no longer supported. + The FactoryBean bean XML configuration method used in Web Flow 1 is no longer supported. The schema configuration method should be used instead. In particular beans defining FlowExecutorFactoryBean and XmlFlowRegistryFactoryBean should be updated. Continue reading Web Flow Schema Configuration for details. @@ -108,9 +108,9 @@ java org.springframework.webflow.engine.model.builder.xml.WebFlowUpgrader flowTo Web Flow Schema Configuration - The configuration schema has change slightly in 2.0. + The webflow-config configuration schema has also changed slightly from version 1 to 2. The simplest way to update your application is modify the version of the schema to 2.0 then fix any errors in a schema aware XML editor. - The most common change is add 'flow-' to the beginning of elements defined by the schema. + The most common change is add 'flow-' to the beginning of the elements defined by the schema. flow-executor - The flow executor is the core of Web Flow. - This element replaces previous bean definitions for FlowExecutorFactoryBean. + The flow executor is the core Web Flow configuration element. + This element replaces previous FlowExecutorFactoryBean bean definitions. @@ -154,7 +154,7 @@ java org.springframework.webflow.engine.model.builder.xml.WebFlowUpgrader flowTo The flow-registry contains a set of flow-locations. Every flow definition used by Web Flow must be added to the registry. - This element replaces previous bean definitions for XmlFlowRegistryFactoryBean. + This element replaces previous XmlFlowRegistryFactoryBean bean definitions. @@ -170,21 +170,12 @@ java org.springframework.webflow.engine.model.builder.xml.WebFlowUpgrader flowTo The portlet flow controller org.springframework.webflow.executor.mvc.PortletFlowController has been replaced by a flow handler adapter available at org.springframework.webflow.mvc.portlet.FlowHandlerAdapter. They will need to be updated in the bean definitions. - - The flowExecutor can no longer be set via a mutator. - It must be set as a constructor argument. - - - - - ]]> Flow Request URL Handler - The default URL handler has changed in Web Flow 2.0. - The flow identifier is now inferred from the URL rather then passed explicitly. + The default URL handler has changed in Web Flow 2. + The flow identifier is now derived from the URL rather then passed explicitly. In order to maintain comparability with existing views and URL structures a WebFlow1FlowUrlHandler is available. View Resolution - Web Flow 2.0 by default will both select and render views. - View were previously selected by Web Flow 1.0 and then rendered by an external view resolver. + Web Flow 2 by default will both select and render views. + View were previously selected by Web Flow 1 and then rendered by an external view resolver. - In order for 1.0 based flows to work in Web Flow 2.0 the default view resolver must be overridden. + In order for version 1 flows to work in Web Flow 2 the default view resolver must be overridden. A common use case is to use Apache Tiles for view resolution. The following configuration will replace the default view resolver with a Tiles view resolver. The tilesViewResolver in this example can be replaced with any other view resolver. @@ -236,16 +227,17 @@ java org.springframework.webflow.engine.model.builder.xml.WebFlowUpgrader flowTo Automatic Model Binding - Web Flow 1.0 required Spring MVC based flows to manually call FormAction methods, mainly: setupForm, bind and bindAndValidate. - Web Flow 2.0 now supports automatic setup, binding and validation via the model attribute for view-states. + Web Flow 1 required Spring MVC based flows to manually call FormAction methods, notably: + setupForm, bindAndValidate to process form views. + Web Flow 2 now provides automatic model setup and binding using the model attribute for view-states. Please see the Binding to a Model section for details. OGNL vs EL - Web Flow 1.0 used OGNL exclusively for expressions within the flow definitions. - Web Flow 2.0 adds support for Unified EL. + Web Flow 1 used OGNL exclusively for expressions within the flow definitions. + Web Flow 2 adds support for Unified EL. United EL is used when it is available, OGNL will continue to be used when a Unified EL implementation is not available. Please see the Expression Language chapter for details. @@ -253,23 +245,24 @@ java org.springframework.webflow.engine.model.builder.xml.WebFlowUpgrader flowTo Flash Scope - Flash scope in Web Flow 1.0 persisted across the current request and into the next request. - In Web Flow 2.0 flash scope is cleared after every view render. - This allows objects to persist across the POST-REDIRECT-GET pattern, while being independent of the next request. + Flash scope in Web Flow 1 lived across the current request and into the next request. + This was conceptually similar to Web Flow 2's view scope concept, but the semantics were not as well defined. + In Web Flow 2, flash scope is cleared after every view render. + This makes flashScope semantics in Web Flow consistent with other web frameworks. Spring Faces - Web Flow 2.0 provides significant support for JavaServer Faces. + Web Flow 2 offers significantly improved integration with JavaServerFaces. Please see the JSF Integration chapter for details. External Redirects - External redirects in Web Flow 1.0 were always considered context relative. - In Web Flow 2.0, if the redirect URL begins with a slash, it is considered absolute to the server root instead of the application context. + External redirects in Web Flow 1 were always considered context relative. + In Web Flow 2, if the redirect URL begins with a slash, it is considered servlet-relative instead of context-relative. URLs without a leading slash are still context relative.