GlassFish - World's first Java EE 7 Application Server


An Overview of the Migration Tool for Project GlassFish

You use the Migration Tool to migrate applications from competitive application servers to GlassFish. You can use this tool to migrate the applications that do not deploy successfully after upgrading from an older version of Application Server. This tool works on the input archive or source code to translate the runtime deployment descriptors from the source application server format to generate runtime deployment descriptors that are compliant with the latest version. It also parses the JSP and Java source code files (in case of source code input) and provides runtime support for certain custom JSP tags and proprietary APIs.

Supported Source Application Servers

The Migration Tool, which functions as a stand-alone Java application, automates the migration of Java EE applications from the following source platforms to GlassFish:

  • Sun Java System Application Server 7.x, 8.x,
  • Sun ONE Application Server 6.x
  • J2EE Reference Implementation 1.3/1.4
  • BEA WebLogic Application Server 5.1/6.0/6.1/8.1/9.0
  • WebSphere Application Server 4.0/5.1
  • JBoss Application Server 3.0
  • Tomcat Web Server 4.1.12

How Migration Works

Although Java EE specifications broadly cover application requirements, it is an evolving standard. The specification either does not cover some aspects of applications, or leaves implementation details as the responsibility of product providers.
Product implementation-dependent aspects are manifested as differences in application server configurations and differences in the deployment of Java EE modules on application servers. Available configuration and deployment tools for use with particular application server products also contribute to differences in product implementation.
The evolutionary nature of the specification itself presents challenges to product providers. Each component APIs may evolve separately, leading to a varying degree of product conformance.
Moreover, product providers usually bundle additional features and services with their products. These features are available as custom JSP tags or proprietary Java API libraries. Using such proprietary features renders these applications non-portable.
The Migration Tool can migrate both Java EE application source and archive. For application archive, if the source is not available, the tool migrates only the deployment descriptors. If the application source is given as input, the tool attempts to migrate the following source files:

  • Configuration Parameter File(s))
  • Deployment Descriptor (XML) Files
  • JSP Source Files
  • Java Source Files

Different migration strategies need to be adopted for each category of files, since each addresses different aspects of the application. The Migration Tool observes the following general guidelines for each file category while migrating the files.

Configuration Parameter File(s)

The Migration Tool detects configuration parameter file(s) based on the name of the file (specified as input to the Migration Tool); for example weblogic.properties, server-cfg.xml, and so on. The configuration of an application server includes settings for parameters such as the location of installation directories, the directory paths to HTML documents, JSPs, servlets, and enterprise beans. Application server configuration also includes parameters related to performance, pooling, clustering, and database connectivity, among others.
Although the information in configuration parameter specifications is similar across products, the format used to specify parameters is product-specific.
Since the target Application Server installation most likely has been carefully configured, the Migration Tool does not overwrite configuration parameters for the target. The only parameter that can be manipulated without incident in the target is JDBC sources. Therefore, the Migration Tool automatically migrates only the JDBC sources parameter. However, the Migration Tool also generates a file containing information for other relevant types of configuration parameters. The system administrator needs to manually configure these parameters in the target Application Server installation.
If message-driven beans are present in any of the JAR files, the Migration Tool generates JMS-related scripts. These JMS scripts are capable of creating the JMS resources at the target server. The tool-generated JMS scripts are buildjms.sh (Solaris) and buildjms.cmd (Windows). The tool generates similar scripts for creating the JMS connection factory resources at the target server.

Deployment Descriptor (XML) Files

Deployment is accomplished by specifying deployment descriptors (DDs) for enterprise beans (EJB JAR files), front-end web components (WAR files), and enterprise applications (EAR files). The Migration Tool detects the DD files by their doctype and/or file name (specified as input to the Migration Tool). A few examples are ejb-jar.xml, weblogic-ejb-jar.xml, ibm-bnd.xmi, and so on. Deployment descriptors are used to resolve all external dependencies of the Java EE components or applications.
The Java EE specification for deployment descriptors is common across all application server products. However, the specification leaves several deployment aspects of components pertaining to an application dependent on product implementation. These aspects appear as additional product-specific DD files.
The Migration Tool automatically migrates information from the source product-specific DD files to the application server-specific DD files.

JSP Source Files

The Migration Tool detects JSP files based on the .jsp extension of the file names (specified as input to the Migration Tool). JSP files are used to write the presentation layer (front-end) for the applications.
Java EE specifies how to extend JSP through adding custom tags. Product vendors may include custom JSP extensions in their products, simplifying some tasks for developers. However, using proprietary custom tags results in non-portable JSP files. Additionally, since JSP can invoke methods defined in other Java source files as well, it raises the same non-portability issues as for Java source files.
The Migration Tool comes bundled with a run-time Java library, which provides the functionality of custom JSP tags found in source products on the application server. Additionally, invoking non-portable Java methods is handled in the same manner as for Java source files, described in the following section.

Java Source Files

The Java source files can be servlets, enterprise beans, or other helper classes. The servlets and enterprise beans can directly invoke standard Java EE services. They can also invoke methods defined in helper classes. The Migration Tool detects the Java source files based on the .java extension of the file names (specified as input to the tool). Java source files may be enterprise beans that are used to encode the business layer of applications.
Servlets are typically used as presentation layer (front-end) for the applications. However, servlets can contain business logic as well.
Vendors may bundle several services and proprietary Java APIs with their products. Using proprietary Java APIs is the major source of non-portable applications. Since Java EE is an evolving standard, different products may support different versions of Java EE component APIs. This is another aspect that migration must address.
The Migration Tool comes bundled with a run-time Java library that provides the functionality for (within a select subset of) proprietary Java APIs. The run-time Java library has been written to preserve the actual interface. To cater to different products and product versions, the package name of proprietary APIs is prefixed with the product name and version. The Migration Tool includes a Java parser, which detects the presence of proprietary Java APIs and prepends the appropriate prefix to their package names. Therefore, while running on the application server, the calls are made to the runtime Java library. The JSP files in the application are also processed with this same Java parser. The parser is targeted to detect and bridge Java EE component version mismatches.

Note - The current Migration Tool implementation has only limited support for bridging such differences.

Previous Next