Chapter 4. Tools and Tips

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 EAP 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 EAP 6, see: Section 4.3.1, “Review Migration of Example Applications”.
Report a bug

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.
Section 4.1.3, “Use Tattletale to Find Application Dependencies”
IronJacamar Migration Tool
In JBoss EAP 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 EAP 6.
Section 4.1.6, “Use the IronJacamar Tool to Migrate Datasource and Resource Adapter Configurations”
Report a bug

4.1.3. Use Tattletale to Find Application Dependencies

Summary

Due to the modular class loading changes in JBoss EAP 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 EAP 6. Tattletale's "JBoss AS 7" 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

  1. Section 4.1.4, “Download and Install Tattletale”
  2. Section 4.1.5, “Create and Review the Tattletale Report”

Note

Tattletale is a 3rd party tool and not supported as part of JBoss 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.
Report a bug

4.1.4. Download and Install Tattletale

Procedure 4.2. Download and Install Tattletale

  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.
Report a bug

4.1.5. Create and Review the Tattletale Report

  1. Create the Tattletale report by issuing the command: java -jar TATTLETALE_HOME/tattletale.jar APPLICATION_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 AS 7" 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.
Report a bug

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

Procedure 4.3. Install and run the IronJacamar Migration tool

  1. Section 4.1.7, “Download and Install the IronJacamar Migration Tool”
  2. Section 4.1.8, “Use the IronJacamar Migration Tool to Convert a Datasource Configuration File”
  3. Section 4.1.9, “Use the IronJacamar Migration Tool to Convert a Resource Adapter Configuration File”

Note

The IronJacamar Migration tool is a 3rd party tool and not supported as part of JBoss EAP 6. For more information about IronJacamar, go to http://www.ironjacamar.org/. For the most current documentation on how to install and use this tool, go to http://www.ironjacamar.org/documentation.html.
Report a bug

4.1.7. Download and Install the IronJacamar Migration Tool

Note

The migration tool is only available in IronJacamar 1.1 version or higher.
  1. Download the IronJacamar 1.1 or greater distribution from here: http://www.ironjacamar.org/download.html/
  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
Report a bug

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

Procedure 4.4. Convert a Datasource Configuration File

  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.xmlnew-datasource-config.xml
    • For Microsoft Windows: ./converter.bat -ds jboss-seam-booking-ds.xmlnew-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.1"><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 EAP 5.x: 
    <?xml version="1.0" encoding="UTF-8"?>
<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 EAP 6 is to use a <driver> element. Here is the resulting XML in the JBoss EAP 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.1">
  <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>
Report a bug

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

  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.xmlnew-adapter-config.xml
    • For Microsoft Windows: ./converter.bat -ra mttestadapter-ds.xmlnew-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.1"> 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 EAP 5.x TestSuite: 
    <?xml version="1.0" encoding="UTF-8"?>
  <!-- ==================================================================== -->
  <!-- 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 EAP 6 configuration file with modifications to the <class-name> element value: 
    <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
  <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>
Report a bug