Overview

JBoss to Geronimo (J2G) is a tool set designed to assist in migrating the sources of an application written for the JBoss application server or written for Java 2 Enterprise Edition (J2EE) to the Apache Geronimo platform.

The components of J2G currently run as command line Eclipse SDK plug-ins to accomplish their tasks.

Disclaimer

While this tool set may be extremely useful in helping someone that is either unfamiliar with JBoss or unfamiliar with Geronimo to convert an application source, experienced developers may find that it is more troublesome than manually doing the entire migration. There is no such thing as a magical fix-everything code converter, it just isn't feasible. In addition to this, BE ABSOLUTELY SURE you have a good backup of the sources that will not be touched by this tool.
In short: It's not our fault if J2G breaks the only source code copy.

Components

J2G consists of three executable utilities. The "Configurator" component, and the three major components, each of which have relatively specific functions, and must be ran in the order as follows.

1. Configurator

To run this component, navigate to bin, and run j2g-configure.cmd

 C:\j2g-conversion-1.0.0-SNAPSHOT>cd bin
 C:\j2g-conversion-1.0.0-SNAPSHOT\bin>j2g-configure.bat
 Copying J2G plugins to c:\.m2\eclipse\eclipse\plugins\ ...
 ..\plugins\org.apache.geronimo.j2g.common_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.descriptors.app_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.descriptors.cmp_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.descriptors.ejb_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.descriptors.web_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.descriptors_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.jasper_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.resources.datasource_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.resources.jms_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.resources.mail_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.resources.security_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.resources_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.sources.dependence_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.sources.environment_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.sources_1.0.0-SNAPSHOT.jar
 ..\plugins\org.apache.geronimo.j2g.util_1.0.0-SNAPSHOT.jar
       16 file(s) copied.
 A backup of your configuration file has been written to c:/.m2/eclipse/eclipse\configuration\config.bak
 Configuration complete.

This will automatically copy the contents of the ./plugins directory to ECLIPSE_HOME/plugins, as well as make changes (or create, if necessary) to ECLIPSE_HOME/configuration/config.ini.

2. Source Identification Tool

This tool parses through source code (.java and .jsp files) recursively in directories passed to it as command line arguments. While doing this, it replaces any JBoss classes and dependencies for which there are Geronimo equivalents. If there is no equivalent, it will alert the user of this issue which must be resolved either through manual creation of a replacement class or rewriting the segment of code dependent on the JBoss class.

3. Descriptors Conversion Tool

This tool converts JBoss specific deployment descriptors and J2EE standard deployment descriptors (if necessary) to their Geronimo equivalents.

4. Resource Conversion Tool

This tool converts JBoss specific resources, such as Java Messaging Services (JMS) Queues, JMS Topics, Java Database Connectivity (JDBC) data sources to their Geronimo equivalents.

Dependencies

The J2G tool set requires at least the following application versions
(these are the versions J2G is known to work on)

• Sun JDK 5.0+ (J2SE 1.5)
• Eclipse SDK 3.3M7 with JDT Core Plug-in
• Apache Geronimo 1.1.1
• Application written for JBoss 3.2 and up or J2EE 1.2 and up.

Environment Variables

The tools in J2G require that the following environment variables be set to the proper locations:

• JAVA_HOME (Location of the JDK)
• ECLIPSE_HOME (Location of the Eclipse SDK)
• WORKSPACE (Location for a temporary eclipse workspace)

Source Identification Tool

Description

The Source Identification Tool should be started first. It scans the sources and identifies files that need to be changed during the migration process. These files include Java classes (.java files), JSPs (.jsp files), files with an overridden JSP file extension, specified with the argument -jspext. (For example: -jspext html for .html files) as well as deployment descriptors (.xml).

In these files, the tool checks for:

• Use of APIs incompatible with Geronimo (e.g. JBoss internal APIs);
• Violation of J2EE naming principles.

When the tool checks for usage of APIs incompatible with Geronimo, these JBoss classes are automatically replaced with Geronimo compatible classes

Any references beyond the table above must be manually corrected so that they are no longer dependent on parts of JBoss. It's important to note that JSP file processing is limited to the identification of problems, and automatic correction is not currently supported.

When the tool validates J2EE naming it detects cases in which a component (a class or JSP) refers to a named object that is not a part of the application being converted (For example: a data source, JMS, or Email provider reference). In simple cases, when a component requests an external resource with a direct, full path and does not have any environment reference, the tool tries to fix this problem automatically by adding the resource reference to the component's deployment descriptor and replaces the direct path with the name of the added reference.

When a source file is changed automatically by the Source Identification Tool, the original version is saved with the .j2g extension and an informational message is printed out. In all other cases, when a problem needs to be fixed manually, the tool simply prints a warning message.

Run the Source Identification Tool

To run this component, execute the following command from the bin directory, with <APPLICATION> representing the path to the application you are converting, and <GERONIMO_HOME> representing the path to Geronimo 1.1.1.

*nix

 ./jsrc2g.sh -src <APPLICATION>/src -web <APPLICATION>/web -geronimo <GERONIMO_HOME>

Windows

 jsrc2g.bat -src <APPLICATION>\src -web <APPLICATION>\web -geronimo <GERONIMO_HOME>

Note: To specify multiple sources for conversion, simply separate them with ,s (commas), as follows.
jsrc2g.cmd -src <APPLICATION>/src,<APPLICATION>/src2,...<APPLICATION>/srcn -web <APPLICATION>/web -geronimo <GERONIMO_HOME>

After the tool runs (which may take a few seconds, depending on system speed and the complexity of the application), it will display all warnings and errors to console output. These messages should be interpreted and corrected as seen fit by the user. Once changes have been made, the sources tool can be ran again to verify correctness.

Descriptors Conversion Tool

Description

The Descriptors Conversion Tool finds and tries to automatically convert the following deployment descriptors so that they are accepted by Geronimo:

Run the Descriptors Conversion Tool

To start the Descriptors Conversion Tool run the following command from the bin directory, again where <APPLICATION> represents the path to the application to be converted

*nix

 ./jdesc2g.sh <APPLICATION>

Windows

 jdesc2g.bat <APPLICATION>

The warnings given in the output of this tool will report only unsupported elements that cannot be automatically converted, and must therefore be manually resolved and converted. This process is heavily dependent on the structure of the application being converted, and is therefore beyond the scope of this document.

Resource Migration Tool

Description

The Resource Migration Tool converts JBoss specific resources to their Geronimo equivalents. It processes the following types of resources:

• JBoss/JCA data source descriptors (*-ds.xml files) defining JDBC connection pools and data sources. Since a data source depends on a database type, the tool performs automatic migration for the following well-known databases
  • DB2
  • Derby
  • Hypersonic
  • Informix
  • Microsoft SQL
  • MySQL
  • Oracle
  • PostgreSQL
  • Other data source definitions must be migrated manually. If a definition contains unknown parameters, the tool will indicate this with a warning message.

• JBoss MBean descriptors (*-service.xml files). Only the following resource definitions will be migrated
  • javax.mail.Session
  • javax.jms.QueueConnectionFactory
  • javax.jms.TopicConnectionFactory
  • javax.transaction.TransactionManager

• JBoss security policy descriptors (login-config.xml) that provide JAAS login module configuration. The tool migrates Role and Policy definitions as well as User and Groups for the following JBoss login modules
  • org.jboss.security.auth.spi.IdentityLoginModule
  • org.jboss.security.auth.spi.UsersRolesLoginModule
  • org.jboss.security.auth.spi.LdapLoginModule
  • org.jboss.security.auth.spi.DatabaseServerLoginModule

Run the Resource Migration Tool

To start the Resource Migration Tool run the following command from the bin directory, again where <APPLICATION> represents the path to the application to be converted

*nix

 ./jres2g.sh <APPLICATION>

Windows

 jres2g.bat <APPLICATION>

The tool will output the name of each resource that is to be migrated, as well as informational, error, and warning messages with associated file names and line numbers. If migration of a resource is completed without errors, the tool will output a success message and generate the migrated resource in the same folder as the original one.

As with the other tools, the Error and Warning messages must be manually corrected to complete the conversion process, again which is heavily application specific and is beyond the scope of this document.

Completion

Once all of the above tools have been properly executed and there are no more errors or warnings, the converted application may now be built for Geronimo. Again, this is something that is extremely application specific and must be completely custom tailored in each individual situation.

After a successful build, the application should be able to be deployed in a running instance of Geronimo 1.1.1 without issue, however if it is not the errors displayed at deployment time must be resolved and the application must be rebuilt.