test

Sun Java System Application Server Enterprise Edition 8.2 Upgrade and Migration Guide

Chapter 3 Migrating J2EE Applications

You use the Migration Tool or the asmigrate command to migrate applications from competitive application servers. You also use this tool to migrate the applications that do not deploy successfully after upgrading from an older version of Sun Java SystemApplication 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.

This chapter addresses the following topics:

Understanding Migration

This section describes the need to migrate J2EE applications and the particular files that must be migrated. Following successful migration, a J2EE application is redeployed to the Application Server.

The following topics are addressed:

J2EE Components and Standards

Sun Java System Application Server 8.2 (hereafter called Application Server) is a J2EE v1.4-compliant server based on the component standards developed by the Java community. By contrast, the Sun Java SystemApplication Server 7 (Application Server 7) is a J2EE v1.3-compliant server and Sun ONE Application Server 6.x (Application Server 6.x) is a J2EE v1.2-compliant server. Between the three J2EE versions, there are considerable differences with the J2EE application component APIs.

The following table characterizes the differences between the component APIs used with the J2EE v1.4-compliant Sun Java System Application Server 8.2, the J2EE v1.3-compliant Sun ONE Application Server 7, and the J2EE v1.2-compliant Sun ONE Application Server 6.x.

Table 3–1 Application Server Version Comparison of APIs for J2EE Components

Component API 

Sun ONE Application Server 6.x 

Sun Java System Application Server 7 

Sun Java System Application Server 8.2 

JDK 

1.2.2 

1.4 

1.4 

Servlet 

2.2 

2.3 

2.4 

JSP 

1.1 

1.2 

2.0 

JDBC 

2.0 

2.0 

2.1, 3.0 

EJB 

1.1 

2.0 

2.0 

JNDI 

1.2 

1.2 

1.2.1 

JMS 

1.0 

1.1 

1.1 

JTA 

1.0 

1.01 

1.01 

J2EE Application Components

J2EE simplifies development of enterprise applications by basing them on standardized, modular components, providing a complete set of services to those components, and handling many details of application behavior automatically, without complex programming. J2EE v1.4 architecture includes several component APIs. Prominent J2EE components include:

J2EE components are packaged separately and bundled into a J2EE application for deployment. Each component, its related files such as GIF and HTML files or server-side utility classes, and a deployment descriptor are assembled into a module and added to the J2EE application. A J2EE application is composed of one or more enterprise bean(s), Web, or application client component modules. The final enterprise solution can use one J2EE application or be made up of two or more J2EE applications, depending on design requirements.

A J2EE application and each of its modules has its own deployment descriptor. A deployment descriptor is an XML document with a .xml extension that describes a component’s deployment settings.

A J2EE application with all of its modules is delivered in an Enterprise Archive (EAR) file. An EAR file is a standard Java Archive (JAR) file with a .ear extension. The EAR file contains EJB JAR files, application client JAR files and/or Web Archive (WAR) files.

For more information on J2EE, see:

Why is Migration Necessary?

Although J2EE specifications broadly cover requirements for applications, they are nonetheless evolving standards. They either do not cover some aspects of applications or leave implementation details to the application providers.

This leads to different implementations of the application servers, also well as difference in the deployment of J2EE components on application servers. The array of available configuration and deployment tools for use with any particular application server product also contributes to the product implementation differences.

The evolutionary nature of the specifications itself presents challenges to application providers. Each of the component APIs are also evolving. This leads to a varying degree of conformance by products. In particular, an emerging product, such as the Application Server, has to contend with differences in J2EE application components, modules, and files deployed on other established application server platforms. Such differences require mappings between earlier implementation details of the J2EE standard, such as file naming conventions, and messaging syntax.

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. Unfortunately, using these proprietary features renders these applications non-portable.

What Needs to be Migrated

The J2EE application consists of the following file categories that need to be migrated:

Deployment descriptors (XML files)

Deployment is accomplished by specifying deployment descriptors for standalone enterprise beans (EJB, JAR files), front-end Web components (WAR files) and enterprise applications (EAR files). Deployment descriptors are used to resolve all external dependencies of the J2EE components or applications. The J2EE 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.

JSP source files

J2EE specifies how to extend JSP by adding extra custom tags. Product vendors include some custom JSP extensions in their products, simplifying some tasks for developers. However, usage of these proprietary custom tags results in non-portability of JSP files. Additionally, JSP can invoke methods defined in other Java source files as well. The JSPs containing proprietary APIs need to be rewritten before they can be migrated.

Java source files

The Java source files can be EJBs, servlets, or other helper classes. The EJBs and servlets can invoke standard J2EE services directly. They can also invoke methods defined in helper classes. Java source files are used to encode the business layer of applications, such as EJBs. Vendors bundle several services and proprietary Java API with their products. The use of proprietary Java APIs is a major source of non-portability in applications. Since J2EE is an evolving standard, different products can support different versions of J2EE component APIs.

Migration Tool and Other Resources

The Migration Tool for Sun Java System Application Server 8.2 (hereafter called Migration Tool) migrates J2EE applications from other server platforms to Sun Java System Application Server 8.2.

The following source platforms are supported for Sun Java System Application Server 8.2:

Migration Tool automates the migration of J2EE applications to Sun Java System Application Server 8.2, without much modification to the source code.

The key features of the tool are:

Download the Migration Tool from the following location:

http://java.sun.com/j2ee/tools/migration/index.html.

The Java Application Verification Kit (AVK) for the Enterprise helps build and test applications to ensure that they are using the J2EE APIs correctly and to migrate to other J2EE compatible application servers using specific guidelines and rules.

Download the Java Application Verification Kit (AVK) from the following location:

http://java.sun.com/j2ee/verified/.

Before Migrating the Application

The Migration tool provides limited support for proprietary APIs and custom JSP tags. The rest of the unsupported API usages show up in the Migration report and need to be manually corrected before you can deploy your application. Therefore, before you start the migration, it is recommended that you run the Application Verification Kit(AVK) to gauge the extent of J2EE compliance of your application.

Before you actually begin the migration process, refer http://java.sun.com/j2ee/tools/migration/doc/prerun.html for information on how to prepare your application for migration.

Migrating the Application by Using the Migration Tool

You can run the Migration Tool in GUI or command-line mode.

To start the Migration Tool on Solaris and Linux in GUI mode, type the following command at the shell prompt: 

<install-dir>/bin/asmigrate.sh -u

To start the Migration Tool on Solaris and Linux in command—line mode, type the following command at the shell prompt: 

<install-dir>/bin/asmigrate.sh -c -S <sourceserver> -t <targetdirectory> -T <targetserver> <operand>
or
install-dir>/bin/asmigrate.sh -c -S <sourceserver> -s <sourcedirectory> -t <targetdirectory> -T <targetserver>

To start the Migration Tool on Windows, perform the following steps:

  1. Open a DOS command-prompt window.

  2. Change to the directory in which you have installed the Application Server 8.2.

  3. To start the Migration Tool in GUI mode, type the following command at the DOS prompt:

    asmigrate.cmd -u

    Or, to start the Migration Tool in command—line mode, type the following command at the DOS prompt:

    asmigrate.cmd -c -S <sourceserver> -t <targetdirectory> -T <targetserver> <operand> 
or
asmigrate.cmd -c -S <sourceserver> -s <sourcedirectory> -t <targetdirectory> -T <targetserver>

For more information on the command-line options of the asmigrate command or the Migration Tool, refer http://java.sun.com/j2ee/tools/migration/doc/run.html#CLI

For step-by-step instructions on how to use this tool to migrate your application, refer http://java.sun.com/j2ee/tools/migration/doc/StepByStep.html or the Migration Tool Online Help.

After the Migration Tool migrates your J2EE application, you need to analyze the Migration report to know what additional changes you need to make to the generated output application. You make these changes and then deploy the migrated application. For details on how to perform these tasks, refer http://java.sun.com/j2ee/tools/migration/doc/postrun.html.

Deploying Migrated Applications

To be able to deploy your migrated applications on Application Server 8.2, it is important to understand classloaders in Application Server 8.2 and changes to the architecture of Application Server 8.2.

In Application Server 7, the DAS controls multiple local instances. The Common Classloader loads the classes in the install-dir/<yourdomain>/<yourinstance>/lib/classes directory and the install-dir/<yourdomain>/<yourinstance>/lib directory. All resources and configurations correspond to a specific instance.

In Application Server 8.2, the DAS controls local and remote instances. The Common Classloader loads the JAR and ZIP files in the domain-dir/lib directory and the classes in the domain-dir/lib/classes directory.

In Application Server 8.2, any JAR file placed in the lib directory of the DAS is replicated to all instances controlled by that DAS. The JAR files bundled with the Application Server reside in the install-dir/lib directory.

For more information on the classloader hierarchy in Application Server 8.2, see The Classloader Hierarchy in Sun Java System Application Server Enterprise Edition 8.2 Developer’s Guide.

You can use the delegation inversion mechanism to use libraries bundled with your application instead of those bundled with the Application Server. However, it is safe to use this mechanism only for web modules that do not access EJB components and do not interact with other applications. For more information on the delegation model of Application Server 8.2, see Classloader Delegation in Sun Java System Application Server Enterprise Edition 8.2 Developer’s Guide.

Note –

The default value of the delegate attribute is true in Application Server 8.2. See Default Value for the delegate Attribute.

The JAXP 1.3 parser is bundled with Application Server 8.2. You cannot override the JAXP 1.3 parser for Application Server 8.2.

In Application Server 8.2, to share a library with all the applications and modules in a domain, place the libraries (JAR files) in the domain-dir/lib directory and restart the Application Server. The Common Classloader will load the new libraries. Use this approach to share commonly shared libraries, such as JDBC drivers.

To share libraries across a specific cluster instead of over an entire domain, add the JAR files to the domain-dir/config/<cluster-name>-config/lib directory and add the path to the JAR files in the classpath-suffix attribute. For instructions on how to change this attribute, see Using the System Classloader in Sun Java System Application Server Enterprise Edition 8.2 Developer’s Guide.

Copy the JAR files to domain-dir/config/<cluster-name>-config/lib/ext directory to add to java.ext.dirs. To create an optional package that can be shared across the domain, add the JAR file to domain-dir/lib/ext directory and restart the Application Server.

Note –

If multiple applications deployed on a single instance require different versions of the same JAR file, ensure that those JAR files have different names.