WebSphere migrations

Migrate from Apache Tomcat to WebSphere Application Server Community Edition


If you are already using Apache Tomcat 5.x to host your Web application and wish to evaluate IBM WebSphere Application Server Community Edition V1.0 as a robust and developer-friendly development or production environment, this article will help you kick start your effort.

The information here will help you will gain insight into the implementation differences between the Tomcat 5.5 application server and WebSphere Application Server Community Edition. A step by step application migration procedure will be illustrated using a sample application designed to highlight some of the notable differences between the two implementations. You will first deploy this application to Tomcat 5.5, then perform migration steps and deploy to WebSphere Application Server Community Edition (hereafter referred to as Community Edition).

This article is organized into the following sections:

Before you continue: 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.

Implementation analysis: Tomcat vs. Community Edition

Migrating existing applications from one vendor's server to another can often be a daunting task. Despite the reassurance of J2EE certification, it is possible for an application to make use of features and extensions that are vendor specific, in the process making the software asset less portable between servers. However, this is not a problem when you are moving between Tomcat 5.5 to Community Edition.

The main reason why you can be quite certain that your application will move smoothly between Tomcat 5.5 and Community Edition 1.0 is the fact that Tomcat 5.5 is part of the Community Edition V1.0 distribution, integrating Tomcat 5.5.9 as its Web-tier container. As a result, there is no need to migrate to a different Web-tier container at all. Figure 1 illustrates this Tomcat 5.5 integration.

Figure 1. Tomcat 5.5 integration in WebSphere Application Server Community Edition
Tomcat 5.5 integration in WebSphere Application Server Community Edition
Tomcat 5.5 integration in WebSphere Application Server Community Edition

In Figure 1, you can see that in fact you will be working with exactly the same Tomcat 5.5 server with which you are already familiar; there is no need to repackage or change the Tomcat 5.5 application-tier assets for Community Edition. There are differences, however, that you need to be aware of as you migrate your applications.

These differences exist mainly due to:

  • How Tomcat 5.5 is integrated into the Community Edition container; Community Edition now handles configuration management, and
  • The fact that the resources of a full-featured J2EE 1.4 server is now available to Tomcat.

Essentially, you can think of this as wrapping Tomcat 5.5 up for use within a larger J2EE container, providing it with container services such as the built-in JNDI support, security, built-in EJB support, built-in JMS broker, and built-in RDBMS.

With this model in mind, you will find that all you need to do to overcome most migration related issues is figure out how or where the equivalent Tomcat 5.5 configurable feature is mapped into the Community Edition container. Once you have located these mappings, the operation of the Tomcat 5 container is identical to the Tomcat 5.5 server that you are working with. There is no internal architectural change to Tomcat 5.5 made in the integration process, it is simply wrapped and fitted into the Community Edition container. This ensures that newer versions of the Tomcat server, beyond the current 5.5 release, can be integrated into Community Edition in the shortest possible time.

The table below highlights some of the notable difference between the Tomcat 5.5 server running in standalone mode, versus the server integrated into Community Edition.

Table 1. Tomcat 5.5 and Community Edition 1.0 feature comparision
FeatureTomcat 5.5 standaloneWebSphere Application Server Community Edition 1.0
servlets and JSPSame engine is used to process Servlet 2.4 and JSP 1.2 components. No difference than Tomcat 5.5 with respect to the core engine.
multiple connectors Enables multiple protocol handlers to access the same engine. For example, an HTTP 1.1 connector can work with an SSL connector on the same engine. This feature is preserved, and the Community Edition Web console can be used to configure the connectors that will be used.
JNDI JNDI is emulated. You need to manually configure the JNDI resource, usually via server.xml. JNDI has access to GBeans or object references managed by the Apache Geronimo kernel.
realms Realms in Tomcat are databases with user ID and password information. You can configure realms in Tomcat via the server.xml or context.xml files. Community Edition supports container managed security realms, which are available uniformly across the entire container for authentication and authorization of all Community Edition application components.
virtual hosts Enables a single server to host application for multiple domain names. You need to edit server.xml to configure virtual hosts. This feature of Tomcat is supported. You may need to edit j2ee-tomcat-plan.xml and redeploy it to the server.
valves Valve chains can be associated with a Tomcat component. You need to edit server.xml to or context.xml. This feature of Tomcat is supported. You may need to edit j2ee-tomcat-plan.xml and redeploy it to the server.
JDBC datasource Can be configured to use any JDBC driver. It can also be configured to use Apache commons DBCP for pooling. Community Edition utilizes JCA 1.5 support and TranQL implementation to access a variety of RDBMSs through JDBC. Configuration may be performed using the Web-based GUI console.

The key thing to note is that there is no server.xml or context.xml files in Community Edition. The Community Edition container is now handling all the configuration management. Instead, you need to modify one of two deployment plans: either the j2ee-tomcat-plan.xml file or geronimo-web.xml, depending on your specific needs. Some configuration tasks, such as connectors modification, can be accomplished using the Community Edition Web console.

The sample application, which is addressed next, will show some of these modifications during an actual migration.

About the sample application

The sample application we will migrate is a general store application, created using Web-tier components including:

  • JSPs
  • servlets
  • JSP Standard Tag Library (JSTL)

The application uses an MVC (Model-Controller-View) based architecture to route requests, and is totally scriptless (no embedded Java code within JSP pages).

As a Tomcat 5.5 application, it also makes use of the following Tomcat-specific features:

  • Default Tomcat UserRealm to authenticate users.
  • JNDI to lookup for a JDBC data source connecting to an external Derby database.

Figure 2 illustrates the general architecture of the application.

Figure 2. The General Store sample application
The General Store sample application
The General Store sample application

In Figure 2, incoming requests are all directed to the controller (MVC architecture) servlet. This servlet, depending on the parameters of the incoming request, will dispatch the request to one of two JSP pages. Initially, the request is directed to generalstore.jsp, which displays the product catalog. Figure 3 shows the General Store application's product catalog page.

Figure 3. The application catalog page
The application catalog page
The application catalog page

When you click one of the BUY hyperlinks, the Controller will dispatch the request to the checkoutcart.jsp page, which will enable you to add multiple items to the cart, clear the cart, or return to shopping.

Both generalstore.jsp and checkoutcart.jsp use the JSTL extensively to script the interactive shopping cart; no embedded Java code is used.

A class called GerneralStore has a method for obtaining categories, as well as the list of products in each category. In a production scenario, the implementation of this class may connect to external RDBMS for their data. In this example, the implementation has the category and products information hardcoded to keep things simple.

To demonstrate RDBMS via JDBC, the checkoutcart.jsp page uses the RDBMS to fetch today's promotional message and display it to the shopper.

Files that make up the sample application are available in the download ZIP file included with this article. Table 2 summaries the classes and files that make up the application, and describes their purpose.

Table 2. Files in the General Store sample application
generalstore.jsp Presents the catalog to the user.
checkoutcart.jsp Presents the shopping cart to the user. Will access RDBMS through a data source (looked up via JNDI) to display promotional messages.
generalstore.css Stylesheet used to format HTML elements by both JSP pages. Main controller for dispatching requests to JSPs. Also obtains category and product information and attaches them as attributes for JSPs to display. Contains methods that return the data required for the application. Also contains functions that implement a custom tag library (see generalstore-taglib.tld).
JavaBeans used to hold value when data is transferred between the model and view of the application.
generalstore-taglib.tld Custom tag library, implemented as methods of, that are used in the JSPs.

To use this sample application, you must have the following downloaded and installed into your environment:

Deploy to the Tomcat 5.5 environment

Before building the example, go into the build.xml file in the code directory, and modify the wasce.home variable to point to your installation directory. You can build the example Web application by going into the code directory, and then entering the command:

ant war

This will create a WAR file, named generalstore.war, in the dist directory. This is the Web application archive file that you can deploy to Tomcat 5.5.

1. Tomcat 5.5 connectors configuration

The Tomcat 5.5 server listens for requests at port 8080 by default. This is configured through conf/server.xml under the Tomcat 5.5 installation directory. Listing 1 shows the server.xml segment that configures the connector.

Listing1. Tomcat connector configuration in server.xml

<Server port="8005" shutdown="SHUTDOWN">
  <!-- Define the Tomcat Stand-Alone Service -->
  <Service name="Catalina">
    <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
    <Connector port="8080" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true" />

If you need to change the port, you will need to:

  1. Shutdown the server.
  2. Change port="8080" to the port you want in the above server.xml segment.
  3. Start the server again.

2. Tomcat 5.5 authentication realm configuration

A realm maintains user, group, and password information in Tomcat. By default, a UserDatabaseRealm is configured in Tomcat 5.5, enabling you to authenticate a user before letting them access the store. This realm is also setup in the server.xml file. The bold lines in the server.xml code segment in Listing 2 represent the configuration for this authentication realm.

Listing 2. Tomcat UserDatabaseRealm configuration in server.xml

 <Server port="8005" shutdown="SHUTDOWN">
     <Resource name="UserDatabase" auth="Container"
       description="User database that can be updated and saved"
          pathname="conf/tomcat-users.xml" />

  <Service name="Catalina">
    <Engine name="Catalina" defaultHost="localhost">
      <Realm className="org.apache.catalina.realm.UserDatabaseRealm"

The above configuration sets up the UserDatabaseRealm to use a file under conf/tomcat-users.xml to maintain user, password, and role information. Because this realm is configured at the <Engine> level, it is available to all the hosts that are running on the Tomcat <Engine> component instance.

To run our application, you do not have to make any modifications to the conf/server.xml file, as the default configuration will work for us as is. You do, however, need to make some changes to the conf/tomcat-users.xml file, where the UserDatabaseRealm keeps all the user information. Make the change indicated in bold in Listing 3 to the tomcat-users.xml file.

Listing 3. Adding admin and manager roles for the tomcat user in tomcat-users.xml

<?xml version='1.0' encoding='utf-8'?>
  <role rolename="tomcat"/>
  <role rolename="role1"/>
  <user username="tomcat" password="tomcat" roles="tomcat,manager,admin"/>
  <user username="role1" password="tomcat" roles="role1"/>
  <user username="both" password="tomcat" roles="tomcat,role1"/>

This assigns the tomcat user (with password 'tomcat') roles as part of the manager and admin group.

In the application's web.xml file, the store's controller is protected and grants access only to users with an admin role. The bold lines in Listing 4 show the web.xml code (in the dd directory of the code distribution), that protects the application.

Listing 4. web.xml deployment descriptor with authenticated access protection for the application

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns=""
   IBM Community Edition 1.0 Example 
    <display-name>IBM Community Edition 1.0 General Store Example</display-name>

      <display-name>General Store Security Constraint</display-name>
         <web-resource-name>Entire store</web-resource-name>

      <realm-name>Shopping Realm</realm-name>


The <security-constraint> and <security-role> elements in the code above are standard J2EE security configuration elements, and are portable between containers. As such, the same unchanged web.xml will work later in the Community Edition environment. However, before you can deploy and work with the application in Tomcat, you should set up the Derby RDBMS that this application will access.

3. Set up the network Derby server

First make sure you have Apache Derby 10.1 installed. Set the DERBY_INSTALL environment variable to your Derby installation directory, and make sure you have the following elements included in your CLASSPATH environment variable:

  • lib/derby.jar
  • lib/derbytools.jar
  • lib/derbynet.jar
  • lib/derbyclient.jar

In the source code distribution, a supplied sp.bat file can be used to set up these variables for you. If you use this batch file, make sure you first modify it to reflect your own actual Derby installation directory. You can then start the networked Derby server in a console window with the command:

java org.apache.derby.drda.NetworkServerControl start

The Derby server starts and listen at the default port 1527.

Next, create the database that will be used. The name of the database is called generalstore, and it contains only one table called promotions. The createdb1.sql file will perform this creation and populate the database.

Use the ij command to execute the SQL script:

java  createdb1.sql

The createdb1.sql script contains the SQL commands shown in Listing 5.

Listing 5. The createdb1.sql script: Creates database table and fills with data

connect 'jdbc:derby://localhost/generalstore;create=true';
drop table promotion;
create table promotion
  (id char (5) not null,
   message char(40) not null,
   primary key(id));
insert into promotion values ('1', 'Thank your for your order.');
insert into promotion values ('2', 'Have a nice day!');

If you see the message ERROR 08001: No suitable driver, then the required lib/derbyclient.jar library is not in your CLASSPATH environment variable.

4. Tomcat 5.5 JNDI resource reference and JDBC connector

The checkoutcart.jsp page uses JSTL's SQL support tags to access the promotion database and prints out the promotional messages. Listing 6 shows the code excerpt that accesses the RDBMS.

Listing 6. JSP code in checkoutcart.jsp that access the database server

<%@ taglib prefix="c" uri="" %>
<%@ taglib prefix="fmt" uri="" %>
<%@ taglib prefix="storetags" uri="/GeneralStoreTagLibrary" %>
<%@ taglib prefix="sql" uri=""  %>
<sql:query var="rs" dataSource="jdbc/storeDB">
select * from promotion
<td colspan="5">
<c:forEach var="row" items="${rs.rows}">

The JSTL <sql:query> tag will lookup, via JNDI, the datasource named jdbc/storeDB. This name reference is defined in a J2EE standard manner within the web.xml deployment descriptor of the application. This standard configuration will work with both Tomcat 5.5 and Community Edition. Listing 7 shows this configuration.

Listing 7. Element in web.xml specifying the JNDI datasource reference

      <description>Derby DB connection</description>

You now need to configure this reference to match the actual JDBC driver and RDBMS connection. This is done in a container-specific manner, different for Tomcat and Community Edition. For Tomcat 5.5, this can be configured in a META-INF/context.xml file (found in the dd directory) (Listing 8).

Listing 8. Tomcat specific context.xml descriptor associating the JNDI resource with the Derby JDBC connector

<Resource name="jdbc/storeDB" auth="Container" type="javax.sql.DataSource"
               maxActive="100" maxIdle="30" maxWait="10000"
user="APP" password="APP"

Here, the Derby network JDBC driver org.apache.derby.jdbc.ClientDriver is used to access a database at URL jdbc:derby://localhost/generalstore. The Derby server has a default user "APP" with password "APP".

5. Deploy to the Tomcat 5.5 environment with the manager application

To deploy the application WAR file with our customizations, start the Tomcat 5.5 server, and point a Web browser to:


You will be prompted to login; this will be using the UserDatabaseRealm that we set up earlier. Since a manager role is needed, use user 'tomcat' with password 'tomcat'.

The manager application will show all the deployed modules. Scroll to the bottom where it has a box for "Deploy directory or WAR file located on server". For "Context path", enter /Shopping, and for "WAR or Directory URL", enter the absolute path to the generalstore.war file. Press the Deploy button. You should now see the Gerneral Store application running with the /Shopping context. Figure 4 shows the manager application after successful deployment.

Figure 4. Successful deployment of application using Tomcat manager
Successful deployment of application using Tomcat manager
Successful deployment of application using Tomcat manager

Try to access the application using this URL:


Add something to your shopping cart. Note that the promotional message displays, indicating that the Derby RDBMS had been access to obtain these messages.

Migrate the application to Community Edition

In general, to migrate the General Store application to Community Edition 1.0, you need to:

  • Configure and replace the Tomcat UserDatabaseRealm to an authentication realm managed by the Community Edition container.
  • Start and use the IBM Cloudscape™ RDBMS (based on Derby) included in Community Edition, rather than the standalone version of Derby.
  • Create a new data source managed by Community Edition.
  • Create the required database table and fill it with data.
  • Configure a JNDI reference to point to the Cloudscape data source in Community Edition.

The elements that need not be changed during the migration are:

  • JNDI reference to the data source in web.xml.
  • Security configuration protecting the application in web.xml.

These elements are coded carefully to be portable between J2EE containers.

1. Change ports used by Tomcat connectors in Community Edition

If you need to change the port used by Tomcat connectors in Community Edition, do not look for the server.xml file; there isn't one in Community Edition. Instead, take a look at the config.xml file in the var/config directory under the Community Edition installation directory. Listing 9 shows an excerpt of config.xml containing the Tomcat configuration elements with the port numbers bold.

Listing 9. Tomcat connector configuration in Community Edition's config.xml file

<gbean name="TomcatWebConnector">
      <attribute name="host"></attribute>
      <attribute name="port">8080</attribute>
      <attribute name="redirectPort">8443</attribute>
      <attribute name="catalinaHome">var/catalina</attribute>
    <gbean name="TomcatAJPConnector">
      <attribute name="host"></attribute>
      <attribute name="port">8009</attribute>
      <attribute name="redirectPort">8443</attribute>
    <gbean name="TomcatWebSSLConnector">
      <attribute name="host"></attribute>
      <attribute name="port">8443</attribute>

If you change the port number in config.xml and then restart Community Edition. Tomcat will then use your newly configured port.

Alternatively, you can use the Web console instead to add a Tomcat connector, or to edit the port number used with the connector. Just select Server => Web Server from the Web console menu.

2. Configure a Community Edition managed authentication realm

By default, Community Edition manages a realm called "geronimo-properties-realm", which makes use of properties file under the var/security directory to store its user, password, and group information. The only user configured in this realm is "system" with password "manager", belonging to the group/role "admin".

This realm is actually configured in the default Tomcat Host component. You can see this configuration in a deployment plan in the doc/plan directory, called j2ee-tomcat-plan.xml; this is equivalent to the server.xml file you will find on a Tomcat 5.5 server. Listing 10 shows the code where the realm is configured in the Host.

Listing 10. Default configuration of a realm at the Engine component for Tomcat in j2ee-tomcat-plan.xml

    <gbean name="TomcatEngine" class="org.apache.geronimo.tomcat.EngineGBean">
        <attribute name="className">org.apache.geronimo.tomcat.TomcatEngine</attribute>
        <attribute name="initParams">
        <references name="Hosts">
        <reference name="RealmGBean">
        <reference name="TomcatValveChain">

In the Community Edition configuration, all of the components in Tomcat (Engine, Host, and so on) are wrapped in GBeans. The j2ee-tomcat-plan.xml file is essentially a wiring diagram for GBeans with direct parallel to server.xml.

There is no need for us to modify the default configuration in this example, but if you do modify the Tomcat system configuration (for example, to add virtual hosts), you will need to redeploy the plan using the command:

deploy --user system --password manager redeploy new-j2ee-tomcat-plan.xml org/apache/geronimo/Tomcat

Always maintain copies of the original plan in case problems occur.

To make the default realm available to us in the General Store application, you need to create a Community Edition specific deployment plan for the Web application. This plan is called geronimo-web.xml and can be included as part of the WAR file if you place it in the WEB-INF directory. Listing 11 shows how to specify a container realm for the application:

Lisitng 11. Configuring a Community Edition container managed authentication realm for the application

        <sec:default-principal realm-name="geronimo-properties-realm">
        <sec:role role-name="admin">
          <sec:realm realm-name="geronimo-properties-realm">

In Listing 12, notice that the <context-root> is set to "/Shopping" to access the Community Edition application at the same context path as the Tomcat 5.5 version.

The <security-realm-name> specifies the geronimo-properties-realm. The <security> element specifies how the roles of the geronimo-properties-realm maps to the roles referred to in the <security-constraint> element within web.xml.

3. Start the network Cloudscape RDBMS server on Community Edition

Make sure you have shutdown the standalone version of Derby, as it listens at the same port (1527) and will create a conflict.

With Community Edition running, logon to the console, and select Application => J2EE Connectors. Start the configuration called org/apache/geronimo/DefaultDatabase, this is the networked database instance.

4. Create the promotion database table and fill with data

Once the org/apache/geronimo/DefaultDatabase configuration is started, the networked Cloudscape server is listening for requests at the standard port 1527, and you can use the ij command to run the createdb1.sql script:

java  createdb1.sql

This command will create the required database and tables, using the network driver to access the Cloudscape database instance.

5. Create a Community Edition managed data source

To create a Community Edition managed data source, use the console, and select Applications => Database Pools. Click on Add New Datasource on the right pane. Use the values in Table 3 to create your data source.

Table 3. Create a Community Edition managed data source
Name StoreDatasource
JNDI Name Leave this blank
Dependency Select org.apache.derby/jars/ from the list.
Driver Classname org.apache.derby.jdbc.ClientDriver
DB URL jdbc:derby://localhost/generalstore
DB User Name APP
DB Password APP
Pool Max Capacity 20
Pool Initial Capacity 10

Press the Create button to create a Community Edition managed pooled data source called StoreDatasource. This data source is set to access the Community Edition managed instance of the network Cloudscape server.

Upon successful deployment, a new configuration called StoreDatasource is created and started. You can see this configuration by clicking Applications => All Configurations or Applications => J2EE Connectors on the console menu. Figure 5 shows the StoreDatasource configuration running after selecting J2EE Connectors.

Figure 5. StoreDatasource in the running state
StoreDatasource in the running state
StoreDatasource in the running state

6. Associate StoreDatasource with JNDI reference

You can associate the StoreDatasource to the web.xml JNDI reference of jdbc/storeDB using a <resource-ref> element in the geronimo-web.xml deployment plan, as shown in Listing 12.

Listing 12. Associating the container managed StoreDatasource with the application's JNDI resource reference


When we configured this association earlier in Tomcat 5.5, it was using the context.xml file. The Community Edition equivalence of context.xml is the geronimo-web.xml file. Configurations performed here affects only the local application context.

Deploy to Community Edition environment

You can deploy the generalstore.war file to Community Edition 1.0 using the command:

deploy --user system --password manager deploy generalstore.war

You can also deploy the generalstore.war file using the console by clicking on the Applications => All Configurations , and then use the Install New Application box on the right hand pane.

Once you have deployed the application, you can access it using a browser at the same URL:


When you are prompted for login/authentication, use "system" as user and "manager" as password. Try placing something into the shopping cart, and notice that the application now fetches data from Cloudscape and shows the promotional messages: Thank you for your order. Have a nice day! as shown in Figure 6.

Figure 6. The shopping cart with promotion messages from RDBMS
The shopping cart with promotion messages from RDBMS
The shopping cart with promotion messages from RDBMS


Migrating applications from Tomcat 5.5 to WebSphere Application Community Edition 1.0 is straightforward because Tomcat 5.5 is integrated, intact, and is actually part of Community Edition. However, since Community Edition now performs all configuration management, configuration elements typically found in server.xml or context.xml with Tomcat users are now migrated to:

  • config.xml: for quick change parameters, such as port number for connectors.
  • j2ee-tomcat-plan.xml: for Tomcat components such as virtual hosts, realms, and valves configuration; modifications made in this plan must be redeployed to the server to take effect.
  • geronimo-web.xml: the Community Edition-specific deployment plan for an application context; can be included in the WEB-INF directory of the archive.

Stepping through the migration of a Web application from Tomcat 5.5 to WebSphere Application Server Community Edition, we have seen that the major points of this migration included the switching of authentication realms, JNDI reference mapping, setup of a Cloudscape networked server, and the configuration of JDBC connectors.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=WebSphere, Open source
ArticleTitle=WebSphere migrations: Migrate from Apache Tomcat to WebSphere Application Server Community Edition