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:
Substitutes all occurrences of
(DynamoHttpServletRequest)[someExpression]withServletUtil.getDynamoRequest([someExpression]), and any occurrences of(DynamoHttpServletResponse)[someExpression]with(ServletUtil.getDynamoResponse)[someExpression].Looks for instances of double quotes nested within double quotes, or single quotes within single quotes, and replaces the outer quotes with single quotes or double quotes.
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:
The
$classproperty is set toatg.nucleus.JNDIReference.There is only one other property,
JNDIName, which is set to the JNDI name of the datasource entry in theatg-das-datasources-ds.xmlfile, with a component path that matches theMonitoredDataSourcecomponent’s originaldataSourceproperty value.
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:
migrateToJBossdynamoRootDir[-ddestinationDir]
[-jjbossServerDir] [-v]
It takes the following parameters:
dynamoRootDir—Required. The root of the ATG application to be migrated.destinationDir—Optional. This directory will contain a copy of the source directory except for those files which have been modified for the migration. If this parameter is not specified, then a default destination directory will be created to hold the migrated files and copies of the unaltered files. The default directory will be the name of the root directory followed by the string “_migration”. If a directory/file by that name already exists, then an integer will be tacked on the end of the name and incremented until a unique name is found.jbossServerDir—Optional. The location of the JBoss server deploy directory. This is needed to correctly save the generated JBoss datasource file. If you do not supply this parameter, the JBoss datasource file is saved to the root level of thedestinationDir, and must be manually copied to the correct JBoss server directory.
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.
