The JBoss Migration Tool is a Java application that is invoked through a shell script. The application automatically performs many of the steps required to transform an application that was designed to run on DAS into an application that will run on JBoss. This includes fixing JSP pages, ensuring that applications use JBoss datasources, ensuring that the correct entries are present in web.xml files, and ensuring that all EAR and WAR files are correctly listed in MANIFEST.MF files. The sections that follow outline the work the migration tool performs.

See the Migrating from Dynamo Application Server section of this appendix for additional changes you may want to make in your applications.

Migrating JSPs

The migration tool copies all files in the root directory you specify to the destination directory, and performs the following processing on all files ending in .jsp or .jspf, including those within .jar or .zip files:

Migrating MANIFEST.MF

All ATG modules have a MANIFEST.MF file that describes properties of the module. The ATG-EAR-Module and ATG-War-Module manifest attributes specify any EAR or WAR files that should be started up in JBoss. The migration tool ensures that the MANIFEST.MF for all ATG modules includes references to all EAR and WAR files specified in the J2EEContainer.properties file within the configuration path for a given module.

Migrating web.xml Files

The migration tool searches the specified root directory, including .jar and .zip files, for all web.xml files. For each web.xml file it finds, it makes sure there is an entry for the PageFilter and for the NucleusServlet. If either is missing, the tool adds the entry to the web.xml and saves the modified file to the destination directory. Any web.xml files contained in .jar or .zip files are modified and inserted back into the copy of the jar in the destination directory.

Migrating Datasource Components

The migration tool examines all .properties files, .jar files, and .zip files within the ATG application’s root directory, looking for configuration files that configure a FakeXADataSource or MonitoredDataSource component. It tracks entries found in localconfig directories separately from entries found in other locations. If a FakeXADataSource has any null values, then that component is ignored by the migration tool. If two datasource components have the same name and configuration path, the last one located takes priority.

After all FakeXADataSources and MonitoredDataSources have been accounted for, the migration tool creates an atg-das-datasources-ds.xml file in the specified JBoss server directory. If no JBoss server directory is specified, the atg-das-datasources-ds.xml file is created at the root level of the destination directory.

For each FakeXADataSource found in localconfig, the migration tool creates a corresponding entry in the atg-das-datasources-ds.xml file, giving each entry a unique JNDI name. The tool then goes through the non-localconfig FakeXADataSource components; it adds an entry for each of these to the XML file only if there is no entry in the localconfig map with the same component path.

Note: The migration tool is not XA-datasource aware. When it migrates existing ATG datasources to JBoss, the JBoss datasources are of type <local-tx-datasource>. You should edit your datasources manually to be XA datasources.

The tool then creates new configuration files for each MonitoredDataSource. The configuration files are placed in home/localconfig, using the original component path of the MonitoredDataSource. The new properties files differ from the original MonitoredDataSource properties files in the following ways:

For example, consider the following FakeXADataSource component:

$class=atg.service.jdbc.FakeXADataSource
driver=com.mysql.jdbc.Driver
URL=jdbc:mysql://localhost:3306
user=admin
password=admin

Along with that component is the following MonitoredDataSource component:

$class=atg.service.jdbc.MonitoredDataSource
dataSource=/atg/dynamo/service/jdbc/FakeXADataSource

Having found those two components, the tool would create the following entry in the atg-das-datasources-ds.xml file:

  <local-tx-datasource>
    <jndi-name>generalDS/atg/reporting/datawarehouse/FakeXADataSource
</jndi-name>
    <connection-url>jdbc:mysql://localhost:3306</connection-url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <user-name>admin</user-name>
    <password>admin</password>
    <min-pool-size>10</min-pool-size>
    <max-pool-size>10</max-pool-size>
  </local-tx-datasource>

It also creates the following MonitoredDataSource.properties file in home/localconfig:

$class=atg.nucleus.JNDIReference
JNDIName=java\:/generalDS/atg/dynamo/service/jdbc/FakeXADataSource

Note: For best results, before running the migration tool, make sure that the most current and relevant datasource configs are placed in a localconfig directory. This will give them priority over any other datasource configs that might be found. Also, double-check the generated JBoss datasource XML file to make sure that all the datasource components are correct, and make any corrections if necessary.

Note: Entering passwords in clear text files entails some security risks. Take steps to secure files that contain clear text passwords.

Running the JBoss Migration Tool

The JBoss Migration Tool script is located in your <ATG10dir>\DAF\JBossMigration folder and, has the following usage syntax:

migrateToJBoss dynamoRootDir [-d destinationDir]
 [-j jbossServerDir] [-v]

It takes the following parameters:

Logging in JBoss Migration

As the JBoss Migration tool works, all migration actions are logged to a file in the top level of the migration destination directory. The log file contains entries for any actions that modify the original application, such as rewriting JSPs to not treat the request object as a DynamoHttpServletRequest, or modifying a web.xml to add the PageFilter or NucleusServlet entries.