 | Level: Introductory Brian Stelzer (bsstelze@us.ibm.com), Staff Software Engineer, IBM
O. Ted Kirby (otkirby@us.ibm.com), Sr. Software Engineer, IBM
Donald R. Woods (drwoods@us.ibm.com), Sr. Software Engineer, IBM
30 Apr 2008 A new tool available from alphaWorks can help you migrate existing
J2EE™ V1.4 applications from Apache Geronimo-based IBM®
WebSphere® Application Server Community Edition V2.0.x to IBM WebSphere
Application Server V6.1.
Introduction
Migrating an application that was written for IBM WebSphere Application Server
Community Edition in such a way that it behaves the same when it runs on IBM
WebSphere Application Server V6.1 requires a series of steps, some of which can be
automated and others that are manual. IBM's new Migration Assistant for
WebSphere Application Server Community Edition tool was created to perform
the automated steps and to help alleviate much of the required manual work. This
article provides a high level overview of this new migration tool, available from
alphaWorks, to
help make the transition to WebSphere Application Server as easy as possible.
This article will not explore any specific issues that you might encounter when
using the tool, but it will offer some general guidance to help you use and
interpretate the results you get.
As of this writing, the Migration Assistant for WebSphere Application Server
Community Edition (hereafter referred to as Migration Assistant) supports the
migration of applications developed to the J2EE 1.4 specification for WebSphere
Application Server Community Edition V2.0.x . The currently supported target
environment for the migrated applications is WebSphere Application Server V6.1
(with no feature packs installed). In this article, all references to WebSphere
Application Server pertain specifically to Version 6.1.x.
End to end migration
overview
The Migration Assistant simplifies the migration of applications from WebSphere
Application Server Community Edition (hereafter referred to as Community Edition)
to WebSphere Application Server by:
- Generating the WebSphere Application Server equivalents of the application's standard and Geronimo-specific deployment descriptors.
- Generating dynamic output that specifyies exactly what additional work needs
to be done (for anything that was not migrated) to make the migration
complete, based on the contents of the standard and Geronimo-specific deployment
descriptors.
Here is a high level look at the steps involved when performing a migration using
the Migration Assistant:
- Run the Migration Assistant command line utility (
wasma.bat or wasma.sh),
passing in the application and any externally-referenced Geronimo-specific
deployment plan as inputs. This will result in the creation of two deliverables:
- An almost WebSphere Application Server compatible EAR or WAR file:
As mentioned earlier, the Migration Assistant does not automatically migrate
everything (except in the simplest of EARs or WARs), and so in most cases,
additional steps still need to be performed to complete the migration; hence
"almost."
- A dynamic document (.html) that is specific to your application
environment: Each application will have its own different output generated
that
will only contain action items required to finish the migration of that
application. The output generated by the Migration Assistant is
structured according to J2EE-defined roles; steps provided for developers
(which apply to the
Application Component Provider and Application Assembler roles) are separate
from the steps provided for deployers (which apply to the Deployer and System Administrator
roles).
- The Application Component Provider or Application Assembler reviews the
developer section of the generated documentation for any action items. When all
developer action items have been resolved, the application is then WebSphere
Application Server compatible. At this point, the application and generated
documentation can be sent off to the Deployer or System Administrator for
additional migration work.
- The Deployer or System Administrator resolves any action items listed in the
deployer section. Whereas developer action items will be application specific
(such as bundling additional libraries and repackaging external resource
adapters), action items in the deployer section will be specific to the
WebSphere Application Server V6.1 environment (such as creating data sources and
binding resource references to physical resources).
- Install the application into your WebSphere Application Server environment and
begin testing.
 |
Installing and running the tool
-
Download the Migration Assistant from alphaWorks.
Install the tool by extracting the download .zip file into a directory of your
choice. This directory will be referred to as WASMA_HOME.
-
The Migration Tool uses some WebSphere Application Server binaries (JAR
files) to analyze your application EAR and WAR files, as well as to create EAR
and WAR files for deployment on WebSphere Application Server. You must have
WebSphere Application Server installed on your system, and the
WAS_INSTALL_ROOT environment variable must be properly set to the WebSphere
Application Server root directory on your system.
Figure 1. Initial setup before
running Migration Assistant
-
The Migration Assistant is a command line tool that analyzes an EAR or WAR file. Figure 2 shows
the wasma command syntax as given by the usage message.
Figure 2. WASMA command-line
syntax
The tool produces two outputs:
- An EAR or WAR file for deploying on WebSphere Application Server.
- An HTML report file describing any additional work you need to perform to
enable your EAR or WAR file to run successfully on WebSphere Application
Server.
The primary input to the Migration Assistant is the EAR or WAR file you want migrated. As with
deploying an EAR or WAR on Community Edition, an optional external deployment
plan can also be specified; this would override any Geronimo-specific
deployment plan in your EAR or WAR file. By default, the Migration Assistant will place its
output in the directory containing the input EAR or WAR file. You can use the
-o and -a flags to put the outputs in a more convenient location. WASMA cracks
open the input archive to tmp-dir, which you may specify with -t, if you wish.
Figure 3. Invoking WASMA
In the example in Figure 3, the wasma command is
run on the J2EE 1.4-based
PlantsByWebSphere.ear sample application. The command line console output is
fairly simple. There is a migration status message, indicating briefly how
much more work is required, followed by a message giving the location of the
output report HTML file . In this invocation, the defaults were taken, so the
output files shown in Figure 4 are in the same directory as the input file.
Open the .html file in your browser.
Figure 4. WASMA generated
output
|
Viewing the output report
Figure 5 shows the top of the generated .html report file, as shown in a browser.
The Input section shows the input parameters that the tool used to produce this
report. It gives the location of the input and output archives, the optional
external deployment plan (if one was provided), and the location of the log file.
Typically, you should not need to refer to the log file. If you have problems with
the tool, you will want to look at this file to debug them.
The Status section gives a brief summary of the results of the migration. There
are three possibilities:
-
Success, no additional work required.
-
Success, but more work is required. (This is the status in this
example.)
-
Failure.
The Deployment Plans section lists the deployment plans that the Migration
Assistant processed while migrating the input archive.
Figure 5. Tool output: Overview section
The rest of the report lists the items that require additional manual
configuration in order for the output archive to run successfully in WebSphere
Application Server. These items are grouped into sections by role, as described
earlier: an Application Component Provider/Application Assembler section
for developers, and a Deployer/System Administrator section for deployers. The Section Summary and Links is like a
table of contents that provides a summary of the work required, with links to each
section in the report below.
Figure 6 shows a sample item pulled from the developer section of the generated
output. Action items found here are steps that need to
be performed to the application before the it can be deployed into the
WebSphere Application Server environment. Some of the actions that you can expect
to find under in this section include:
- Repackage externally referenced Web modules with EAR.
- Generate WebSphere Application Server specific EJB to DB mappings.
- Access any dependencies and package with EAR as needed.
Figure 6. Tool output: Developer section
Figure 7 contains a sample item from the deployer section of the generated
output. Action items found here are steps that need to
be performed in the WebSphere Application Server environment before a migrated application can
be installed. Some of actions that you can expect to find in this section include:
- Bind resource references.
- Create physical resources such as datasources.
- Set up security and bind security roles.
Figure 7. Tool output: Deployer
section
A closer look
Let's explore some of the individual items in the report.
A log record is generated for each instance of an element requiring manual
intervention, in the order that the Migration Assistant encounters it while
migrating your archive. In the output report, each element is listed once, along
with a table of the values for each instance or occurrence of this element found
in the archive. The elements are grouped by section, which relates to the role
(developer or deployer) of the person generally tasked with performing the work. The elements are presented in
descending order of roughly how much work is required to manually migrate the
element.
Figure 8 shows an item with the Message section highlighted. This is the message
text that is found in the log file for each element, briefly describing the
problem element that the Migration Assistant encountered. Messages have variable
data for each instance or occurrence of the element to identify the precise
resource and other data required to fix the problem. Each variable is named,
presented in bold type, and enclosed by {}.
Figure 8. Tool output: Message section
Figure 9 shows an item with the Values section highlighted. This section lists
the variable data for each message or element instance in a table. The variable
name is in the column header, in bold type, and matches the name in the Message
section.
Figure 9. Tool output: Values section
Figure 10 shows an item with the Explanation section highlighted. This section
gives a fuller description of the problem to be solved for this element.
Figure 10. Tool output:
Explanation section
Figure 11 shows an item with the User Action section highlighted. This section
describes how to resolve the issue, generally with links to the WebSphere
Application Server V6.1 Information Center, which will give you complete
information and specific steps for addressing the problem.
Figure 10. Tool output:
User Action section
Conclusion
IBM's Migration Assistant for WebSphere Application Server Community Edition can
help
alleviate much of the manual work required to migrate simple J2EE 1.4 applications
from WebSphere Application Server Community Edition V2.0.x to WebSphere
Application Server V6.1. For more complicated applications, such as those that use
EJB V2.1 or rely upon server unique features or resources, the tool will generate
documentation focused on the manual migration steps required by a developer and a
deployer, with each role presented with deployment artifacts to migrate, along
with detailed explanations and user actions with context relative links to
the WebSphere Application Server V6.1 Information Center.
The Migration Assistant tool is an ongoing effort. If using this tool prompts you
to create a list of migration features you would like to see, please don't
hesitate to post a comment to this article or to the forums associated with this
tool.
Resources Learn
Get products and technologies
Discuss
About the authors | 
| |
Brian Stelzer is a Software Engineer at IBM in Rochester, MN. He has over 7 years of experience planning, designing and implementing migration solutions for customers using both WebSphere Application Server and WebSphere Application Server Community Edition. Brian is currently working on the WebSphere Application Server Community Edition migration team. |
| 
| |
Ted Kirby is a Sr. Software Engineer at IBM in RTP, NC. He is part of the WebSphere Application Server Community Edition development and migration teams. Previously, he has enhanced and maintained eCommerce Web sites and developed distributed operating systems, including the system used by the Deep Blue machine.
|
| 
| |
Donald Woods is a Sr. Software Engineer at IBM in RTP, NC. He is part of the WebSphere Application Server Community Edition development and migration teams, along with being an Apache Geronimo committer and PMC member. Previously, he has worked on various WebSphere Everyplace mobility and Tivoli system management products. |
Rate this page
| |
