WebSphere migrations

Principles and plans for migrating from WebSphere Application Server Community Edition to other WebSphere Application Server products


IBM WebSphere Application Server Community Edition is an application server platform based on the Apache Geronimo open source application server project. WebSphere Application Server Community Edition (hereafter referred to as Community Edition) consists of a set of core features and services, as well as additional critical services provided by other open source projects, that live together to offer the J2EE™ application server platform.

The table below details the open source projects integrated into Apache Geronimo (see Related topics for more information):

Specification required for J2EEArea of coverageProject or code used by Apache Geronimo
Servlets 2.4
JavaServer Pages (JSP) 2.0
Web tier container with support for JSPs and servletsJetty and Tomcat
Enterprise Java Beans (EJB) 2.1EJB containerOpenEJB
Java Message Service (JMS) 1.1Messaging serviceActiveMQ
Java Naming and Directory Interface (JNDI) 1.2.1 Directory service/naming APICustom code implementation
Java Transaction API (JTA) 1.0TransactionsCustom manager with High-speed ObjectWeb Logger (HOWL) for transaction logging, XA supported, evolving to Java Open Transaction Manager (JOTM)
JavaMail 1.3MailCustom code
JavaBeans Activation Framework (JAF) 1.0Activation; handling html/text/gif/jpg MIME types, primarily for JavaMail attachmentsCustom code
JSR 77 -- J2EE Management 1.0ManageabilityCustom code with MX4J
JSR 88 -- J2EE Deployment 1.1Deployment and configuration -- cross-vendor server deployabilityCustom code implementation
Java Management Extensions (JMX) 1.2ManageabilityMX4J
Java Data Access API (JDBC) 3.0, 2.1DatabaseCode from TranQL
Java API for XML Processing (JAXP) 1.2SAX, DOM APIs; third-party SAX, DOM, XSLT engine pluggabilityJDK support where applicable, and Apache Xerces
J2EE Connector Architecture (J2CA) 1.5ConnectorCustom coding. Includes JMS resources and JDBC pools.
JSR 109 -- Implementing Enterprise Web Services 1.1Web servicesApache Axis
Java API for XML-based RPC (JAX-RPC)Web servicesApache Axis
SOAP with Attachments API for Java (SAAJ) 1.2Web servicesApache Axis
Java API for XML Registries (JAXR) 1.0Web servicesApache Scout
JSR 115: Java Authorization Contract for Containers (JACC)Security -- authorization and authenticationCustom development using JDK's JAAS support
Internal databaseDatabaseDerby
Persistence mechanismDatabaseUnified substrate for CMP and Beans/POJO oriented schemes over TranQL
Interoperability TCP/IP, HTTP1.1, SSL3.0, TLS 1.0, SOAP 1.1, WS-I Basic Profile 1.0 CORBA - IIOP, RMI-IIOP, EJB Interop, CORBA Interop Naming Service, JRMPJDK support (that is, ORB and JRMP), support from other packages, and custom code

As the foundation of the WebSphere software platform, IBM WebSphere Application Server V6.0 is the industry's premier Java™-based application platform, integrating enterprise data and transactions for the dynamic on demand business world. Each WebSphere Application Server configuration delivers a rich application deployment environment with application services that provide enhanced capabilities for transaction management, as well as the security, performance, availability, connectivity, and scalability expected from WebSphere products. Figure 1 shows a high level summary of WebSphere Application Server products.

Figure 1. WebSphere product family
Figure 1. WebSphere product family
Figure 1. WebSphere product family

WebSphere Application Server Community Edition is an extremely practical and beneficial option for customers, enabling them to get started quickly with their J2EE application development without any licensing costs. Eventually, should the development team wish to integrate, test, and extend their application beyond Community Edition, a migration path to other WebSphere Application Server products is available.

Figure 2. Migrating from Community Edition to other WebSphere Application Server products
Figure 2. Migrating from Community Edition to other WebSphere Application Server products
Figure 2. Migrating from Community Edition to other WebSphere Application Server products

In fact, since all WebSphere Application Server products, including Community Edition, support the Java 2 Enterprise Edition (J2EE) specification, migrating from Community Edition to another WebSphere Application Server product is relatively easy, though some areas do require special care during the migration process.

J2EE is primarily concerned with how application code is written and packaged; application code is only part of enterprise application ownership and often tends to be a relatively small part of a migration effort. Any migration will propagate change in terms of processes, environments, skills, and culture within the development team.

It is easy to think of a migration in narrow terms, but it is dangerous to do so. Application developers often tend to think of migration only in terms of changes to the application code, and administrators think primarily of the production run time environment. Instead, migration should be thought of in broader terms, and must (at least) consider:

  • Development environment
  • Developer skills
  • Required and recommended changes to the application code
  • Administrator skills
  • Run time environments.

Very often, migration is not particularly difficult, but it can be a lengthy process. Therefore, it is critical that you begin a migration with your eyes as wide open as possible and take adequate stock of what you need to do before you get started.

This article is organized as a high level checklist and meant to serve as a tool to help you adequately cover the areas required to make your migration a success. In the remainder of this document:

  • Community Edition refers to WebSphere Application Server Community Edition.
  • WebSphere Application Server refers to WebSphere Application Server - Express, WebSphere Application Server Base and WebSphere Application Server Network Deployment.

Migration roadmap

Migration must consider all aspects of enterprise application ownership. At a high level, your migration plan should cover the following areas:

The following sections provide details on each of these areas.

Migration assessment

A comprehensive assessment is a key element of a successful migration. The overall goal of assessment is to discover issues that may have an impact on the migration process so that adequate resources can be applied to ensure that the migration is successful. The main activities and objectives of assessment include:

  • Bring concerned parties together.
    The migration assessment is a good opportunity to bring concerned parties together. An interesting result of assessment is often a more clear understanding between the different groups about the larger picture, and a greater appreciation for the issues faced by other areas.

  • Review high-level architecture.
    With the gathering of concerned parties comes an excellent opportunity to articulate the application architecture at a high level. With a clearer view of the big picture, the stage is neatly set for subsequent parts of the assessment.

  • Review application code.
    Naturally, a review of the application code must be part of the assessment process. This is not a full-blown code review; rather, a code review in the context of a migration assessment is generally concerned only with discovering the use of any non-J2EE compliant code. In general, code quality does not have a direct impact on migration complexity. It is only when significant rearchitecture of an application is required, or when the complexity makes it very difficult to understand the code, that complexity plays a factor.

  • Review the development environment.
    When migrating to WebSphere Application Server V6.0, it is common to also adapt to using WebSphere development tools, such as IBM Rational® Application Developer for WebSphere Software V6.0. However, if the existing development environment is to be retained, some current development practices may need to be revised. As part of the assessment, the current development environment should be reviewed to determine how the existing practices, tools, and skills can be adapted to build a new development environment around Rational Application Developer.

  • Assess application development skills.
    Existing application development skills should be evaluated as part of the assessment. Even software developers familiar with J2EE may need some skills upgrades to familiarize themselves with J2EE, WebSphere Application Server, and the new development environment.

  • Review the run time environments.
    Most organizations support a number of run time environments, each with a different purpose. The configuration of these environments (potentially including one or more development test, system test, pre-production, and production environments) should be reviewed as part of the assessment to ensure that the existing requirements, topology, configurations, and hardware are adequate for WebSphere Application Server. A review of security requirements and implementation is an important part of this stage of the assessment.

  • Review the build and deployment processes.
    The existing processes should be reviewed to identify changes that are required for WebSphere Application Server. Existing build scripts may need to be changed. New scripts will have to be written to replace those used to manage the application servers.

  • Review and understand schedule issues.
    Scheduling is always an issue with migration. Most organizations have applications that are constantly changing in response to external business drivers. Working a migration plan around other deliverables can be a daunting task that requires special attention.

  • Review testing practices.
    The existing testing practices should be reviewed to determine whether or not they provide adequate coverage. If they do not, then some augmentation of testing practices may be required. When a problem is encountered during migration and well-defined, robust testing practices are not in place, it is often difficult to know if the migration is a catalyst that exposed a pre-existing problem, or if the migration is the actual source of the problem. This makes it difficult to gauge the progress and the ultimate success of the migration. A comprehensive testing strategy is a very important part of enterprise application ownership.

Assessment gives you the opportunity to understand what you have and what you need to do, and to accurately plan your migration so you can put the required resources into place.

Development environment

The development environment is one of the first environments to be addressed during a migration. Developers need to be able to become comfortable with the IDE and the testing environment to be productive and be effective in debugging their applications.


In keeping with the open source trend, the most popular development environment that Java developers use today is Eclipse 3.1. Eclipse is an open source IDE platform that enables easy extensibility by means of plug-ins, and the Eclipse organization promotes the building of commercial products based on Eclipse framework. IBM provides a plug-in for use with Eclipse Web Tools Platform (WTP) for testing and debugging applications on Community Edition.

For more information about using Eclipse for deploying and testing applications with Community Edition, see How to use the new Eclipse plug-in for Geronimo.

Figure 3. Eclipse platform with WebSphere Application Server Community Edition plug-in
Figure 3. Eclipse platform with WebSphere Application Server Community Edition plug-in
Figure 3. Eclipse platform with WebSphere Application Server Community Edition plug-in

Rational Application Developer

IBM Rational Application Developer V6.0 is the most appropriate development environment for building applications for WebSphere Application Server. Rational Application Developer builds applications using Eclipse technology, and builds on the tools provided by Eclipse to provide a complete environment for J2EE development. Rational Application Developer is an open and pluggable environment intended for all kinds of development, including components to build and edit Java, J2EE, and Web site content (HTML, images, and other resources).

Figure 4 shows a high level view of the Rational Application family of products.

Figure 4. Rational tools
Figure 4. Rational tools
Figure 4. Rational tools

The Rational Developer products, Rational Web Developer and Rational Application Developer, each provides J2EE application development, with increasing levels of extended support. Rational Application Developer provides everything you need to build, test, and deploy J2EE applications. Early in the migration process, you will have to select the development tool best suited to your needs.

Migrating from Eclipse to Rational Developer products

Users familiar with Eclipse, initially using a Rational Developer product, which is built on Eclipse, will quickly become accustomed to performing application development and deployment tasks with the new tools. The code from the Eclipse J2EE environment can be exported as EAR/WAR and JAR files and easily imported into Rational Web or Application Developer for continued development. (Project dependencies and the Eclipse build paths will not be preserved, and may need to be reconfigured within the Rational environment.)


Rational Developer products support a number of software configuration management (SCM) solutions, including Rational ClearCase, Concurrent Versions System (CVS), and others using vendor-supplied plug-ins. As part of the migration to Rational, your existing source trees will not have to be modified if they follow the J2EE packaging structure.

Build process

If you are using Ant/Project Maven to build and package your application into EAR/WAR/JAR files, WebSphere Application Server provides a set of pre-built Ant tasks that can be integrated for RMIC generation and automated deployment integration. The WebSphere Application Server Information Center has more information about automating builds using Ant tasks.


Rational tools are different from other development environments and you should expect that it will require some time for developers to fully develop the skills required to work effectively with the product. Even really bright people should receive training for IBM Rational Web or Application Developer to fully leverage the significant power the products can provide. Typically, five days of classroom training is sufficient for application developers who are already familiar with enterprise application development.

Management of WebSphere Application Server is very different from management of Community Edition. While many of the concepts are similar, the details are very different. It may take time for your operations staff to learn about WebSphere Application Server and understand how to configure and manage it. Existing scripts that you may have used to manage Community Edition will need to be rebuilt to work with WebSphere Application Server.

Managing a collection of WebSphere Application Server nodes is still a task that requires dedicated administrators with specialized skills. Even skilled administrators will benefit from formal training. Typically, five days of classroom training is enough to arm seasoned application server administrators with the information they need to install, configure and maintain WebSphere Application Server.

Application code

As long as the applications abide by the J2EE specification there will not be significant change required in your application code as part of the migration. For the most-part, application code that is "just Java" should just work on both products. Chances are that most of your control and business logic falls into this category. Most of your Java code should migrate without change. Since Community Edition and WebSphere Application Server are J2EE 1.4 compliant it is unlikely that there would be any changes to J2EE artifacts like servlets, JSPs, and EJB™ components.

However, there are other sections within the J2EE that needs further attention, such as:

These points are discussed below.

Code organization

J2EE defines a very specific packaging structure that separates the various artifacts into different archives. Web artifacts, including servlets, JSPs, and Web content (like GIF and JPEG files), are packaged in a Web Archive (WAR) file. EJB artifacts, typically consisting of the EJB types, are packaged in an EJB-JAR (JAR) file. An Enterprise Archive (EAR) file is used to collect all the application components (WAR and JAR) files into a single file. Other libraries (JAR files) used by the application can be located in the EAR file as well. The archive can also contain application client archives (JAR) which is another J2EE module type.

Figure 5 shows how the various archives (also referred to as modules in J2EE documentation) are organized.

Figure 5. J2EE packaging structure
Figure 5. J2EE packaging structure
Figure 5. J2EE packaging structure

There is an XML deployment descriptor packaged with each module. The deployment descriptor describes the organization of the components in the module and how they are configured at run time.

Rational Application Developer requires that application code be structured along J2EE lines. As mentioned, Web artifacts must be placed in a Web project and EJB artifacts in an EJB project. Within these project types, a particular directory structure is also required. A Web project must, for example, contain a Web content directory that contains all the content for the project (everything except source code).

If the code is structured in such a way for the build process to bundle the different modules into J2EE artifacts, then the implications might be that existing code organization will have to be changed as a part of the migration effort.

Deployment descriptors

All applications require standard J2EE deployment descriptors as web.xml, ejb-jar.xml, and so on, to define components and operational parameters within a J2EE container. In addition to these, there are also application server specific deployment descriptors that some applications will need to run within the container. The application server specific deployment descriptors do not conform to any standards and hence they vary between the J2EE container implementations.

The table below lists the deployment descriptors used by Community Edition and WebSphere Application Server:

J2EE moduleCommunity EditionWebSphere Application Server
Web containergeronimo-web.xmlibm-web-bnd.xmi
EJB containeropenejb-jar.xmlibm-ejb-jar-bnd.xmi
JCA containergeronimo-ra.xmlra.xml
Application descriptorgeronimo-application.xmlibm-application-bnd.xmi

The extended deployment descriptors (also referred to as deployment plan in the Geronimo world) provide more information about the application to the container. These can be easily migrated into WebSphere Application Server-specific containers by importing the application into Rational Application Developer or the Application Server Toolkit (ASTK).


Community Edition leverages a JAAS-based security to be enforced within a JVM, and does not have a server wide default security realm configuration. Any number of security realms can be configured and each application module has to specify in its deployment plan the name of the security realm to be used. This limits the ability to do single sign on and identity propagation to downstream servers. The security realms are enforced using JAASLoginModules, which provides the capabilities of prompting the user for username and password, and for creating the JAAS subject with the principal for that user.

Community Edition ships with the most commonly used LoginModules for:

  • Authenticating against a list of users and groups stored in files on disk.
  • Authenticating against a database holding the users and groups.
  • Authenticating via Kerberos.
  • Authenticating via SSL client certificates, where a properties file maps certificate names to users and groups.

All the security realms are configurable via deployment plan. Information on Geronimo security will also apply to Community Edition.

WebSphere Application Server provides a default security realm that can be set and used for the entire server. The same realm can be shared between WebSphere administration and for application security authentication and authorization. WebSphere Application Server conforms to JAAS standards, and Login modules can be easily plugged into the application server for easy access. The security realms are enforced by means of four types of UserRegistry:

  • FileBasedUserRegistry
  • LDAPUserRegistry
  • LocalOSRegistry
  • CustomUserRegistry.

As the names indicate, the user registries are for disk based, LDAP, and local operating system authentication. The more complex security requirements can be addressed using the CustomUserRegistry. For more information on writing custom user registries, see the WebSphere Application Server Information Center.

Further, if you have written your own JAASLoginModule, you can leverage the same within WebSphere Application Server by configuring them through the admin console or through using scripts. The Information Center also has more information on configuring JAAS Modules within WebSphere Application Server.

Changes in the security implementation do not warrant any changes in the application code itself since they are all being enforced by the J2EE container using the JAAS standards.


As typical with all application servers, the JNDI context factories for Community Edition and WebSphere Application Server are different. If all the JNDI lookups within the application are local context lookups (contained within the same EAR), then this will not affect the application code. WebSphere Application Server uses the context factory, and will also require the J2EE application client programs to run within WebSphere J2EE client container to leverage all of WebSphere Application Server’s capabilities.

See the Information Center for more information about developing using WebSphere J2EE Application clients.

EJB (CMP) beans migration

Community Edition uses OpenEJB as its EJB container and Castor JDO as its CMP implementation mechanism. While the EJB implementations conform to the J2EE 1.4 and EJB 2.1 standards, the internal workings of the container can be very different -- especially the Entity CMP beans, which use the extended deployment descriptors to provide object to database mapping information. WebSphere Application Server has a similar way of mapping CMP bean Java objects to a database using mapping files, and these can be generated using either the Application Server Toolkit or Rational Application Developer. See the Information Center for more information on using Container Manager Persistence within WebSphere Application Server.

If you are using an external persistence mechanism such as Hibernate or iBatis, you will be able to retain the persistence model without any changes and run it within WebSphere Application Server by deploying the dependent libraries as a part of the application.

Third-party libraries and frameworks

WebSphere Application Server treats third-party libraries the same as your application code. Libraries composed of "just Java" code should continue to work without modification on WebSphere Application Server. However, many libraries do have dependencies on particular versions of the dependent libraries (for example Xerces or Xalan). As part of the migration effort, it is imperative that the third party library or framework be compatible to work within WebSphere Application Server. Compatibility should be tested thoroughly -- and early in the migration cycle -- in case alternatives need to be sought.

Run time environment

Installation, administration, and management

Community Edition is designed to bootstrap development teams and agile enterprises to quickly get started with the application development and deployment process. It is possible to get Community Edition installed and up and running (including downloading) within a matter of minutes. Part of the appeal of the Apache Geronimo project is the ability to customize the runtime to suit the application being deployed on to the server. A simple administrative console is also available to view the current status of the application and to manage the running components within the application server.

Installing WebSphere Application Server is a larger effort. To install a large enterprise may take some time and skilled personnel to complete. WebSphere Application Server Base installation is tuned out of the box to initially run enterprise applications with little or no tuning at all. WebSphere Application Server Network Deployment has features to support clustering and central application/server management within a cell. Any task related to administration and management can be done through Web-based administration console or wsadmin scripts. See the Information Center for more information on installation and administration.

Community Edition and WebSphere Application Server installations can co-exist on the same physical servers as long as the ports used by these servers do not conflict. The run time processes are individual JVMs and as long as the physical server has enough memory and hard disk, they can be run alongside each other.

Run time migration

When referring to the run time environment, it is the production environment that most people think of first, but the run time environment should be thought of as more than that; it includes your development testing, system testing, performance, and pre-production testing as well. Considering that many developers and enterprises may use Community Edition as their test platform, it is important to consider the strategy for migrating the run time environment.

As mentioned above, the easiest run time migration approach is to make Community Edition and WebSphere Application Server co-exist on the same hardware until the development and the test teams are comfortable with the new systems to which they are migrating. Once the new processes are in place for deploying to WebSphere Application Server, then Community Edition can be shut off and removed from the system, if desired.

Figure 6. Illustration of run time migration recommendation
Figure 6. Illustration of run time migration recommendation
Figure 6. Illustration of run time migration recommendation

The same approach can be followed for the production environment as well. Again, the co-existence strategy assumes that there will no port conflict and the physical system(s) has the capability to support two servers or processes running simultaneously on the same machine.

Before you decide to build out your WebSphere Application Server environment, your team should become familiar with the different WebSphere deployment topologies that will ensure the best high availability and scalability options for your applications. To learn more about choosing the right network topology see the Redbook WebSphere Application Server Network Deployment V6: High Availability Solutions.


Migrating from WebSphere Application Server Community Edition to other WebSphere Application Server family products is relatively easy, but must be performed with care. Every organization and application is different, and so the migration experience will be as well. This article outlined the basic issues you need to consider for migrating from WebSphere Application Server Community Edition to WebSphere Application Server Base or Network Deployment. The migration path is a natural progression as your organization and applications grow in size and complexity, and a more scalable, highly available, and full featured platform becomes more of a competitive requirement to successfully achieve your business objectives.

Migrations that begin with careful planning are the ones likely to be most successful.

Important version information: This article was written for WebSphere Application Server Community Edition V1.0, which was the current version at the time the article was published. Some of the information in this article may not be applicable to later versions. To follow along with this article, be sure to use the product version on which this article is based. If you wish, you can download the current version of WebSphere Application Server Community Edition, or you can download an earlier version by visiting the product archive page.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=WebSphere, Open source
ArticleTitle=WebSphere migrations: Principles and plans for migrating from WebSphere Application Server Community Edition to other WebSphere Application Server products