Procedure 3.25. Migrate Seam 2.2 Archives

1. Update the datasource configuration

   Some Seam 2.2 examples use the default JDBC datasource named java:/ExampleDS. This default datasource has changed in JBoss EAP 6 to java:jboss/datasources/ExampleDS. If your application uses the example database, you can do one of the following:

   • If you want to use the example database that ships with JBoss EAP 6, modify the META-INF/persistence.xml file to replace the existing jta-data-source element with the example database datasource JNDI name:

     <!-- <jta-data-source>java:/ExampleDS</jta-data-source> -->
     <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source>

   • If you prefer to keep your existing database, you can add the datasource definition to the EAP_HOME/standalone/configuration/standalone.xml file.

     Important

     You must stop the server before editing the server configuration file for your change to be persisted on server restart.
     The following definition is a copy of the default HSQL datasource defined in JBoss EAP 6:

     <datasource name="ExampleDS" jndi-name="java:/ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
        <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
        <driver>h2</driver>
        <security>
           <user-name>sa</user-name>
           <password>sa</password>
        </security>
     </datasource>

   • You can also add the datasource definition using the Management CLI command line interface. The following is an example of the syntax you must use to add a datasource. The "\" at the end of line indicates the continuation of the command on the following line.

     Example 3.3. Example of syntax to add the datasource definition

     $ EAP_HOME/bin/jboss-cli --connect 
     [standalone@localhost:9999 /] data-source add --name=ExampleDS --jndi-name=java:/ExampleDS \ 
           --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 --driver-name=h2 \ 
           --user-name=sa --password=sa
     

   For more information on how to configure a datasource, see Section 3.1.6.2, “Update the DataSource Configuration”.

2. Add any required dependencies

   Because Seam 2.2 applications use JSF 1.2, you need to add dependencies for the JSF 1.2 modules and exclude the JSF 2.0 modules. To accomplish this, you need to create a jboss-deployment-structure.xml file in the EAR's META-INF/ directory that contains the following data:

   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
     <deployment>
         <dependencies>
           <module name="javax.faces.api" slot="1.2" export="true"/>
                 <module name="com.sun.jsf-impl" slot="1.2" export="true"/>
         </dependencies>
     </deployment>
     <sub-deployment name="jboss-seam-booking.war">
       <exclusions>
           <module name="javax.faces.api" slot="main"/>
                 <module name="com.sun.jsf-impl" slot="main"/>
         </exclusions>
         <dependencies>
           <module name="javax.faces.api" slot="1.2"/>
                 <module name="com.sun.jsf-impl" slot="1.2"/>
         </dependencies>
     </sub-deployment>
   </jboss-deployment-structure>

   If your application uses any third-party logging frameworks you need to add those dependencies as described here: Section 3.1.4.1, “Modify Logging Dependencies”.

3. If your application uses Hibernate 3.x, first try to run the application using the Hibernate 4 libraries

   If your application does not use the Seam Managed Persistence Context, Hibernate search, validation, or other features that have changed with Hibernate 4, you may be able to run with the Hibernate 4 libraries. However, if you see ClassNotFoundExceptions or ClassCastExceptions that point to Hibernate classes, or see errors similar to the following, you may have to follow the instructions in the next step and modify the application to use Hibernate 3.3 libraries.

           Caused by: java.lang.LinkageError: loader constraint violation in interface itable initialization: when resolving method "org.jboss.seam.persistence.HibernateSessionProxy.getSession(Lorg/hibernate/EntityMode;)Lorg/hibernate/Session;" the class loader (instance of org/jboss/modules/ModuleClassLoader) of the current class, org/jboss/seam/persistence/HibernateSessionProxy, and the class loader (instance of org/jboss/modules/ModuleClassLoader) for interface org/hibernate/Session have different Class objects for the type org/hibernate/Session used in the signature
   

4. Copy dependent archives from outside frameworks or other locations

   If your application uses Hibernate 3.x and you are not able to use Hibernate 4 successfully with your application, you will need to copy the Hibernate 3.x JARs into the /lib directory and exclude the Hibernate module in the deployments section of the META-INF/jboss-deployment-structure.xml as follows:

   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
    <deployment>
      <exclusions>
        <module name="org.hibernate"/>
      </exclusions>
    <deployment>
   </jboss-deployment-structure>

   There are additional steps you must take when you bundle Hibernate 3.x with your application. For more information, see Section 3.2.2.2, “Configure Changes for Applications That Use Hibernate and JPA”.

5. Debug and resolve Seam 2.2 JNDI errors

   When you migrate a Seam 2.2 application, you may see javax.naming.NameNotFoundException errors in the log like the following:

   javax.naming.NameNotFoundException: Name 'jboss-seam-booking' not found in context ''

   If you don't want to modify JNDI lookups throughout the code, you can modify the application's components.xml file as follows:

   1. Replace the existing core-init element

      First, you need to replace the existing core-init element as follows:

      <!-- <core:init jndi-pattern="jboss-seam-booking/#{ejbName}/local" debug="true" distributable="false"/>   -->
      <core:init debug="true" distributable="false"/>
      

   2. Find the JNDI binding INFO messages in the server log

      Next, find the JNDI binding INFO messages that are printed in the server log when the application is deployed. The JNDI binding messages should look similar to this:

      INFO org.jboss.as.ejb3.deployment.processors.EjbJndiBindingsDeploymentUnitProcessor (MSC service thread 1-1) JNDI bindings for session bean
      named AuthenticatorAction in deployment unit subdeployment "jboss-seam-booking.jar" of deployment "jboss-seam-booking.ear" are as follows:
          java:global/jboss-seam-booking/jboss-seam-booking.jar/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
          java:app/jboss-seam-booking.jar/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
          java:module/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
          java:global/jboss-seam-booking/jboss-seam-booking.jar/AuthenticatorAction
          java:app/jboss-seam-booking.jar/AuthenticatorAction
          java:module/AuthenticatorAction
      

   3. Add component elements

      For each JNDI binding INFO message in the log, add a matching component element to the components.xml file:

      <component class="org.jboss.seam.example.booking.AuthenticatorAction" jndi-name="java:app/jboss-seam-booking.jar/AuthenticatorAction" />

   For more information on how to debug and resolve migration issues, see Section 4.2.1, “Debug and Resolve Migration Issues”.
   For a list of known migration issues with Seam 2 archives, see Section 3.2.13.2, “Seam 2.2 Archive Migration Issues”.