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.

Back to top

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:

1. 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.
2. 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.
3. 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).
4. Install the application into your WebSphere Application Server environment and begin testing.

Back to top

Installing and running the tool

1. 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.

2. 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
   
   
   

3. 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
   
   
   

Back to top

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 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 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.

Back to top

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 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 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 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.

Back to top

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

• Redbook: Migrating from WebSphere Application Server Community Edition to WebSphere Application Server
  
  
• Redbook: WebSphere Application Server V6.1: System Management and Configuration
  
  
• Redbook: WebSphere Application Server Community Edition 2.0 User Guide
  
  
• WebSphere Application Server Community Edition zone on developerWorks
  
  
• WebSphere Application Server Community Edition community space on developerWorks
  
  
• View a PDF of the original V2.0 article.
  
  

Get products and technologies

• Download the Application Advancement Assistant for WebSphere Application Server Community Edition
  
  
• Download WebSphere Application Server Community Edition
  
  

Discuss

• IBM WebSphere Application Server Community Edition focused discussion forum.
  
  
• IBM WebSphere Application Server focused discussion forum.
  
  

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.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• End to end conversion overview
• Installing and running the tool
• Viewing the output report
• A closer look
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers