16. Upgrading from 1.0

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

The conversion tool requires spring-webflow.jar, spring-core.jar and an XSLT 1.0 engine. Saxon 6.5.5 is recommended.

The tool can be run from the command line with the following command. Required libraries must be available on the classpath. The source must be a single flow to convert. The resulting converted flow will be sent to standard output.

java org.springframework.webflow.upgrade.WebFlowUpgrader flow-to-upgrade.xml
			

EL expressions are used heavily throughout the flow definition language. Many of the attributes that appear to be plain text are actually interpreted as EL. The standard EL delimiters (either ${} or #{} in Web Flow 2.0 or just #{} in Web Flow 2.1) are not necessary and will often cause an exception if they are included.

EL delimiters should be removed where necessary by the updater tool.

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.

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 the elements defined by the schema.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:webflow="http://www.springframework.org/schema/webflow-config"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-4.0.xsd
           http://www.springframework.org/schema/webflow-config
           http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.4.xsd">
			

<webflow:flow-executor id="flowExecutor" />
				

<webflow:flow-executor id="flowExecutor" flow-registry="flowRegistry">
    <webflow:flow-execution-listeners>
        <webflow:listener ref="securityFlowExecutionListener"/>
    </webflow:flow-execution-listeners>
</webflow:flow-executor>

<bean id="securityFlowExecutionListener"
      class="org.springframework.webflow.security.SecurityFlowExecutionListener" />
				

<webflow:flow-registry id="flowRegistry">
    <webflow:flow-location path="/WEB-INF/hotels/booking/booking.xml" />
</webflow:flow-registry>
				

The package name for flow controllers has changed from org.springframework.webflow.executor.mvc.FlowController and is now org.springframework.webflow.mvc.servlet.FlowController for Servlet MVC requests. 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 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.

<bean name="/pos.htm" class="org.springframework.webflow.mvc.servlet.FlowController">
    <property name="flowExecutor" ref="flowExecutor" />
    <property name="flowUrlHandler">
        <bean class="org.springframework.webflow.context.servlet.WebFlow1FlowUrlHandler" />
    </property>
</bean>
			

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

<webflow:flow-registry id="flowRegistry" flow-builder-services="flowBuilderServices">
	<web:flow-location path="..." />
    ...
</webflow:flow-registry>

<webflow:flow-builder-services id="flowBuilderServices"
                               view-factory-creator="viewFactoryCreator"/>

<bean id="viewFactoryCreator" class="org.springframework.webflow.mvc.builder.MvcViewFactoryCreator">
    <property name="viewResolvers" ref="tilesViewResolver" />
</bean>

<bean id="tilesViewResolver" class="org.springframework.web.servlet.view.UrlBasedViewResolver">
    <property name="viewClass" value="org.springframework.web.servlet.view.tiles.TilesJstlView" />
</bean>

<bean class="org.springframework.web.servlet.view.tiles.TilesConfigurer">
    <property name="definitions" value="/WEB-INF/tiles-def.xml" />
</bean>
			

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.

Web Flow 1 used OGNL exclusively for expressions within the flow definitions. Web Flow 2 adds support for Unified EL. Web Flow 2.1 uses Spring EL by default. United EL and OGNL can still be plugged in. Please see Chapter 4, Expression Language (EL) for details.

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.

Web Flow 2 offers significantly improved integration with JSF. Please see Chapter 13, JSF Integration for details.

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.