<?xml version="1.0" standalone="no"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>

<chapter id="migration">
   <title>Migrating from Seam 1.2 to Seam 2</title>
   
   <para>
      There are two approaches to migrating your Seam 1.2 application to Seam 2.
      The recommended approach, described in <xref linkend="migrating.skeleton"/>
      is to create a new project using seam-gen in Seam 2, and migrate your code
      across. We recognize that many projects may have extensive customizations
      to their project, so we also provide instructions for how to upgrade your
      project in-situ in <xref linkend="migrating.insitu" /> Due to the number 
      of changes introduced between Seam 1.2 and Seam 2, this may not always be 
      a straightforward process! 
   </para>
   
   <para>
      However you decide to migrate your application, you'll need to alter your
      code, as many components have moved. <xref linkend="migrating.general"/>
      details those changes.
   </para>
   
   <section id="migrating.skeleton">
      <title>Creating a new project skeleton using seam-gen</title>
      
      <para>
         Start by creating a new skeleton seam project. In your Seam 2
         directory run:
      </para>
      
      <programlisting>~/seam_2_0$ ./seam setup</programlisting>
      
      <para>
         Customize the defaults as needed. You'll want to set the location of 
         JBoss EAP, name your project and select an EAR or WAR as needed; you 
         can accept the defaults for Java package names (as we aren't going to
         use the reverse engineering features of seam-gen); you'll want to set
         your JDBC driver, URL, username and password correctly, and configure
         Hibernate to drop and recreate tables if so desired.
      </para>
      
      <para>
         Now, we are ready to import your existing code and views into the new 
         structure. The simplest way to do this is to import both projects 
         into your favorite IDE, and copy your code and views across. 
      </para>
      
      <para>
         Continue on to <xref linkend="migrating.general"/> for details regarding
         the changes needed to your code, and configuration files.
      </para>
      
   </section>
   
   <section id="migrating.insitu">
      <title>In place migration</title>
      
      <para>
         This requires more work, but is suitable for more complex projects. The
         steps below may not be an exhaustive list, so if you have to any extra
         steps please report them through the Customer Support Portal.
      </para>
      
      <section>
         <title>Migrating to JSF 1.2</title>
         
         <warning>
            <para>
               You only need to do this if you are migrating from the community
               edition of Seam, JBoss EAP 4.2 and 4.3 shipped a version of Seam
               1.2 which used JSF 1.2.
            </para>
         </warning>
         
         <para>
            Seam 2.0 requires JSF 1.2, and JBoss EAP supports Sun's JSF RI. To 
            switch to JSF 1.2, you need to remove the MyFaces listener:
         </para>
         
         <programlisting role="XML"><![CDATA[<!--Remove for Seam 2-->
<!--<listener>
   <listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class>
</listener>-->]]></programlisting>
         
         <para>
            from your <literal>web.xml</literal>.
         </para>
         
         <para>The JSF RI doesn't require you to specify a listener.</para>
         
         <note>
            <para>
               Due to an incompatibility between Seam and MyFaces, you had to
               use client side state saving in Seam 1.2. Switching to the JSF RI
               1.2 lifts this restriction. So remove the context param javax.faces.STATE_SAVING_METHOD.
            </para> 
         </note>
      </section>
      
      <section>
         <title>Migrating <literal>web.xml</literal> to Seam 2</title>
         
		<para>
			First change the <literal>web-app</literal> version from 2.4 to 2.5.
            There is also change in j2ee to javaee in namespace URL. Declaration of the <literal>web.xml</literal>
            should look like:</para>
            
<programlisting role="XML"><![CDATA[<web-app xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
    http://java.sun.com/xml/ns/javaee
    http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" 
  version="2.5">
  ...
</web-app>]]></programlisting> 
         
         <para>
            In your Seam 1.2 app you may have specified some Seam specific 
            configuration in <literal>web.xml</literal>.  First, we'll discuss
            all the Seam related elements you need in 
            <literal>web.xml</literal>, not just those that have changed, noting
            any changes.
         </para>
         
         <para>
             In Seam 2, you need specify a listener (just as you did in Seam 
             1.2):
         </para>
         
         <programlisting role="XML"><![CDATA[<listener>
   <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
</listener>]]></programlisting>

         <para>
            Modify the Seam master filter (note the package of the class 
            changed):
         </para>
         
         <programlisting role="XML"><![CDATA[<filter>
   <filter-name>Seam Filter</filter-name>
   <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
</filter>

<filter-mapping>
   <filter-name>Seam Filter</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>]]></programlisting>

         <para>
            If any other Seam Filters (for example the 
            <literal>SeamExceptionFilter</literal>) are enumerated, they should
            be removed.
         </para>

         <para>
            Finally, you should have the Seam resource servlet (just as you did
            in Seam 1.2):
         </para>
         
             <programlisting role="XML"><![CDATA[<servlet>
   <servlet-name>Seam Resource Servlet</servlet-name>
   <servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
</servlet>
    
<servlet-mapping>
   <servlet-name>Seam Resource Servlet</servlet-name>
   <url-pattern>/seam/resource/*</url-pattern>
</servlet-mapping>]]></programlisting>
         
         <para>
            Seam 2 will automatically install RichFaces' Ajax4JSF if it present
            in your project so you should make sure the Ajax4JSF filter isn't
            declared:
         </para>
         
         <programlisting role="XML"><![CDATA[<!--Remove for Seam 2-->
<!--<filter>
  <display-name>Ajax4jsf Filter</display-name>
  <filter-name>ajax4jsf</filter-name>
  <filter-class>org.ajax4jsf.Filter</filter-class>
</filter>-->
    
<!--Remove for Seam 2-->
<!--<filter-mapping>
  <filter-name>ajax4jsf</filter-name>
  <url-pattern>*.seam</url-pattern>
</filter-mapping>-->]]></programlisting>
      
         <para>
            Next, we'll describe the changes you need to make to your JSF
            <literal>ViewHandler</literal> configuration. Previously the
            configuration you used depended on whether you were using Seam's EL
            enhancements or Ajax4JSF or both. In Seam 2 you should use the
            default <literal>FaceletViewHandler</literal>.
         </para>
         
         <para> 
            Seam 1.2 required you to use a special JSF 
            <literal>ViewHandler</literal> to install it's EL enhancement 
            (whilst in Seam 2 the EL enhancement is built in). The version of 
            Ajax4JSF distributed with Seam 1.2 required you to specify which 
            <literal>ViewHandler</literal> to use when it was in use. Make sure
            that the Ajax4JSF configuration is removed from your 
            <literal>web.xml:</literal>:
         </para>
         
         <programlisting role="XML"><![CDATA[<!--Remove for Seam 2-->
<!--<context-param>
   <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
   <param-value>org.jboss.seam.ui.facelet.SeamFaceletViewHandler</param-value>
</context-param>-->]]></programlisting>


      </section>
      
      <section>
         <title>Migrating <literal>faces-config.xml</literal> to Seam 2</title>

		 <para>Remove the DTD on the document and add the XML Schema declarations to the
             root tag:
         </para>
<programlisting role="XML"><![CDATA[<faces-config version="1.2"
  xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
    http://java.sun.com/xml/ns/javaee
    http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd">
  ...
</faces-config>]]></programlisting>

         <para>
            Seam 1.2 required you to specify either the 
            <literal>SeamPhaseListener</literal> (Seam Managed Transaction were
            are disabled) or <literal>SeamTransactionalPhaseListener</literal> 
            (Seam Managed Transactions are enabled) in
            <literal>faces-config.xml</literal>. Seam 2 lets you enable or
            disable Seam Managed Transactions in 
            <literal>components.xml</literal>, and installs the phase listener
            for you. Therefore, you should remove any reference to 
            <literal>SeamPhaseListener</literal> or 
            <literal>SeamTransactionalPhaseListener</literal> from
            <literal>faces-config.xml</literal>. 
         </para>
         
         <para>
            Seam Managed Transaction are enabled by default, to disable Seam 
            Managed Transactions, set 
            <literal>transaction-management-enabled</literal> to false:
         </para>
      
         <programlisting role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>]]></programlisting>

         <para>
            To workaround a bug, you may have specified 
            <literal>SeamELResolver</literal> in 
            <literal>faces-config.xml</literal>. This is no longer required.
         </para>
         
         <para>
            Finally remove <literal>FaceletViewHandler</literal> configuration:
         </para>
         
         <programlisting role="XML"><![CDATA[<application>
   <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
</application>]]></programlisting>
      
      </section>
      
      <section>
         <title>Deployment structure changes</title>
         
         <para>
            If you have an EAR application there are some deployment structure
            changes needed. You should move all the dependencies which you 
            previously declared as modules in <literal>application.xml</literal> 
            in the <literal>lib/</literal> directory of your EAR 
            <emphasis>except</emphasis> <literal>jboss-seam.jar</literal> which 
            should be declared as an ejb module in 
            <literal>application.xml</literal>. Remove the unneeded module
            declarations from <literal>application.xml</literal>.
         </para>
         
      </section>
      
      <section id="migration.embedded">
         <title>Migration to JBoss Embedded</title>

         <para>
            Support for deployment to JBoss Embeddable EJB3 and JBoss 
            Microcontainer has been removed. Instead, the new JBoss Embedded 
            distribution gives you a full set of EE-compatible APIs with 
            simplified deployment.
         </para>

         <para>
            For testing, you need the jars in Seam's <literal>lib/test</literal>,
            the jars in Seam's <literal>lib/</literal> directory, your test 
            classes and application classes together with the 
            <literal>bootstrap/</literal> directory in your classpath. 
            <literal>SeamTest</literal> will automatically start the container. 
         </para>
         
         <warning>
            <para>
               You must order the classpath correctly when using Embedded with
               <literal>SeamTest</literal>. Make sure the jars in
               <literal>lib/test</literal> come first in any classpath order.
               For example, when using Ant, they should be declared above any
               other libraries in the test classpath.
            </para>
         </warning>
         
         <para>
            If you want to run tests using the Eclipse TestNG plugin, you'll 
            need to add these jars to the top of your TestNG classpath.  Using 
            the Run Dialog, select the xml suite to run, and add 
            <literal>/lib/test/jboss-embedded-all.jar</literal>,
            <literal>/lib/test/hibernate-all.jar</literal>, 
            <literal>/lib/test/thirdparty-all.jar</literal>, 
            <literal>/lib/jboss-embedded-api.jar</literal>,
            <literal>/lib/jboss-deployers-client-spi.jar</literal>, 
            <literal>/lib/jboss-deployers-core-spi.jar</literal>, and 
            <literal>/bootstrap</literal> as the first entries in the
            <emphasis>User classpath</emphasis>.
         </para>
         
         <para>
            Note that JBoss Embedded is able to bootstrap a datasource from a 
            <literal>-ds.xml</literal> file, so there is no longer a need for 
            <literal>jboss-beans.xml</literal>.
         </para>

      </section>
      
   </section>
   
   <section id="migrating.general">
      <title>Updating your code</title>
      
      <important>
         <para>
            Don't forget to update the XSD's in <literal>pages.xml</literal> and
            <literal>components.xml</literal> to point at the ones for Seam 2.
            Just change the suffix from <literal>-1.2.xsd</literal> to
            <literal>-2.0.xsd</literal>.
         </para>
      </important>
      
      <section>
         <title>Built-in Component changes</title>
         
         <para>
            Seam's built-in components have undergone a major reorganization 
            designed to organize them for easier learning, and to isolate 
            dependencies upon particular technologies like JSF into specific 
            packages.
         </para>
         
         <para>
            You'll need to update both your <literal>components.xml</literal> 
            and any references in Java code.
         </para>
         
         <para>
            In general:
         </para>
         
         <itemizedlist>
            <listitem>
               <para>
                  Persistence-related components are located in 
                  <literal>org.jboss.seam.persistence</literal>
               </para>
            </listitem>
            <listitem>
               <para>
                  jBPM related components are located in  
                  <literal>org.jboss.seam.bpm</literal>
               </para>
            </listitem>
            <listitem>
               <para>
                  JSF-related components are located in 
                  <literal>org.jboss.seam.faces</literal>
               </para>
            </listitem>
            <listitem>
               <para>
                  Servlet-related components are located in
                  <literal>org.jboss.seam.web</literal>
               </para>
            </listitem>
            <listitem>
               <para>
                  Components related to asynchronicity are located in 
                  <literal>org.jboss.seam.async</literal>
               </para>
            </listitem>
            <listitem>
               <para>
                  i18n-related components are located in 
                  <literal>org.jboss.seam.international</literal>
               </para>
            </listitem>
            <listitem>
               <para>
                  The Pageflow component are located in 
                  <literal>org.jboss.seam.pageflow</literal>
               </para>
            </listitem>
            <listitem>
               <para>
                  The Pages component are located in 
                  <literal>org.jboss.seam.navigation</literal>
               </para>
            </listitem>
         </itemizedlist>
         
         <para>
            The following table presents a non-exhaustive list of
            changed components:
         </para>
         
         <table>
            <title>Component's in Seam 2</title>
            <tgroup cols="2">
          <!--     <colspec colnum="1" colwidth="2*" />
               <colspec colnum="2" colwidth="2*" />
               <colspec colnum="3" colwidth="2*" />
               <colspec colnum="4" colwidth="2*" />
               <colspec colnum="5" colwidth="2*" />
               <colspec colnum="6" colwidth="2*" /> -->

               <thead>
                  <row>
                     <entry>
                        <para>Component name</para>
                     </entry>
                     <entry>
                        <para>Seam 1.2 Old class</para>
                     </entry>
                     <entry>
                        <para>Seam 2 class</para>
                     </entry>
                     <entry>
                        <para>XML Element</para>
                     </entry>
                     <entry>
                        <para>XML namespace</para>
                     </entry>
                     <entry>
                        <para>XSD</para>
                     </entry>
                  </row>
               </thead>
               <tbody>
                  <row>
                      <entry>
                        <para><literal>actor</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Actor</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.bpm.Actor</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;bpm:actor /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/bpm</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/bpm-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                      <entry>
                        <para><literal>businessProcess</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.BusinessProcess</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.bpm.BusinessProcess</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>dispatcher</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Dispatcher</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.async.Dispatcher</literal> (now an interface)</para>
                     </entry>
                     <entry>
                        <para><literal>&lt;async:timer-service-dispatcher /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/async</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/async-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                      <entry>
                        <para>Specified by user</para>
                     </entry>
                     <entry>
                        <para><literal>javax.persistence.EntityManagerFactory</literal></para>
                     </entry>
                     <entry>
                        <para><literal>javax.persistence.EntityManagerFactory</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;persistence:entity-manager-factory /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>exceptions</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Exceptions</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.exception.Exceptions</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>facesMessages</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.FacesMessages</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.faces.FacesMessages</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>facesPage</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.FacesPage</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.faces.FacesPage</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  
                  <row>
                     <entry>
                        <para>Specified by user</para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Filter</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.persistence.Filter</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;persistence:filter /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para>Specified by user</para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.HibernateSessionFactory</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.persistence.HibernateSessionFactory</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;persistence:hibernate-session-factory /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>httpError</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.HttpError</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.faces.HttpError</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>image</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Image</literal></para>
                     </entry>
                     <entry>
                        <para>removed</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>isUserInRole</literal></para>
                     </entry>
                     <entry>
                        <para><literal>Map&lt;String, Boolean&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.faces.IsUserInRole</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>jbpm</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Jbpm</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.bpm.Jbpm</literal></para>
                     </entry>
                     <entry>
                        <para><literal>bpm</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/bpm</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/bpm-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.LocalDispatcher</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.async.LocalDispatcher</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>localeSelector</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.LocaleSelector</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.international.LocaleSelector</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;international:locale-selector /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/international</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/international-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.LocalTransactionListener</literal></para>
                     </entry>
                     <entry>
                        <para>removed</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para>Specified by user</para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.ManagedHibernateSession</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.persistence.ManagedHibernateSession</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;persistence:managed-hibernate-session /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>jbpmContext</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.ManagedJbpmContext</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.bpm.ManagedJbpmContext</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para>Specified by user</para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.ManagedEntityManager</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.persistence.ManagedEntityManager</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;persistence:managed-entity-manager /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/persistence-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>microcontainer</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Microcontainer</literal></para>
                     </entry>
                     <entry>
                        <para>removed</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>pageflow</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Pageflow</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.bpm.Pageflow</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>pages</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Pages</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.navigation.Pages</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;navigation:pages/&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/navigation</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/navigation-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>persistenceContexts</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.PersistenceContexts</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.persistence.PersistenceContexts</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>pooledTask</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.PooledTask</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.bpm.PooledTask</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>processInstanceFinder</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.ProcessInstanceFinder</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.bpm.ProcessInstanceFinder</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>redirect</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Redirect</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.faces.Redirect</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>switcher</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Switcher</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.faces.Switcher</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>timeZoneSelector</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.TimeZoneSelector</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.international.TimeZoneSelector</literal></para>
                     </entry>
                     <entry>
                        <para><literal>&lt;international:time-zone-selector /&gt;</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/international</literal></para>
                     </entry>
                     <entry>
                        <para><literal>http://jboss.com/products/seam/international-2.0.xsd</literal></para>
                     </entry>
                  </row>
                  <row>
                     <entry>
                        <para><literal>transition</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.core.Transistion</literal></para>
                     </entry>
                     <entry>
                        <para><literal>org.jboss.seam.bpm.Transition</literal></para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                     <entry>
                        <para>N/A</para>
                     </entry>
                  </row>
               </tbody>
            </tgroup>
         </table>
         
      </section>
      
      <section>
         <title>Annotation changes in Seam 2</title>
         
         <para>
            Annotations have also moved to reflect their purpose. In
         </para>
         
         <itemizedlist>
            <listitem>
               <para>
                  BPM-related annotations are located in
                  <literal>org.jboss.seam.annotations.bpm</literal>
               </para>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>@BeginTask</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@CreateProcess</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@EndTask</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@ResumeProcess</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@StartTask</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@Transition</literal>
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
            <listitem>
               <para>
                  JSF-related annotations are located in
                  <literal>org.jboss.seam.annotations.faces</literal>
               </para>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>@Converter</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@Validator</literal>
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
            <listitem>
               <para>
                  Interceptor annotations are located in
                  <literal>org.jboss.seam.annotations.intercept</literal>
               </para>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>@AroundInvoke</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@BypassIntercetors</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@Interceptor</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@Interceptors</literal>
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
            <listitem>
               <para>
                  Annotations related to asynchronicity are located in
                  <literal>org.jboss.seam.annotations.async</literal>
               </para>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>@Asynchronous</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@Duration</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@Expiration</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@FinalExpiration</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@IntervalCron</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@IntervalDuration</literal>
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
            <listitem>
               <para>
                  The annotation to inject a request parameter is located in
                  <literal>org.jboss.seam.annotations.web</literal>
               </para>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>@RequestParameter</literal>
                     </para>
                  </listitem>
                </itemizedlist> 
            </listitem>
            <listitem>
               <para>
                  The annotation required to make a method accessible via 
                  remoting is located in 
                  <literal>org.jboss.seam.annotations.remoting</literal>
               </para>
            </listitem>
            <listitem>
               <para>
                  The annotation to apply a security restriction to the 
                  component is located in
                  <literal>org.jboss.seam.annotations.security</literal>
               </para>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>@Restrict</literal>
                     </para>
                  </listitem>
                </itemizedlist> 
            </listitem>
            <listitem>
               <para>
                  Exception handling annotations moved to 
                  <literal>org.jboss.seam.annotations.exception</literal>
               </para>
               <itemizedlist>
                  <listitem>
                     <para>
                        <literal>@HttpError</literal>
                     </para>
                  </listitem>
                  <listitem>
                     <para>
                        <literal>@Redirect</literal>
                     </para>
                  </listitem>
               </itemizedlist>
            </listitem>
         </itemizedlist>
         
         <note>
            <para>
               You also need to replace <literal>@Intercept(NEVER)</literal>
               with <literal>@BypassInterceptors</literal>.
            </para>
         </note>
         
          
      </section>
      
      <section>
         <title>Other changes needed to <literal>components.xml</literal></title>
         
         <para>
            The <literal>conversation-is-long-running-parameter</literal>
            attribute has been removed from Seam (and doesn't have a 
            replacement), remove it from <literal>&lt;core:init /&gt;</literal>.
         </para> 
   
         <para>
            As described in <xref linkend="migration.embedded"/>, Embeddable EJB3
            and Microcontainer support has been removed, so you need to remove
            <literal>&lt;core:ejb/&gt;</literal> and 
            <literal>&lt;core:microcontainer/&gt;</literal> from 
            <literal>components.xml</literal>.
         </para>
         
         <para>
            The EE transaction integration has been redesigned, so the 
            transaction listener component name has changed. Replace 
            <literal>&lt;core:transaction-listener/&gt;</literal> with 
            <literal>&lt;transaction:ejb-transaction/&gt;</literal>. 
         </para>
         
         <para>
            The resource bundle loader has been split out of the resource bundle,
            so you should replace 
            <literal>&lt;core:resource-bundle/&gt;</literal> with 
            <literal>&lt;core:resource-loader/&gt;</literal>. 
         </para>
         
         <para>
            Finally, you should change any <literal>expression</literal> 
            attributes to <literal>execute</literal>:
         </para>
         
         <programlisting role="XML"><![CDATA[<event type="org.jboss.seam.notLoggedIn">
   <action execute="#{redirect.captureCurrentView}"/>
</event>]]></programlisting>

      </section>
      
      <section>
         <title>Migration to jBPM 3.2</title>

         <para>
            If you are using jBPM for business processes, 
            you need to add the tx service to <literal>jbpm.cfg.xml</literal>:
         </para>
         
         <programlisting role="XML"><![CDATA[<service name="tx" factory="org.jbpm.tx.TxServiceFactory" />]]></programlisting> 

         <note>
            <para>
               You don't need to do this if you are just using jBPM for 
               pageflows.
            </para>
         </note>
         
      </section>
      
      <section>
         <title>Migration to RichFaces 3.1</title>

         <para>
            If you are using RichFaces or Ajax4jsf, a major reorganization of 
            the project has occurred. The jars <literal>ajax4jsf.jar</literal> and 
            <literal>richfaces.jar</literal> have been replaced by 
            <literal>richfaces-api.jar</literal> (which should go in your ear 
            <literal>lib/</literal> directory), 
            <literal>richfaces-impl.jar</literal> and 
            <literal>richfaces-ui.jar</literal> (both of which go in 
            <literal>WEB-INF/lib</literal>).
         </para>
         
         <para>
         &lt;s:selectDate&gt; has been deprecated in favor of &lt;rich:calendar&gt;. No more 
		development will be done on &lt;s:selectDate&gt;. You can remove the styles related
		to the data picker from your stylesheet to save on unnecessary bandwidth use.
         </para>
         <para>
            You should check the RichFaces documentation for more information on
            parameter name changes and namespace changes.
         </para>
         
      </section>
      
      <section>
         <title>Changes to Seam UI</title>
         
         <para>
            As most JSF component sets provide a date selector, the Seam date
            selector (&lt;s:selectDate&gt;) has been deprecated. You
            should replace it with the date selector from the component set you
            use.
         </para>
         
         <para>
            Selector &lt;s:decorate/&gt; has become a naming container.  
            Therefore client ids have changed from 
            <literal>fooForm:fooInput</literal> to 
            <literal>fooForm:foo:fooInput</literal>, assuming the following declaration:</para>
                        
 <programlisting role="XML"><![CDATA[<h:form id="fooForm">
  <s:decorate id="foo">
    <h:inputText id="fooInput" value="#{bean.property}"/>
   </s:decorate>
</h:form>]]></programlisting>

          <para>If you don't provide an id to &lt;s:decorate&gt;, one will be generated by JSF.</para>         
         
      </section>
      
      <section>
      	<title>Changes to seam-gen</title>
      	
      	<para>There was a change in seam-gen regarding
		how the generated classes are organized when generate-entities is
		executed.</para>

		<variablelist>		
		<varlistentry>
			<term>Old way:</term>				
			<listitem><para>src/model/com/domain/projectname/model/EntityName.java</para></listitem>
			<listitem><para>src/action/com/domain/projectname/model/EntityNameHome.java</para></listitem>
			<listitem><para>src/action/com/domain/projectname/model/EntityNameList.java</para></listitem>
		</varlistentry>
		
		<varlistentry><term>New way:</term>
			<listitem><para>src/model/com/domain/projectname/model/EntityName.java</para></listitem>
		  	<listitem><para>src/action/com/domain/projectname/action/EntityNameHome.java</para></listitem>
		  	<listitem><para>src/action/com/domain/projectname/action/EntityNameList.java</para></listitem>
		</varlistentry>
		</variablelist>
		  

		<para>Home and Query objects are <quote>action</quote> components, not <quote>model</quote> components
		and are therefore placed in the action package. This change makes the
		conventions followed by generate-entities consistent with the conventions
		used in the new-entity command.</para>

		<para>Remember, model classes are kept separate because they cannot be hot reloaded.</para>

		<para>Due to the change from JBoss Embeddable EJB3 to JBoss Embedded for testing,
		it is recommended that you generate a project using seam-gen from Seam 2
		and borrow the <literal>build.xml</literal> file from that project. If you have made
		significant changes to the <literal>build.xml</literal> in your project, you may want to focus
		on just migrating the test-related targets.</para>
		
		<para>In order for tests to work under JBoss Embedded, you need to change the
		value of the &lt;datasource&gt; element in <literal>resources/META-INF/persistence-test.xml</literal>
		(or <literal>persistence-test-war.xml</literal>) to <literal>java:/DefaultDS</literal>. The alternative is to
		deploy a <literal>*-ds.xml</literal> file to the <literal>bootstrap/deploy</literal> folder and use the JNDI name
		defined by that file.</para>
		
		<para>If you use the <literal>build.xml</literal> from a Seam 2 seam-gen project, you will also need
		the <literal>deployed-*.list</literal> file(s). These files define which JAR files are packaged
		in the EAR or WAR. They were introduced to externalize this set of JARS from
		the <literal>build.xml</literal> file.</para>
		
		<para>To accommodate a change in the RichFaces panel, you need to add the following
		style to your stylesheet. Otherwise, you're search criteria block in pages
		created by generate-entities will bleed into the table of results.</para>

<programlisting><![CDATA[.rich-stglpanel-body {
    overflow: auto;
}]]></programlisting>

      	
      </section>	
   </section>

</chapter>
