JBoss.comEnterprise Documentation

Chapter 4. Migrating from Seam 1.2 to Seam 2

4.1. Creating a new project skeleton using seam-gen
4.2. In place migration
4.2.1. Migrating to JSF 1.2
4.2.2. Migrating web.xml and faces-config.xml to Seam 2
4.2.3. Deployment structure changes
4.2.4. Migration to JBoss Embedded
4.3. Updating your code
4.3.1. Built-in Component changes
4.3.2. Annotation changes in Seam 2
4.3.3. Other changes needed to components.xml
4.3.4. Migration to jBPM 3.2
4.3.5. Migration to RichFaces 3.1
4.3.6. Changes to Seam UI

There are two approaches to migrating your Seam 1.2 application to Seam 2. The recommended approach, described in Section 4.1, “Creating a new project skeleton using seam-gen” 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 Section 4.2, “In place migration” Due to the number of changes introduced between Seam 1.2 and Seam 2, this may not always be a straightforward process!

However you decide to migrate your application, you'll need to alter your code, as many components have moved. Section 4.3, “Updating your code” details those changes.

Start by creating a new skeleton seam project. In your Seam 2 directory run:

~/seam_2_0$ ./seam setup

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.

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.

Continue on to Section 4.3, “Updating your code” for details regarding the changes needed to your code, and configuration files.

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.

In your Seam 1.2 app you may have specified some Seam specific configuration in web.xml. First, we'll discuss all the Seam related elements you need in web.xml, not just those that have changed, noting any changes.

In Seam 2, you need specify a listener (just as you did in Seam 1.2):


<listener>
   <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
</listener>

Modify the Seam master filter (note the package of the class changed):


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

If any other Seam Filters (for example the SeamExceptionFilter) are enumerated, they should be removed.

Finally, you should have the Seam resouce servlet (just as you did in Seam 1.2):


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

Seam 2 will automatically install RichFaces' Ajax4JSF if it present in your project so you should make sure the Ajax4JSF filter isn't declared:


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

Next, we'll describe the changes you need to make to your JSF ViewHandler 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 FaceletViewHandler.

Seam 1.2 required you to use a special JSF ViewHandler 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 ViewHandler to use when it was in use. Make sure that the Ajax4JSF configuration is removed from your web.xml::


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

And that FaceletViewHandler is set in faces-config.xml:


<application>
   <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
</application>

Seam 1.2 required you to specify either the SeamPhaseListener (Seam Managed Transaction were are disabled) or SeamTransactionalPhaseListener (Seam Managed Transactions are enabled) in faces-config.xml. Seam 2 lets you enable or disable Seam Managed Transactions in components.xml, and installs the phase listener for you. Therefore, you should remove any reference to SeamPhaseListener or SeamTransactionalPhaseListener from faces-config.xml.

Seam Managed Transaction are enabled by default, to disable Seam Managed Transactions, set transaction-management-enabled to false:


<core:init transaction-management-enabled="false"/>

To workaround a bug, you may have specified SeamELResolver in faces-config.xml. This is no longer required.

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.

You'll need to update both your components.xml and any references in Java code.

In general:

The following table presents a non-exhaustive list of changed components:

Table 4.1. Component's in Seam 2

Component name

Seam 1.2 Old class

Seam 2 class

XML Element

XML namespace

XSD

actor

org.jboss.seam.core.Actor

org.jboss.seam.bpm.Actor

<bpm:actor />

http://jboss.com/products/seam/bpm

http://jboss.com/products/seam/bpm-2.0.xsd

businessProcess

org.jboss.seam.core.BusinessProcess

org.jboss.seam.bpm.BusinessProcess

N/A

N/A

N/A

dispatcher

org.jboss.seam.core.Dispatcher

org.jboss.seam.async.Dispatcher (now an interface)

<async:timer-service-dispatcher />

http://jboss.com/products/seam/async

http://jboss.com/products/seam/async-2.0.xsd

Specified by user

javax.persistence.EntityManagerFactory

javax.persistence.EntityManagerFactory

<persistence:entity-manager-factory />

http://jboss.com/products/seam/persistence

http://jboss.com/products/seam/persistence-2.0.xsd

exceptions

org.jboss.seam.core.Exceptions

org.jboss.seam.exception.Exceptions

N/A

N/A

N/A

facesMessages

org.jboss.seam.core.FacesMessages

org.jboss.seam.faces.FacesMessages

N/A

N/A

N/A

facesPage

org.jboss.seam.core.FacesPage

org.jboss.seam.faces.FacesPage

N/A

N/A

N/A

Specified by user

org.jboss.seam.core.Filter

org.jboss.seam.persistence.Filter

<persistence:filter />

http://jboss.com/products/seam/persistence

http://jboss.com/products/seam/persistence-2.0.xsd

Specified by user

org.jboss.seam.core.HibernateSessionFactory

org.jboss.seam.persistence.HibernateSessionFactory

<persistence:hibernate-session-factory />

http://jboss.com/products/seam/persistence

http://jboss.com/products/seam/persistence-2.0.xsd

httpError

org.jboss.seam.core.HttpError

org.jboss.seam.faces.HttpError

N/A

N/A

N/A

image

org.jboss.seam.core.Image

removed

N/A

N/A

N/A

isUserInRole

Map<String, Boolean>

org.jboss.seam.faces.IsUserInRole

N/A

N/A

N/A

jbpm

org.jboss.seam.core.Jbpm

org.jboss.seam.bpm.Jbpm

bpm

http://jboss.com/products/seam/bpm

http://jboss.com/products/seam/bpm-2.0.xsd

N/A

org.jboss.seam.core.LocalDispatcher

org.jboss.seam.async.LocalDispatcher

N/A

N/A

N/A

localeSelector

org.jboss.seam.core.LocaleSelector

org.jboss.seam.international.LocaleSelector

<international:locale-selector />

http://jboss.com/products/seam/international

http://jboss.com/products/seam/international-2.0.xsd

N/A

org.jboss.seam.core.LocalTransactionListener

removed

N/A

N/A

N/A

Specified by user

org.jboss.seam.core.ManagedHibernateSession

org.jboss.seam.persistence.ManagedHibernateSession

<persistence:managed-hibernate-session />

http://jboss.com/products/seam/persistence

http://jboss.com/products/seam/persistence-2.0.xsd

jbpmContext

org.jboss.seam.core.ManagedJbpmContext

org.jboss.seam.bpm.ManagedJbpmContext

N/A

N/A

N/A

Specified by user

org.jboss.seam.core.ManagedEntityManager

org.jboss.seam.persistence.ManagedEntityManager

<persistence:managed-entity-manager />

http://jboss.com/products/seam/persistence

http://jboss.com/products/seam/persistence-2.0.xsd

microcontainer

org.jboss.seam.core.Microcontainer

removed

N/A

N/A

N/A

pageflow

org.jboss.seam.core.Pageflow

org.jboss.seam.bpm.Pageflow

N/A

N/A

N/A

pages

org.jboss.seam.core.Pages

org.jboss.seam.navigation.Pages

<navigation:pages/>

http://jboss.com/products/seam/navigation

http://jboss.com/products/seam/navigation-2.0.xsd

persistenceContexts

org.jboss.seam.core.PersistenceContexts

org.jboss.seam.persistence.PersistenceContexts

N/A

N/A

N/A

pooledTask

org.jboss.seam.core.PooledTask

org.jboss.seam.bpm.PooledTask

N/A

N/A

N/A

processInstanceFinder

org.jboss.seam.core.ProcessInstanceFinder

org.jboss.seam.bpm.ProcessInstanceFinder

N/A

N/A

N/A

redirect

org.jboss.seam.core.Redirect

org.jboss.seam.faces.Redirect

N/A

N/A

N/A

switcher

org.jboss.seam.core.Switcher

org.jboss.seam.faces.Switcher

N/A

N/A

N/A

timeZoneSelector

org.jboss.seam.core.TimeZoneSelector

org.jboss.seam.international.TimeZoneSelector

<international:time-zone-selector />

http://jboss.com/products/seam/international

http://jboss.com/products/seam/international-2.0.xsd

transition

org.jboss.seam.core.Transistion

org.jboss.seam.bpm.Transition

N/A

N/A

N/A


The conversation-is-long-running-parameter attribute has been removed from Seam (and doesn't have a replacement), remove it from <core:init />.

As described in Section 4.2.4, “Migration to JBoss Embedded”, Embeddable EJB3 and Microcontainer support has been removed, so you need to remove <core:ejb/> and <core:microcontainer/> from components.xml.

The EE transaction integration has been redesigned, so the transaction listener component name has changed. Replace <core:transaction-listener/> with <transaction:ejb-transaction/>.

The resource bundle loader has been split out of the resource bundle, so you should replace <core:resource-bundle/> with <core:resource-loader/>.

Finally, you should change any expression attributes to execute:


<event type="org.jboss.seam.notLoggedIn">
   <action execute="#{redirect.captureCurrentView}"/>
</event>