WebSphere migrations

Migrating from BEA WebLogic Server to IBM WebSphere Application Server V5.x


Content series:

This content is part # of # in the series: WebSphere migrations

Stay tuned for additional content in this series.

This content is part of the series:WebSphere migrations

Stay tuned for additional content in this series.

Recent versions of BEA WebLogic Server, like WebSphere Application Server V5.x, support the Java™ 2 Enterprise Edition (J2EE) specification. Conformance to the specification makes migrating from WebLogic Server to WebSphere Application Server relatively easy, though not necessarily without its challenges.

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. Even when code changes are not required, it is still necessary to modify processes, scripts, environments, and, ultimately, culture, meaning that it is possible that migrating from WebLogic Server to WebSphere Application Server could conceivably still take weeks (or even months).

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. Instead, migration should be thought of in broader terms, expanding these areas to also include the development run time environment, developer and administrator skills, and so on.

Very often, migration is not particularly difficult, but it can be a lengthy process. Therefore, it is critical that you begin a migration as aware 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.

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. Assessment will typically take between five and ten days and should involve somebody familiar with WebSphere Application Server V5.x and WebSphere Studio. 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. A high-level architecture review should not take more than a few hours.
  • 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 non-J2EE compliant code. In general, code quality does not have a direct impact on migration complexity. When significant rearchitecture of an application is required, or if it is very difficult to understand the code, then complexity plays a factor. The application code review typically takes between one and two days per application.
  • Review the development environment.
    When migrating to WebSphere Application Server V5.x, it is common to also adapt to using WebSphere development tools, such as WebSphere Studio. 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 WebSphere Studio.
  • 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 of the run time environments typically takes at least a day.
  • 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. For more information about testing, see Related topics.

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

WebSphere Studio is the most appropriate development environment for building applications for WebSphere Application Server. Your development environment can be one of the biggest changes you make as part of your migration.

WebSphere Studio

WebSphere Studio builds applications using Eclipse technology, which is widely regarded as one of the best tools available for Java development. WebSphere Studio builds on the tools provided by Eclipse to provide a complete tool for J2EE development. WebSphere Studio 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).

The WebSphere Studio family of products includes the following:

  • WebSphere Studio Application Developer
  • WebSphere Studio Application Developer Integration Edition
  • WebSphere Studio Enterprise Developer.

Each of these products provides J2EE application development, with increasing levels of extended support. WebSphere Studio Application Developer provides everything you need to build, test and deploy J2EE applications. WebSphere Studio Application Developer Integration Edition extends the J2EE support with support for integrating J2EE with legacy applications using JCA connectors, business process choreography, and other features. WebSphere Studio Enterprise Developer adds support for additional legacy enterprise development, and includes additional rapid application development tools. Early in your migration process, you will have to select the edition of WebSphere Studio best suited to your needs.

Other tools

WebSphere Studio Application Developer supports a number of software configuration management (SCM) solutions, including Rational® ClearCase® and Concurrent Versions System (CVS), and others (using vendor-supplied plug-ins).

As part of the migration to WebSphere Studio, your existing source trees may need to be modified. WebSphere Studio V5 requires that application code be structured along J2EE packaging lines. For example, Web components must be in a "Web project" and Enterprise JavaBeans (EJB) components in an "EJB project". Each of these projects is represented as a separate source tree. Modifying existing source trees in an SCM (while maintaining the history of the various components) can be difficult and time consuming.

The development team can use additional tools as well, though these tools will have to be evaluated to determine their appropriateness for WebSphere Application Server development.


WebSphere Studio is 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 WebSphere Studio to fully leverage the significant power the product can provide. Typically, five days of classroom training is sufficient for application developers who are already familiar with enterprise application development. Every migration plan should include mentoring for the development team to guide them through their first few weeks with WebSphere Studio.

Management of WebSphere Application Server is very different from management of WebLogic Server. 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 WebLogic Server 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

It is likely that significant change will not be required in your application code as part of your migration. For the most part, application code that is "just Java" should work on both platforms. Chances are most of your control and business logic falls into this category. Even some of the J2EE artifacts like servlets, JSPs, and EJB components may work without modification on the new platform.

In evaluating how your application code will be migrated, you need to consider:

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 1 shows how the various archives (also referred to as modules in J2EE documentation) are organized.

Figure 1. J2EE packaging structure
Figure 1. J2EE packaging structure
Figure 1. J2EE packaging structure

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

WebSphere Studio 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).

In many cases, code for applications deployed on WebLogic Server is arbitrarily structured and depends on the build process to make sense of it all. The implication of this is that existing code organization will very likely have to be changed as part of the migration effort. This may be very difficult (or even impossible) to accomplish while maintaining links to your code's history. Some organizations choose simply to archive their history and start fresh.

Changes to the specifications

Most J2EE artifacts should migrate to WebSphere Application Server with relative ease, since migration to these artifacts tends to be more of a redeployment. Still, redeployment can be time consuming (more on this below).

A number of minor changes have been made to the servlet specification which, depending on the age of your WebLogic application, may affect your code. Methods such as HttpSession#getValue(String) have been deprecated in favor of renamed equivalents, like HttpSession#getAttribute(String). Perhaps the most significant change to the servlet specification has to do with session scope. The more recent versions of the servlet specification limit the HttpSession scope to the Web module. That is, it is not possible (according to the specification) for multiple Web modules to share HttpSession data.

In previous versions of the servlet specification (including those supported by older versions of WebLogic Server), a single HttpSession scope is shared by all applications. If your application code depends on this semantic, it will need to be changed. To make migration easier, WebSphere Application Server V5.x does provide a switch that permits HttpSession state to be shared by multiple Web modules packaged within a single EAR. This deviation from the specification is provided as a convenience and its use should be limited.

With a few exceptions, JavaServer Pages (JSPs) intended for deployment on WebLogic Server should migrate with relative ease to WebSphere Application Server. Tag libraries that are specific to WebLogic Server will need to be replaced (this is more of a licensing issue than a technical one). One significant difference between WebLogic Server and WebSphere Application Server is that WebLogic Server's JSP compiler automatically includes the java.util package; you may need to explicitly add this package to some of your JSPs to make them work with WebSphere Application Server.

It is very likely that your EJB code will work without modification, assuming that your beans conform to the EJB 2.0 specification. WebSphere Application Server tends to be more rigorous in its conformance to the EJB specification, so some minor violations that WebLogic Server permits may need some attention when migrating.

Redeploying EJB components can be a time consuming process, as the EJB specification stops short of detailing everything that is needed to deploy beans. The specification, for example, makes no mention of how to provide a name for a bean in the Java Naming and Directory Interface (JNDI). This information is represented in extended deployment descriptors.

Entity beans employing container-managed persistence (CMP) could require much more work to redeploy. Each enterprise bean and persistent field must be remapped to a corresponding database table and columns. If the field names in your entity beans exactly match the column names in your tables, then WebSphere Studio's meet-in-the-middle mapping wizard can complete this job in a matter of minutes. If, however, your field names do not match your column names, you will have to manually reconstruct the mapping. This process can be time consuming and, if not very careful, prone to errors.

While it is theoretically possible to generate the required extended deployment descriptors manually, it is impractical to do so. Instead, consider using either WebSphere Studio Application Developer or the Application Assembly Toolkit to build the deployment descriptors for your beans. The Application Assembly Toolkit for WebSphere Application Server (available for free download ) provides a subset of WebSphere Studio functionality focusing on the deployment of J2EE artifacts.

Older versions of WebLogic Server used the proprietary WebLogic Query Language (WL-QL) to specify finder queries for CMP entity beans. These queries will need to be converted to EJB Query Language (EJB-QL) as part of the migration.

Servlets, JSPs, and EJB components will likely make up the bulk of your migration effort.

Use of proprietary technologies

"Proprietary technology" in this article refers to features that are specific to WebLogic Server and not governed by standards. If your application makes use of proprietary technology, it needs to be changed.

Perhaps the most common examples of proprietary technology are the so called "t3" services, the most popular of which is the t3 protocol used in place of RMI to communicate with EJB components. In general, replacing this protocol amounts to generating WebSphere-specific EJB deployment code and replacing occurrences of t3 with iiop in the uniform resource locators (URLs) provided to the JNDI initial context construction. In general, code that explicitly indicates a provider URL should be changed to instead get this value implicitly from the environment, as recommended by the J2EE specification.

Perhaps the second most commonly used t3 feature is T3StartupDef, which is used to provide code that runs when the application server starts. This code will not run on WebSphere Application Server and so will need to be replaced. For more information on migrating WebLogic Server startup code, see Migrating WebLogic startup code to WebSphere Application Server 5.0.

Optimizations specific to WebLogic Server are useless to WebSphere Application Server. A performance tuning exercise will help you to determine how to best configure WebSphere Application Server for the performance you require.

Third-party libraries

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 V5.0. However, many libraries do have dependencies on particular versions of the application server. To complicate matters, most library vendors do not provide source code or permission to change their code, which can sometimes leave you at their mercy for support.

As part of the migration effort, third party vendors should be contacted and asked to provide compatibility statements for WebSphere Application Server. Compatibility should be tested thoroughly -- and early in the migration cycle -- in case alternatives need to be sought.

Migration tools

There are few tools that provide real help to migrate WebLogic Server applications to WebSphere Application Server. WebSphere Studio is perhaps the most valuable tool in this space, since it provides considerable help to identify, diagnose, and resolve code problems that may manifest as part of the migration process.

If your application conforms to the J2EE 1.2 specification (including EJB 1.1), then the excellent WL2WAS tool can provide significant help. Once your J2EE 1.2 application is migrated to deploy on WebSphere Application Server, it can be easily imported into WebSphere Studio Application Developer, where the J2EE Migration Wizard can then be used to complete the migration to J2EE 1.3.

Other issues

Reference cycles is one of the most common issues encountered when migrating code from WebLogic Server to WebSphere Studio. A reference cycle occurs when a class in one project refers to a class in a different project that refers back to a class (possibly the same class) in the first project.

Reference cycles between classes in different packages or projects are generally considered to be a bad programming practice (they introduce tighter coupling between components). WebSphere Studio's build process will stop when a reference cycle between projects is detected (but can be configured to proceed). Build processes that work with code from a single tree have no problem with the dependencies and do nothing to discourage their construction. For more help on dealing with dependency cycles, see Learning from Experience: Moving a WebLogic Server Application into WebSphere Studio.

Run time environments

Most organizations have more than one run time environment, including development test, system test, performance, and pre-production. Other environments with other purposes may also exist.

Rarely is the migration of a production run time environment a simple matter of shutting everything down, installing new hardware and starting everything back up. This may be possible for development test and system test environments, but other run time environments have restrictions that make such practices impractical, if not impossible. In nearly every case, the production run time environment must stay in service while it is migrated. Often, very limited downtime is acceptable for even the pre-production environment. Migration of a production run time is made more complex if there are multiple applications with different development teams and different delivery schedules. In this kind of situation, you may need to run both application servers concurrently for a period of time.

Depending on your run time configuration, it may be possible to do a "rolling migration". A sample run time topology is shown in Figure 2.

Figure 2. A sample run time topology
Figure 2. A sample run time topology

In a rolling migration scenario, application servers are upgraded either individually or in small groups using the following steps:

  • Select one or more application server nodes.
  • Remove the selected nodes from the load balancer's routing tables (Figure 3).
  • Remove the nodes from service (shut down).
  • Remove (or make dormant) WebLogic Server.
  • Install, configure and test WebSphere Application Server.
  • Install, configure and test the migrated application code.
  • Activate the upgraded node and configure it to accept incoming requests (for example, add it back to the load balancer's routing table).

The process is repeated for the remaining nodes.

Figure 3. A branch is severed and migrated
Figure 3. A branch is severed and migrated
Figure 3. A branch is severed and migrated

This is a very simple overview and may not necessarily be appropriate for your configuration. This scenario assumes that you have at least three application servers providing more capacity than you require (the sample shows four application servers and it can be presumed that the configuration provides at least 50% more capacity than is required). If your run time environment is running close to full capacity, you might consider temporarily adding additional hardware to your configuration during the rolling migration. Note also that this scenario leaves a single HTTP server as a single point of failure while the migration is occurring. This significantly increases your risk during the migration; in an ideal world, at least three HTTP Servers would be available, thereby mitigating this risk.

Every migration plan should include a back out strategy. In the above steps, it is suggested that WebLogic Server be made dormant; rather than completely removing the WebLogic Server installation, you can instead just shut it down (and configure your system not to start it), and remove its plug-in from the HTTP Server. If later testing suggests problems with the migration, it is then relatively easy to reinstate the old application server instance.

If you have multiple applications, the rolling migration could take several weeks (or even months). If you have a single application, or if all your applications are migrated prior to the run time migration, the rolling migration may be accomplished in a matter of hours or days. In either case it is important to consider that, at least for some period of time, you will have to support a run time environment that contains a mix of nodes running WebSphere Application Server and WebLogic Server. Figure 4 shows the mid-point of a sample migration. At this point during the run time migration, only half the nodes have been migrated.

Figure 4. During run time migration, some period of interoperability is inevitable
Figure 4.  During run time migration, some period of interoperability is inevitable
Figure 4. During run time migration, some period of interoperability is inevitable

The mix of application server products has some interesting implications. To start, if two different versions of a single application are running on different application server products, effort must be made to ensure that the application appears consistent to the user. That is, the application should look and act the same way on both application server products. If your applications make use of HttpSession state, you may consider introducing (if you have not already done so) server "stickiness" to ensure that all requests from a particular user are directed to the same server instance. Unfortunately, HttpSession state cannot be shared between WebSphere Application Server and WebLogic Server. This has a potential impact on failover.

There are interoperability options that you may need to consider if your application is split physically across tiers. It is possible to connect from servlets running on WebLogic Server to EJB components running in WebSphere Application Server V5.0 (and vice versa), but this introduces complexity and associated risk that may be prohibitive.

Figure 4 shows a database containing application data that is shared by both WebLogic Server and WebSphere Application Server. This may be possible, but will likely require that very specific versions with very specific fix packs be applied. As part of the migration, you may decide to update your hardware, operating systems, and other components (such as the HTTP Server and database). WebSphere Application Server product requirements are well-documented.


Be sure to test your run time migration plans in a test environment before starting the migration of your production run time. Migration is more than just installing new products. Some of your existing practices and processes may also need to be considered. Any scripts you currently use to administer your servers will need to be revisited, rebuilt, and tested.

Additional scenarios are presented with detail in Migrating to WebSphere V5.0: An End-to-End Migration Guide.


It is difficult to cover all aspects of migration in a single document. Without exception, every organization and application is different, so it follows that every migration experience will be different as well. In this paper, we have outlined many of the issues you must consider as part of your migration effort. More specific technical information about migrating to WebSphere Application Server is available in Related topics.

Migration is always a significant undertaking. Even if no change is required to your application code, you can expect that migration will still take some level of time and effort when all factors are considered. Migration involves more than just code or any single environment. Your migration plan should account for everything from development environment and skills, right through to administration skills and run time environments.

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

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=WebSphere migrations: Migrating from BEA WebLogic Server to IBM WebSphere Application Server V5.x