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
$class
property 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.xml
file, with a component path that matches theMonitoredDataSource
component’s originaldataSource
property 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.