JBoss.com Enterprise Documentation

- Prev
- Next

## Chapter 4. Migrating from Seam 1.2 to Seam 2

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.

## 4.1. Creating a new project skeleton using seam-gen

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.

## 4.2. In place migration

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.

### 4.2.1. Migrating to JSF 1.2

## Warning

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.

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:

    <!--Remove for Seam 2-->

    <!--<listener>

       <listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class>

    </listener>-->

from your `web.xml`.

The JSF RI doesn't require you to specify a listener.

## Tip

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.

### 4.2.2. Migrating `web.xml` and `faces-config.xml` to Seam 2

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.

### 4.2.3. Deployment structure changes

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 `application.xml` in the `lib/` directory of your EAR except `jboss-seam.jar` which should be declared as an ejb module in `application.xml`. Remove the unneeded module declarations from `application.xml`.

### 4.2.4. Migration to JBoss Embedded

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.

For testing, you need the jars in Seam's `lib/test`, the jars in Seam's `lib/` directory, your test classes and application classes together with the `bootstrap/` directory in your classpath. `SeamTest` will automatically start the container.

## Tip

You must order the classpath correctly when using Embedded with `SeamTest`. Make sure the jars in `lib/test` come first in any classpath order. For example, when using Ant, they should be declared above any other libraries in the test classpath.

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 `/lib/test/jboss-embedded-all.jar`, `/lib/test/hibernate-all.jar`, `/lib/test/thirdparty-all.jar`, `/lib/jboss-embedded-api.jar`, `/lib/jboss-deployers-client-spi.jar`, `/lib/jboss-deployers-core-spi.jar`, and `/bootstrap` as the first entries in the User classpath.

Note that JBoss Embedded is able to bootstrap a datasource from a `-ds.xml` file, so there is no longer a need for `jboss-beans.xml`.

## 4.3. Updating your code

## Tip

Don't forget to update the XSD's in `pages.xml` and `components.xml` to point at the ones for Seam 2. Just change the suffix from `-1.2.xml` to `-2.0.xml`.

### 4.3.1. Built-in Component changes

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:

- Persistence-related components are located in `org.jboss.seam.persistence`

- jBPM related components are located in `org.jboss.seam.bpm`

- JSF-related components are located in `org.jboss.seam.faces`

- Servlet-related components are located in `org.jboss.seam.web`

- Components related to asynchronicity are located in `org.jboss.seam.async`

- i18n-related components are located in `org.jboss.seam.international`

- The Pageflow component are located in `org.jboss.seam.pageflow`

- The Pages component are located in `org.jboss.seam.navigation`

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

### 4.3.2. Annotation changes in Seam 2

Annotations have also moved to reflect their purpose. In

- BPM-related annotations are located in `org.jboss.seam.annotations.bpm`

  - `@BeginTask`

  - `@CreateProcess`

  - `@EndTask`

  - `@ResumeProcess`

  - `@StartTask`

  - `@Transition`

- JSF-related annotations are located in `org.jboss.seam.annotations.faces`

  - `@Converter`

  - `@Validator`

- Interceptor annotations are located in `org.jboss.seam.annotations.intercept`

  - `@AroundInvoke`

  - `@BypassIntercetors`

  - `@Interceptor`

  - `@Interceptors`

- Annotations related to asynchronicity are located in `org.jboss.seam.annotations.async`

  - `@Asynchronous`

  - `@Duration`

  - `@Expiration`

  - `@FinalExpiration`

  - `@IntervalCron`

  - `@IntervalDuration`

- The annotation to inject a request parameter is located in `org.jboss.seam.annotations.web`

  - `@RequestParameter`

- The annotation required to make a method accessible via remoting is located in `org.jboss.seam.annotations.remoting`

- The annotation to apply a security restriction to the component is located in `org.jboss.seam.annotations.security`

  - `@Restrict`

- Exception handling annotations moved to `org.jboss.seam.annotations.exception`

  - `@HttpError`

  - `@Redirect`

## Note

You also need to replace `@Intercept(NEVER)` with `@BypassInterceptors`.

### 4.3.3. Other changes needed to `components.xml`

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>

### 4.3.4. Migration to jBPM 3.2

If you are using jBPM for business processes, you need to add the tx service to `jbpm.cfg.xml`:

    <service name="tx" factory="org.jbpm.tx.TxServiceFactory" />

## Tip

You don't need to do this if you are just using jBPM for pageflows.

### 4.3.5. Migration to RichFaces 3.1

If you are using RichFaces or Ajax4jsf, a major reorganization of the project has occurred. `ajax4jsf.jar` and `richfaces.jar` have been replaced by `richfaces-api.jar` (which should go in your ear `lib/` directory), `richfaces-impl.jar` and `richfaces-ui.jar` (both of which go in `WEB-INF/lib`).

You should check the RichFaces documentation for more information on parameter name changes and namespace changes.

### 4.3.6. Changes to Seam UI

As most JSF component sets provide a date selector, the Seam date selector (`s:selectDate` has been deprecated. You should replace it with the date selector from the component set you use.

`<s:decorate/>` has become a naming container. Therefore client ids have changed from `fooForm:fooInput` to `fooForm:foo:fooInput` (assuming your `<s:decorate>` has foo as an id).

- PrevChapter 3. Getting started with Seam, using JBoss...
- Top of page
- Front page
- NextChapter 5. The contextual component model