Chapter 4. Tools and Tips

4.1. Resources to Assist With Migration
4.1.1. Resources to Assist in Your Migration
4.1.2. Become Familiar with Tools That Can Assist with the Migration
4.1.3. Use Tattletale to Find Application Dependencies
4.1.4. Download and Install Tattletale
4.1.5. Create and Review the Tattletale Report
4.1.6. Use the IronJacamar Tool to Migrate Datasource and Resource Adapter Configurations
4.1.7. Download and Install the IronJacamar Migration Tool
4.1.8. Use the IronJacamar Migration Tool to Convert a Datasource Configuration File
4.1.9. Use the IronJacamar Migration Tool to Convert a Resource Adapter Configuration File
4.2. Debug Migration Issues
4.2.1. Debug and Resolve Migration Issues
4.2.2. Debug and Resolve ClassNotFoundExceptions and NoClassDefFoundErrors
4.2.3. Find the JBoss Module Dependency
4.2.4. Find the JAR in the Previous Install
4.2.5. Debug and Resolve ClassCastExceptions
4.2.6. Debug and Resolve DuplicateServiceExceptions
4.2.7. Debug and Resolve JBoss Seam Debug Page Errors
4.3. Review Migration of Example Applications
4.3.1. Review Migration of Example Applications
4.3.2. Migrate the Seam 2.2 JPA Example to JBoss Enterprise Application Platform 6
4.3.3. Migrate the Seam 2.2 Booking Example to JBoss Enterprise Application Platform 6
4.3.4. Migrate the Seam 2.2 Booking Archive to JBoss Enterprise Application 6: Step-By-Step Instructions
4.3.5. Build and Deploy the JBoss Enterprise Application Platform 5.1 Version of the Seam 2.2 Booking Application
4.3.6. Debug and Resolve Seam 2.2 Booking Archive Deployment Errors and Exceptions
4.3.7. Debug and Resolve Seam 2.2 Booking Archive Runtime Errors and Exceptions
4.3.8. Review a Summary of the Changes Made When Migrating the Seam 2.2 Booking Application

4.1. Resources to Assist With Migration

4.1.1. Resources to Assist in Your Migration

The following is a list of resources that may be of help when migrating an application to JBoss Enterprise Application Platform 6.
Tools
There are several tools that help automate some of the configuration changes. For more information, see: Section 4.1.2, “Become Familiar with Tools That Can Assist with the Migration”.
Debugging Tips
For a list of the most common causes and resolutions of issues and errors you may see when you migrate your application, see: Section 4.2.1, “Debug and Resolve Migration Issues”.
Example migrations
For examples of applications that have been migrated to JBoss Enterprise Application Platform 6, see: Section 4.3.1, “Review Migration of Example Applications”.

4.1.2. Become Familiar with Tools That Can Assist with the Migration

Summary
There are some tools that can assist you in your migration efforts. The following is a list of these tools along with a description of what they do.
Tattletale
With the change to modular class loading, you need to find and rectify application dependencies. Tattletale can help you identify dependent module names and generate the configuration XML for your application.
IronJacamar Migration Tool
In JBoss Enterprise Application Platform 6, datasources and resource adapters are no longer configured in a separate file. They are now defined in the server configuration file and use new schemas. The IronJacamar Migration Tool can help convert the old configuration into the format expected by JBoss Enterprise Application Platform 6.

4.1.3. Use Tattletale to Find Application Dependencies

Summary
Due to the modular class loading changes in JBoss Enterprise Application Platform 6, you might see ClassNotFoundException or ClassCastException traces in the JBoss log when you migrate your application. To resolve these errors, you need to find the JARs that contain the classes specified by the exceptions.
Tattletale is an excellent 3rd party tool that recursively scans your application and provides detailed reports about its contents. Tattletale 1.2.0.Beta2 or later contains additional support to help with the new JBoss Modules class loading used in JBoss Enterprise Application Platform 6. Tattletale's "JBoss EAP 6" report can be used to automatically identify and generate dependent module names to include your application's jboss-deployment-structure.xml file.

Procedure 4.1. Install and run Tattletale to find application dependencies

Note

Tattletale is a 3rd party tool and not supported as part of JBoss Enterprise Application Platform 6. For the most current documentation on how to install and use Tattletale, go to the Tattletale web site at http://www.jboss.org/tattletale.

4.1.4. Download and Install Tattletale

Procedure 4.2. 

  1. Download Tattletale version 1.2.0.Beta2 or newer from http://sourceforge.net/projects/jboss/files/JBoss%20Tattletale.
  2. Unzip the file into the directory of your choice.
  3. Modify the TATTLETALE_HOME/jboss-tattletale.properties file by doing the following:
    1. Add ee6 and as7 to the profiles property.
      profiles=java5, java6, ee6, as7
    2. Uncomment the scan and reports properties.

Note

Tattletale is a 3rd party tool and not supported as part of JBoss Enterprise Application Platform 6. For the most current documentation on how to install and use Tattletale, go to the Tattletale web site at http://www.jboss.org/tattletale.

4.1.5. Create and Review the Tattletale Report

Procedure 4.3. 

  1. Create the Tattletale report by issuing the command: java -jar TATTLETALE_HOME/tattletale.jarAPPLICATION_ARCHIVEOUTPUT_DIRECTORY
    For example: java -jar tattletale-1.2.0.Beta2/tattletale.jar applications/jboss-seam-booking.ear output-results/
  2. In a browser, open the OUTPUT_DIRECTORY/index.html file and click on "JBoss EAP 6" under the "Reports" section.
    1. The column on the left lists the archives used by the application. Click on the ARCHIVE_NAME link to view details about the archive, such as its location, manifest information, and classes it contains.
    2. The jboss-deployment-structure.xml link in the column on the right shows how to specify the module dependency for the archive named in the left column. Click on this link to see how to define the deployment dependency module information for this archive.

Note

Tattletale is a 3rd party tool and not supported as part of EAP 6. For the most current documentation on how to install and use Tattletale, go to the Tattletale web site at http://www.jboss.org/tattletale.

4.1.6. Use the IronJacamar Tool to Migrate Datasource and Resource Adapter Configurations

Summary
In previous versions of the application server, datasources and resource adapters were configured and deployed using a file with a suffix of *-ds.xml. The IronJacamar 1.1 distribution contains a migration tool that can be used to convert these configuration files into the format expected by JBoss Enterprise Application Platform 6. The tool parses the source configuration file from the previous release, then creates and writes the XML configuration to an output file in the new format. This XML can then be copied and pasted under the correct subsystem in the JBoss Enterprise Application Platform 6 server configuration file. This tool makes a best effort to convert old attributes and elements into the new format, however, it may be necessary to make additional modifications to the generated file.

Note

The IronJacamar Migration tool is a 3rd party tool and not supported as part of JBoss Enterprise Application Platform 6. For more information about IronJacamar, go to http://www.jboss.org/ironjacamar. For the most current documentation on how to install and use this tool, go to http://docs.jboss.org/ironjacamar/userguide/1.1/en-US/html/tools.html#tools_migration.

4.1.7. Download and Install the IronJacamar Migration Tool

Note

The migration tool is only available in IronJacamar 1.1 version or higher.

Procedure 4.5. 

  1. Download the IronJacamar 1.1 or greater distribution from here: http://www.jboss.org/ironjacamar/downloads/
  2. Unzip the downloaded file into a directory of your choice.
  3. Find the converter script in the IronJacamar distribution.
    • The Linux script is located here: IRONJACAMAR_HOME/doc/as/converter.sh
    • The Windows batch file is located here: IRONJACAMAR_HOME/doc/as/converter.bat

Note

The IronJacamar Migration tool is a 3rd party tool and not supported as part of JBoss Enterprise Application Platform 6. For more information about IronJacamar, go to http://www.jboss.org/ironjacamar. For the most current documentation on how to install and use this tool, go to http://docs.jboss.org/ironjacamar/userguide/1.1/en-US/html/tools.html#tools_migration.

4.1.8. Use the IronJacamar Migration Tool to Convert a Datasource Configuration File

Procedure 4.6. 

  1. Open a command line and navigate to the IRONJACAMAR_HOME/docs/as/ directory.
  2. Run the converter script by typing the following command:
    • For Linux: ./converter.sh -ds SOURCE_FILE TARGET_FILE
    • For Microsoft Windows: ./converter.bat -ds SOURCE_FILE TARGET_FILE
    The SOURCE_FILE is the datasource -ds.xml file from the previous release. The TARGET_FILE contains the new configuration.
    For example, to convert the jboss-seam-booking-ds.xml datasource configuration file located in the current directory, you would type:
    • For Linux: ./converter.sh -ds jboss-seam-booking-ds.xml new-datasource-config.xml
    • For Microsoft Windows: ./converter.bat -ds jboss-seam-booking-ds.xml new-datasource-config.xml
    Note that the parameter for datasource conversion is -ds.
  3. Copy the <datasource> element from the target file and paste it into the server configuration file under the <subsystem xmlns="urn:jboss:domain:datasources:1.0"><datasources> element.

    Important

    You must stop the server before editing the server configuration file for your change to be persisted on server restart.
    • If you are running in a managed domain, copy the XML into the EAP_HOME/domain/configuration/domain.xml file.
    • If you are running as a standalone server, copy the XML into the EAP_HOME/standalone/configuration/standalone.xml file.
  4. Modify the generated XML in the new configuration file.
    Here is an example of the jboss-seam-booking-ds.xml datasource configuration file for the Seam 2.2 Booking example that shipped with JBoss Enterprise Application Platform 5.x:
    <datasources>
      <local-tx-datasource>
        <jndi-name>bookingDatasource</jndi-name>
        <connection-url>jdbc:hsqldb:.</connection-url>
        <driver-class>org.hsqldb.jdbcDriver</driver-class>
        <user-name>sa</user-name>
        <password></password>
      </local-tx-datasource>
    </datasources>
    The following is the configuration file that was generated by running the converter script. The generated file contains a <driver-class> element. The preferred way to define the driver class in JBoss Enterprise Application Platform 6 is to use a <driver> element. Here is the resulting XML in the JBoss Enterprise Application Platform 6 configuration file with modifications to comment out the <driver-class> element and add the corresponding <driver> element:
    <subsystem xmlns="urn:jboss:domain:datasources:1.0">
      <datasources>
        <datasource enabled="true" jndi-name="java:jboss/datasources/bookingDatasource" jta="true"
                pool-name="bookingDatasource" use-ccm="true" use-java-context="true">
          <connection-url>jdbc:hsqldb:.</connection-url>
          <!-- Comment out the following driver-class element 
               since it is not the preferred way to define this.
               <driver-class>org.hsqldb.jdbcDriver</driver-class>     -->
          <transaction-isolation>TRANSACTION_NONE</transaction-isolation>
          <pool>
            <prefill>false</prefill>
            <use-strict-min>false</use-strict-min>
            <flush-strategy>FailingConnectionOnly</flush-strategy>
          </pool>
          <security>
            <user-name>sa</user-name>
            <password/>
          </security>
          <validation>
            <validate-on-match>false</validate-on-match>
            <background-validation>false</background-validation>
            <use-fast-fail>false</use-fast-fail>
          </validation>
          <timeout/>
          <statement>
            <track-statements>false</track-statements>
          </statement>
        </datasource>
        <drivers>
          <!-- The following driver element was not in the 
         XML target file. It was created manually. -->
          <driver name="h2" module="com.h2database.h2">
            <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
            </driver>
          </drivers>
      </datasources>
    </subsystem>
    

Note

The IronJacamar Migration tool is a 3rd party tool and is not supported as part of JBoss Enterprise Application Platform 6. For more information about IronJacamar, go to http://www.jboss.org/ironjacamar. For the most current documentation on how to install and use this tool, go to http://docs.jboss.org/ironjacamar/userguide/1.1/en-US/html/tools.html#tools_migration.

4.1.9. Use the IronJacamar Migration Tool to Convert a Resource Adapter Configuration File

Procedure 4.7. 

  1. Open a command line and navigate to the IRONJACAMAR_HOME/docs/as/ directory.
  2. Run the converter script by typing the following command:
    • For Linux: ./converter.sh -ra SOURCE_FILE TARGET_FILE
    • For Microsoft Windows: ./converter.bat -ra SOURCE_FILE TARGET_FILE
    The SOURCE_FILE is the resource adapter -ds.xml file from the previous release. The TARGET_FILE contains the new configuration.
    For example, to convert the mttestadapter-ds.xml resource adapter configuration file located in the current directory, you would type:
    • For Linux: ./converter.sh -ra mttestadapter-ds.xml new-adapter-config.xml
    • For Microsoft Windows: ./converter.bat -ra mttestadapter-ds.xml new-adapter-config.xml
    Note that the parameter for resource adapter conversion is -ra.
  3. Copy the entire <resource-adapters> element from the target file and paste it into the server configuration file under the <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"> element.

    Important

    You must stop the server before editing the server configuration file for your change to be persisted on server restart.
    • If you are running in a managed domain, copy the XML into the EAP_HOME/domain/configuration/domain.xml file.
    • If you are running as a standalone server,copy the XML into the EAP_HOME/standalone/configuration/standalone.xml file.
  4. Modify the generated XML in the new configuration file.
    Here is an example of the mttestadapter-ds.xml resource adapter configuration file from the JBoss Enterprise Application Platform 5.x TestSuite:
      <!-- ==================================================================== -->
      <!-- ConnectionManager setup for jboss test adapter                       -->
      <!-- Build jmx-api (build/build.sh all) and view for config documentation -->
      <!-- ==================================================================== -->
    <connection-factories>
      <tx-connection-factory>
        <jndi-name>JBossTestCF</jndi-name>
        <xa-transaction/>
        <rar-name>jbosstestadapter.rar</rar-name>
        <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
        <config-property name="IntegerProperty" type="java.lang.Integer">2</config-property>
        <config-property name="BooleanProperty" type="java.lang.Boolean">false</config-property>
        <config-property name="DoubleProperty" type="java.lang.Double">5.5</config-property>
        <config-property name="UrlProperty" type="java.net.URL">http://www.jboss.org</config-property>
        <config-property name="sleepInStart" type="long">200</config-property>
        <config-property name="sleepInStop" type="long">200</config-property>
      </tx-connection-factory>
      <tx-connection-factory>
        <jndi-name>JBossTestCF2</jndi-name>
        <xa-transaction/>
        <rar-name>jbosstestadapter.rar</rar-name>
        <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
        <config-property name="IntegerProperty" type="java.lang.Integer">2</config-property>
        <config-property name="BooleanProperty" type="java.lang.Boolean">false</config-property>
        <config-property name="DoubleProperty" type="java.lang.Double">5.5</config-property>
        <config-property name="UrlProperty" type="java.net.URL">http://www.jboss.org</config-property>
        <config-property name="sleepInStart" type="long">200</config-property>
        <config-property name="sleepInStop" type="long">200</config-property>
      </tx-connection-factory>
      <tx-connection-factory>
        <jndi-name>JBossTestCFByTx</jndi-name>
        <xa-transaction/>
        <track-connection-by-tx>true</track-connection-by-tx>
        <rar-name>jbosstestadapter.rar</rar-name>
        <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
        <config-property name="IntegerProperty" type="java.lang.Integer">2</config-property>
        <config-property name="BooleanProperty" type="java.lang.Boolean">false</config-property>
        <config-property name="DoubleProperty" type="java.lang.Double">5.5</config-property>
        <config-property name="UrlProperty" type="java.net.URL">http://www.jboss.org</config-property>
        <config-property name="sleepInStart" type="long">200</config-property>
        <config-property name="sleepInStop" type="long">200</config-property>
      </tx-connection-factory>
    </connection-factories>
    The following is the configuration file that was generated by running the converter script. Replace the class-name attribute value "FIXME_MCF_CLASS_NAME" in the generated XML with the correct class name of the managed connection factory, in this case, "org.jboss.test.jca.adapter.TestManagedConnectionFactory". Here is the resulting XML in the JBoss Enterprise Application Platform 6 configuration file with modifications to the <class-name> element value:
    <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0">
      <resource-adapters>
        <resource-adapter>
          <archive>jbosstestadapter.rar</archive>
          <transaction-support>XATransaction</transaction-support>
          <connection-definitions>
      <!-- Replace the "FIXME_MCF_CLASS_NAME" class-name value with the correct class name
      <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true"
        jndi-name="java:jboss/JBossTestCF" pool-name="JBossTestCF" 
        use-ccm="true" use-java-context="true"> -->
      <connection-definition 
        class-name="org.jboss.test.jca.adapter.TestManagedConnectionFactory" 
        enabled="true"
        jndi-name="java:jboss/JBossTestCF" pool-name="JBossTestCF" 
        use-ccm="true" use-java-context="true">
        <config-property name="IntegerProperty">2</config-property>
        <config-property name="sleepInStart">200</config-property>
        <config-property name="sleepInStop">200</config-property>
        <config-property name="BooleanProperty">false</config-property>
        <config-property name="UrlProperty">http://www.jboss.org</config-property>
        <config-property name="DoubleProperty">5.5</config-property>
        <pool>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
        </pool>
        <security>
          <application/>
        </security>
        <timeout/>
        <validation>
          <background-validation>false</background-validation>
          <use-fast-fail>false</use-fast-fail>
        </validation>
      </connection-definition>
          </connection-definitions>
        </resource-adapter>
        <resource-adapter>
          <archive>jbosstestadapter.rar</archive>
          <transaction-support>XATransaction</transaction-support>
          <connection-definitions>
      <!-- Replace the "FIXME_MCF_CLASS_NAME" class-name value with the correct class name
       <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true"
        jndi-name="java:jboss/JBossTestCF2" pool-name="JBossTestCF2" 
        use-ccm="true" use-java-context="true"> -->
      <connection-definition 
        class-name="org.jboss.test.jca.adapter.TestManagedConnectionFactory" 
        enabled="true"
        jndi-name="java:jboss/JBossTestCF2" pool-name="JBossTestCF2" 
        use-ccm="true" use-java-context="true">
        <config-property name="IntegerProperty">2</config-property>
        <config-property name="sleepInStart">200</config-property>
        <config-property name="sleepInStop">200</config-property>
        <config-property name="BooleanProperty">false</config-property>
        <config-property name="UrlProperty">http://www.jboss.org</config-property>
        <config-property name="DoubleProperty">5.5</config-property>
        <pool>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
        </pool>
        <security>
          <application/>
        </security>
        <timeout/>
        <validation>
          <background-validation>false</background-validation>
          <use-fast-fail>false</use-fast-fail>
        </validation>
      </connection-definition>
          </connection-definitions>
        </resource-adapter>
        <resource-adapter>
          <archive>jbosstestadapter.rar</archive>
          <transaction-support>XATransaction</transaction-support>
          <connection-definitions>
      <!-- Replace the "FIXME_MCF_CLASS_NAME" class-name value with the correct class name
      <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true"
         jndi-name="java:jboss/JBossTestCFByTx" pool-name="JBossTestCFByTx" 
         use-ccm="true" use-java-context="true"> -->
      <connection-definition 
        class-name="org.jboss.test.jca.adapter.TestManagedConnectionFactory" 
        enabled="true"
        jndi-name="java:jboss/JBossTestCFByTx" pool-name="JBossTestCFByTx" 
        use-ccm="true" use-java-context="true">
        <config-property name="IntegerProperty">2</config-property>
        <config-property name="sleepInStart">200</config-property>
        <config-property name="sleepInStop">200</config-property>
        <config-property name="BooleanProperty">false</config-property>
        <config-property name="UrlProperty">http://www.jboss.org</config-property>
        <config-property name="DoubleProperty">5.5</config-property>
        <pool>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
        </pool>
        <security>
          <application/>
        </security>
        <timeout/>
        <validation>
          <background-validation>false</background-validation>
          <use-fast-fail>false</use-fast-fail>
        </validation>
      </connection-definition>
          </connection-definitions>
        </resource-adapter>
      </resource-adapters>
    </subsystem>
    

Note

The IronJacamar Migration tool is a 3rd party tool and is not supported as part of JBoss Enterprise Application Platform 6. For more information about IronJacamar, go to http://www.jboss.org/ironjacamar. For the most current documentation on how to install and use this tool, go to http://docs.jboss.org/ironjacamar/userguide/1.1/en-US/html/tools.html#tools_migration.