 | 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
Manu T. George (mageorge@in.ibm.com), Staff Software Engineer, IBM
30 Apr 2008
Updated 28 Oct 2008 A tool available from alphaWorks can help you move existing
J2EE™ V1.4 applications from Apache Geronimo-based IBM®
WebSphere® Application Server Community Edition V2.0.x and V2.1.x to IBM WebSphere
Application Server V6.1.
Introduction
Converting 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 Application Advancement 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 conversion 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
interpret the results you get.
As of this writing, the Application Advancement Assistant for WebSphere Application Server
Community Edition supports the
conversion of applications developed to the J2EE 1.4 specification for WebSphere
Application Server Community Edition V2.0.x or V2.1.x. The currently supported target
environment for the converted 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 conversion overview
The Application Advancement Assistant simplifies the conversion of applications from WebSphere
Application Server Community Edition
to WebSphere Application Server by:
- Generating the WebSphere Application Server equivalents of the application's standard and Geronimo-specific deployment descriptors.
- Generating Jython-based resource generation scripts for supported WebSphere Application Server resource types.
- Generating dynamic output that specifies exactly what additional work needs
to be done (for anything that was not converted) to make the conversion
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 conversion using
the Application Advancement Assistant:
- Run the Application Advancement 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 three deliverables:
- An almost WebSphere Application Server compatible EAR or WAR file:
As mentioned earlier, the Application Advancement Assistant does not automatically convert
everything (except in the simplest of EARs or WARs), and so in most cases,
additional steps still need to be performed to complete the conversion; hence
"almost."
- A dynamic document (.html) that is specific to your application
environment: Each application will have its own output generated
that will only contain action items required to finish the conversion of that
application. The output generated by the Application Advancement 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).
- A Jython-based script for each discovered resource
that is supported by both Community Edition and
WebSphere Application Server and can be converted, such as
data source, JMS, security, mail and URL resources.
- 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 conversion 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 Application Advancement Assistant from alphaWorks.
Install the tool by extracting the downloaded ZIP/TAR file into a location of your
choice. The download bundles include a base wasma directory, which will be referred to as WASMA_HOME below.
-
The Application Advancement Assistant 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 as shown in Figure 1, 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 Application Advancement Assistant
-
The Application Advancement 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 one or more outputs:
- One or more HTML files describing the conversion status and any additional
work you need to perform to enable your EAR or WAR file to run successfully
on WebSphere Application Server.
- An updated EAR or WAR file for deploying on WebSphere Application Server, if
no critical errors were encountered.
- A Jython script for each discovered resource that could be
converted from
Community Edition to WebSphere Application Server.
The primary input to the Application Advancement Assistant is the EAR or WAR file you
developed and tested on Community Edition and want converted. 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 Application Advancement Assistant will place its
output in the WASMA_HOME\output directory. You can use the
-o flag to put the outputs in a more convenient location. WASMA extracts
the input archive to tmp-dir during the conversion, which you may override with -t, if you wish.
Figure 3. Invoking WASMA
In the example in Figure 3, the wasma command is
run on the WASMA-supplied, J2EE 1.4-based
PlantsByWebSphere.ear sample application. The command line console output is
fairly simple. There is a conversion 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 were created under the WASMA_HOME\output directory
in a subdirectory created based on the supplied application archive filename.
Open the mentioned index.html file in your browser to view the results of the conversion process.
Figure 4. WASMA generated
output
|
Viewing the output report
Figure 5 shows the generated index.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 archive and the optional
external deployment plan (if one was provided).
The Output section provides the location of the converted WAR or EAR file, the
location of any generated Jython scripts and the log file which contains tracing and debugging information.
Typically, you should not need to refer to the log file, unless you encounter problems with
the tool and need further information to debug them.
The Migration Results - Status section gives a brief summary of the results of the conversion. There
are three possibilities:
-
CWWCA0002I: Archive was successfully migrated. - No additional work required.
-
CWWCA0003W: Archive was migrated, but ... - Some manual migration steps are required. (This is the status in this
example.)
-
CWWCA0004E: Archive migration failed. - A critical error has occurred. See the log file for more information.
The Deployment Plans section lists the deployment plans that the
Application Advancement Assistant processed while converting the input archive.
The Summary and Links section provides links to the the other pages which
contain items that are grouped by role, as described
earlier: an Application Component Provider/Application Assembler page
for developers, and a Deployer/System Administrator page for deployers.
Figure 5. Tool output: Overview section
Figure 6 shows a sample item pulled from the developer page of the generated
output. Action items found here are steps that need to
be performed to the application before 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 within the EAR.
- Generate WebSphere Application Server specific EJB to DB mappings.
- Access any dependencies and package within the EAR or as shared libraries as needed.
Figure 6. Tool output: Developer section
Figure 7 contains a sample item from the deployer page of the generated
output. Action items found here are steps that need to
be performed in the WebSphere Application Server environment before a converted 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 data sources.
- 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 Application Advancement Assistant encounters it while
converting your archive. In the generated HTML output, 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 on one of two pages, 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 convert 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 Application Advancement 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 11. Tool output:
User Action section
Conclusion
IBM's Application Advancement Assistant for WebSphere Application Server Community Edition can
help alleviate much of the manual work required to convert simple J2EE 1.4 applications
from WebSphere Application Server Community Edition V2.0.x and V2.1.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 conversion steps required by a developer and a
deployer, with each role presented with deployment artifacts to convert, along
with detailed explanations and user actions with context relative links to
the WebSphere Application Server V6.1 Information Center.
The Application Advancement Assistant tool is an ongoing effort. If using this tool prompts you
to create a list of conversion features you would like to see, like support for
EJB3, WebSphere Application Server V7 or integration with Eclipse and Rational
tooling, please do not hesitate to post your thoughts to the Application Advancement Assistant or
Community Edition forums mentioned in the resources below.
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. |
| 
| | Manu T. George is a Staff Software Engineer at IBM India Software Labs in Bangalore, India. He is a committer on Apache Geronimo and Apache OpenEJB projects, and is a part of the IBM WebSphere Application Server Community Edition Level 3 Support Team. He received his Bachelor of Technology in Applied Electronics from the College of Engineering Trivandrum in the year 2001. |
Rate this page
| |
