<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="upgrade-guide">
	<title>Upgrading from 1.0</title>
	<sect1 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 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 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.
				<ulink url="http://saxon.sourceforge.net/">Saxon 6.5.5</ulink> 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 id="upgrade-guide-definition-language-tool-warnings">
				<title>Flow Definition Updater Tool Warnings</title>
				<sect4 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 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 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 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 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 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 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 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 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-2.5.xsd
           http://www.springframework.org/schema/webflow-config
           http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.0.xsd">
			]]></programlisting>
			<sect3 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 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 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 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 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 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 <ulink url="http://tiles.apache.org/">Apache Tiles</ulink> 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 id="upgrade-guide-webflow-concepts">
		<title>New Web Flow Concepts</title>
		<sect2 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 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 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 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 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>