Chapter 2. Migration

If you already have a previous version of Seam installed, you will need to follow the instructions in this chapter to migrate to latest version (2.2.0), which is available with the JBoss Enterprise Application Platform.
If you are already using Seam 2.0, you can skip directly to Section 2.2, “Migrating from Seam 2.0 to Seam 2.1 or 2.2”. If you are currently using Seam 1.2.x, follow the instructions in both Section 2.1, “Migrating from Seam 1.2.x to Seam 2.0” and Section 2.2, “Migrating from Seam 2.0 to Seam 2.1 or 2.2”.

2.1. Migrating from Seam 1.2.x to Seam 2.0

In this section, we show you how to migrate from Seam 1.2.x to Seam 2.0. We also list the changes to Seam components between versions.

2.1.1. Migrating to JavaServer Faces 1.2

Seam 2.0 requires JSF 1.2 to work correctly. We recommend Sun's JSF Reference Implementation (RI), which ships with most Java EE 5 application servers, including JBoss 4.2. To switch to the JSF RI, you will need to make the following changes to your web.xml:
  • Remove the MyFaces StartupServletContextListener.
  • Remove the AJAX4JSF filter, mappings, and org.ajax4jsf.VIEW_HANDLERS context parameter.
  • Rename org.jboss.seam.web.SeamFilter as org.jboss.seam.servlet.SeamFilter.
  • Rename org.jboss.seam.servlet.ResourceServlet as org.jboss.seam.servlet.SeamResourceServlet.
  • Change the web-app version from 2.4 to 2.5. In the namespace URL, change j2ee to javaee. For example: 
    <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>
As of Seam 1.2, you can declare SeamFilter in web.xml instead of explicitly declaring SeamExceptionFilter and SeamRedirectFilter in web.xml.
Client-side state saving is not required with the JSF RI, and can be removed. (Client-side state saving is defined by the javax.faces.STATE_SAVING_METHOD context parameter.
You will also need to make the following changes to faces-config.xml:
  • Remove the TransactionalSeamPhaseListener or SeamPhaseListener declaration, if in use.
  • Remove the SeamELResolver declaration, if in use.
  • Change the SeamFaceletViewHandler declaration to the standard com.sun.facelets.FaceletViewHandler, and ensure it is enabled.
  • Remove the Document Type Declaration (DTD) from the document and add the XML Schema declarations to the <faces-config> root tag, like so: 
    <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>

2.1.2. Code Migration

Seam's built-in components have been reorganized to make them easier to learn and to isolate particular technology dependencies into specific packages.
  • Persistence-related components have been moved to org.jboss.seam.persistence.
  • jBPM-related components have been moved to org.jboss.seam.bpm.
  • JSF-related components, most notably org.jboss.seam.faces.FacesMessages, have been moved to org.jboss.seam.faces.
  • Servlet-related components have been moved to org.jboss.seam.web.
  • Components related to asynchronicity have been moved to org.jboss.seam.async.
  • Internationalization-related components have been moved to org.jboss.seam.international.
  • The Pageflow component has been moved to org.jboss.seam.pageflow.
  • The Pages component has been moved to org.jboss.seam.navigation.
Any code that depends upon these APIs will need to be altered to reflect the new Java package names.
Annotations have also been reorganized:
  • BPM-related annotations are now included in the org.jboss.seam.annotations.bpm package.
  • JSF-related annotations are now included in the org.jboss.seam.annotations.faces package.
  • Interceptor annotations are now included in the org.jboss.seam.annotations.intercept package.
  • Annotations related to asynchronicity are now included in the org.jboss.seam.annotations.async package.
  • @RequestParameter is now included in the org.jboss.seam.annotations.web package.
  • @WebRemote is now included in the org.jboss.seam.annotations.remoting package.
  • @Restrict is now included in the org.jboss.seam.annotations.security package.
  • Exception handling annotations are now included in the org.jboss.seam.annotations.exception package.
  • Use @BypassInterceptors instead of @Intercept(NEVER).

2.1.3. Migrating components.xml

The new packaging system outlined in the previous section means that you must update components.xml with the new schemas and namespaces.
Namespaces originally took the form org.jboss.seam.foobar. The new namespace format is http://jboss.com/products/seam/foobar, and the schema is of the form http://jboss.com/products/seam/foobar-2.0.xsd. You will need to update the format of the namespaces and schemas in your components.xml file so that the URLs correspond to the version of Seam that you wish to migrate to (2.0 or 2.1).
The following declarations must have their locations corrected, or be removed entirely:
  • Replace <core:managed-persistence-context> with <persistence:managed-persistence-context> .
  • Replace <core:entity-manager-factory> with <persistence:entity-manager-factory> .
  • Remove conversation-is-long-running parameter from <core:manager/> element.
  • Remove <core:ejb/> .
  • Remove <core:microcontainer/> .
  • Replace <core:transaction-listener/> with <transaction:ejb-transaction/> .
  • Replace <core:resource-bundle/> with <core:resource-loader/> .

Example 2.1. components.xml Notes

Seam transaction management is now enabled by default. It is now controlled by components.xml instead of a JSF phase listener declaration in faces-config.xml. To disable Seam-managed transactions, use the following: 
<core:init transaction-management-enabled="false"/>
The expression attribute on event actions has been deprecated in favor of execute. For example: 
<event type="org.jboss.seam.security.notLoggedIn">
   <action execute="#{redirect.captureCurrentView}"/>
</event>
<event type="org.jboss.seam.loginSuccessful">
   <action execute="#{redirect.returnToCapturedView}"/>
</event>
In Seam 2.2, security events use the org.jboss.seam.security> prefix instead of org.jboss.seam (for example, org.jboss.seam.security.notLoggedIn.)

Note

Instead of the org.jboss.seam.postAuthenticate event, use the org.jboss.seam.security.loginSuccessful event to return to the captured view.

2.1.4. Migrating to Embedded JBoss

Embedded JBoss no longer supports the use of JBoss Embeddable EJB3 or JBoss Microcontainer. Instead, the new Embedded JBoss distribution provides a complete set of Java EE-compatible APIs with simplified deployment.
For testing, you will need to include the following in your classpath:
  • the jars in Seam's lib/ directory
  • the bootstrap/ directory
Remove any references or artifacts relating to JBoss Embeddable EJB3, such as the embeddded-ejb directory and jboss-beans.xml. (You can use the Seam examples as reference.)
There are no longer any special configuration or packaging requirements for Tomcat deployment. To deploy with Tomcat, follow the instructions in the User Guide.

Note

Embedded JBoss can bootstrap a datasource from a -ds.xml file, so the jboss-beans.xml file is no longer required.

2.1.5. Migrating to jBPM 3.2

If you use jBPM for business processes as well as pageflows, you must add the tx service to jbpm.cfg.xml: 
<service name="tx" factory="org.jbpm.tx.TxServiceFactory" />

2.1.6. Migrating to RichFaces 3.1

There has been a major reorganization of the codebase for both RichFaces and AJAX4JSF. The ajax4jsf.jar and richfaces.jar jars have been replaced with the richfaces-api.jar (to be placed in the EAR lib/ directory) and the richfaces-impl.jar and richfaces-ui.jar (to be placed in WEB-INF/lib).
<s:selectDate> has been deprecated in favor of <rich:calendar> . There will be no further development of <s:selectDate> . The styles associated with the data picker should be removed from your style sheet to reduce bandwidth use.
Check the RichFaces documentation for more information about changes to namespace and parameter names.

2.1.7. Changes to Components

Packaging Changes

All dependencies that were previously declared as modules in application.xml should now be placed in the lib/ directory of your EAR, except jboss-seam.jar, which should be declared as an EJB module in application.xml.

Changes to the Seam User Interface

<s:decorate> has become a naming container. Client IDs have therefore changed from fooForm:fooInput to fooForm:foo:fooInput, assuming that the following has been declared: 

<h:form id="fooForm">
  <s:decorate id="foo">
     <h:inputText id="fooInput" value="#{bean.property}"/>
   </s:decorate>
</h:form>
If you do not provide an ID for <s:decorate> , JSF will generate an ID automatically.
Changes to seam-gen

Since Seam 2.0.0.CR2, there have been changes to the organization of generated classes in seam-gen when generate-entities is executed.

Originally, classes were generated as follows: 
        src/model/com/domain/projectname/model/EntityName.java
        src/action/com/domain/projectname/model/EntityNameHome.java
        src/action/com/domain/projectname/model/EntityNameList.java
Now, they are generated like this: 
        src/model/com/domain/projectname/model/EntityName.java
        src/action/com/domain/projectname/action/EntityNameHome.java
        src/action/com/domain/projectname/action/EntityNameList.java
Home and Query objects are action components, not model components, and are therefore placed in the action package. This makes generate-entities conventions consistent with those of the new-entity command.
Model classes are listed separately because they cannot be hot-reloaded.
Since the testing system has changed from JBoss Embeddable EJB3 to Embedded JBoss, we recommend that you generate a project with seam-gen in Seam 2.x, and use its build.xml file as a base for new projects. If you have made extensive changes to the build.xml, you can focus on migrating only test-related targets.
For tests to work under Embedded JBoss, you need to change the value of the <datasource> element in resources/META-INF/persistence-test.xml (or persistence-test-war.xml) to java:/DefaultDS. Alternatively, you can deploy a -ds.xml file to the bootstrap/deploy folder and use the JNDI name defined in that file.
If you use the Seam 2.x build.xml as described, you will also require the deployed-*.list files, which define the jar files that are packaged in the EAR or WAR archive. These were introduced to remove the jar set from the build.xml file.
Add the following CSS to your style sheet to allow your style to accommodate a change in the RichFaces panel. Failing to add this code will mean that, in any page created by generate-entities, the search criteria block will bleed into the results table. 
.rich-stglpanel-body {
        overflow: auto;
        }