279 lines
13 KiB
XML
279 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter xml:id="upgrade-guide"
|
|
xmlns="http://docbook.org/ns/docbook" version="5.0"
|
|
xmlns:xl="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="
|
|
http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
|
|
http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">
|
|
<title>Upgrading from 1.0</title>
|
|
<sect1 xml:id="upgrade-guide-introduction">
|
|
<title>Introduction</title>
|
|
<para>
|
|
This chapter shows you how to upgrade existing Web Flow 1 application to Web Flow 2.
|
|
</para>
|
|
</sect1>
|
|
<sect1 xml:id="upgrade-guide-definition-language">
|
|
<title>Flow Definition Language</title>
|
|
<para>
|
|
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 list of <link linkend="field-mappings">mapping changes</link> is available as an appendix.
|
|
</para>
|
|
<sect2 xml:id="upgrade-guide-definition-language-tool">
|
|
<title>Flow Definition Updater Tool</title>
|
|
<para>
|
|
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 <code>WARNING</code> comment in the resulting flow.
|
|
</para>
|
|
<para>
|
|
The conversion tool requires spring-webflow.jar, spring-core.jar and an XSLT 1.0 engine.
|
|
<link xl:href="http://saxon.sourceforge.net/">Saxon 6.5.5</link> is recommended.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<programlisting>
|
|
java org.springframework.webflow.upgrade.WebFlowUpgrader flow-to-upgrade.xml
|
|
</programlisting>
|
|
<sect3 xml:id="upgrade-guide-definition-language-tool-warnings">
|
|
<title>Flow Definition Updater Tool Warnings</title>
|
|
<sect4 xml:id="upgrade-guide-definition-language-tool-warnings-argument-parameter-type">
|
|
<title>argument parameter-type no longer supported</title>
|
|
<para>
|
|
Bean actions have been deprecated in favor of EL based evaluate expressions.
|
|
The EL expression is able to accept method parameters directly, so there is no longer a need for the argument tag.
|
|
A side effect of this change is that method arguments must be of the correct type before invoking the action.
|
|
</para>
|
|
</sect4>
|
|
<sect4 xml:id="upgrade-guide-definition-language-tool-warnings-inline-flow">
|
|
<title>inline-flow is no longer supported</title>
|
|
<para>
|
|
Inline flows are no longer supported.
|
|
The contents of the inline flow must be moved into a new top-level flow.
|
|
The inline flow's content has been converted for your convenience.
|
|
</para>
|
|
</sect4>
|
|
<sect4 xml:id="upgrade-guide-definition-language-tool-warnings-mapping-target-collection">
|
|
<title>mapping target-collection is no longer supported</title>
|
|
<para>
|
|
Output mappings can no longer add an item to a collection.
|
|
Only assignment is supported.
|
|
</para>
|
|
</sect4>
|
|
<sect4 xml:id="upgrade-guide-definition-language-tool-warnings-var-bean">
|
|
<title>var bean is no longer supported</title>
|
|
<para>
|
|
The var bean attribute is no longer needed.
|
|
All spring beans can be resolved via EL.
|
|
</para>
|
|
</sect4>
|
|
<sect4 xml:id="upgrade-guide-definition-language-tool-warnings-var-scope">
|
|
<title>var scope is no longer supported</title>
|
|
<para>
|
|
The var element will place all variable into flow scope.
|
|
Conversation scope was previously allowed.
|
|
</para>
|
|
</sect4>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-definition-language-el">
|
|
<title>EL Expressions</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
EL delimiters should be removed where necessary by the updater tool.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 xml:id="upgrade-guide-webflow-config">
|
|
<title>Web Flow Configuration</title>
|
|
<para>
|
|
In Web Flow 1 there were two options available for configuring Web Flow, one using standard spring bean XML and the other using the <code>webflow-config-1.0</code> 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.
|
|
</para>
|
|
<sect2 xml:id="upgrade-guide-webflow-config-beans">
|
|
<title>Web Flow Bean Configuration</title>
|
|
<para>
|
|
The <code>FactoryBean</code> 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 <code>FlowExecutorFactoryBean</code> and <code>XmlFlowRegistryFactoryBean</code> should be updated.
|
|
Continue reading Web Flow Schema Configuration for details.
|
|
</para>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-webflow-config-schema">
|
|
<title>Web Flow Schema Configuration</title>
|
|
<para>
|
|
The <code>webflow-config</code> 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.
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<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">
|
|
]]></programlisting>
|
|
<sect3 xml:id="upgrade-guide-webflow-config-schema-executor">
|
|
<title>flow-executor</title>
|
|
<para>
|
|
The flow executor is the core Web Flow configuration element.
|
|
This element replaces previous <code>FlowExecutorFactoryBean</code> bean definitions.
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<webflow:flow-executor id="flowExecutor" />
|
|
]]></programlisting>
|
|
</sect3>
|
|
<sect3 xml:id="upgrade-guide-webflow-config-schema-listeners">
|
|
<title>flow-execution-listeners</title>
|
|
<para>
|
|
Flow execution listeners are also defined in the flow executor.
|
|
Listeners are defined using standard bean definitions and added by reference.
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<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" />
|
|
]]></programlisting>
|
|
</sect3>
|
|
<sect3 xml:id="upgrade-guide-webflow-config-schema-registry">
|
|
<title>flow-registry</title>
|
|
<para>
|
|
The <code>flow-registry</code> contains a set of <code>flow-location</code>s.
|
|
Every flow definition used by Web Flow must be added to the registry.
|
|
This element replaces previous <code>XmlFlowRegistryFactoryBean</code> bean definitions.
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<webflow:flow-registry id="flowRegistry">
|
|
<webflow:flow-location path="/WEB-INF/hotels/booking/booking.xml" />
|
|
</webflow:flow-registry>
|
|
]]></programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-java-controller">
|
|
<title>Flow Controller</title>
|
|
<para>
|
|
The package name for flow controllers has changed from <code>org.springframework.webflow.executor.mvc.FlowController</code> and is now <code>org.springframework.webflow.mvc.servlet.FlowController</code> for Servlet MVC requests.
|
|
The portlet flow controller <code>org.springframework.webflow.executor.mvc.PortletFlowController</code> has been replaced by a flow handler adapter available at <code>org.springframework.webflow.mvc.portlet.FlowHandlerAdapter</code>.
|
|
They will need to be updated in the bean definitions.
|
|
</para>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-java-url-handler">
|
|
<title>Flow URL Handler</title>
|
|
<para>
|
|
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 <code>WebFlow1FlowUrlHandler</code> is available.
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<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>
|
|
]]></programlisting>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-webflow-config-view-resolver">
|
|
<title>View Resolution</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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 <link xl:href="http://tiles.apache.org/">Apache Tiles</link> for view resolution.
|
|
The following configuration will replace the default view resolver with a Tiles view resolver.
|
|
The <code>tilesViewResolver</code> in this example can be replaced with any other view resolver.
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<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>
|
|
]]></programlisting>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 xml:id="upgrade-guide-webflow-concepts">
|
|
<title>New Web Flow Concepts</title>
|
|
<sect2 xml:id="upgrade-guide-webflow-concepts-binding">
|
|
<title>Automatic Model Binding</title>
|
|
<para>
|
|
Web Flow 1 required Spring MVC based flows to manually call <code>FormAction</code> methods, notably:
|
|
<code>setupForm</code>, <code>bindAndValidate</code> to process form views.
|
|
Web Flow 2 now provides automatic model setup and binding using the <code>model</code> attribute for <code>view-state</code>s.
|
|
Please see the <link linkend="view-model">Binding to a Model</link> section for details.
|
|
</para>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-webflow-concepts-el-v-ognl">
|
|
<title>OGNL vs Spring EL</title>
|
|
<para>
|
|
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 <xref linkend="el"/> for details.
|
|
</para>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-webflow-concepts-flash-scope">
|
|
<title>Flash Scope</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-webflow-concepts-jsf">
|
|
<title>JSF</title>
|
|
<para>
|
|
Web Flow 2 offers significantly improved integration with JSF.
|
|
Please see <xref linkend="spring-faces"/> for details.
|
|
</para>
|
|
</sect2>
|
|
<sect2 xml:id="upgrade-guide-webflow-concepts-redirects">
|
|
<title>External Redirects</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|