WebSphere migrations: Migrate from Gluecode SE or Apache Geronimo to WebSphere Application Server Community Edition

Birds of the same feather make migration simple

For Gluecode Standard Edition or Apache Geronimo users, this article explains how to migrate a J2EE™ application from either of these open source application server environments to IBM® WebSphere® Application Server Community Edition 1.0.

Share:

Sing Li (westmakaha@yahoo.com), Author, Wrox Press

Photo of Sing LiSing Li is a consultant and freelance writer. He has contributed to Beginning JavaServer Pages, Professional Apache Tomcat 5, Pro JSP - Third Edition, Early Adopter JXTA, Professional Jini, Beginning J2ME: From Novice to Professional, Third Edition, and numerous other books. He is also a regular contributor to technical magazines and an active evangelist of the VON and P2P evolutions. You can reach Sing at westmakaha@yahoo.com.



18 November 2005

Also available in

IBM WebSphere Application Server Community Edition is the latest evolution of the Gluecode Standard Edition (SE) open source application server product. If you have been using Gluecode SE to host your Web applications, you will continue to find the familiar, user friendly, Web-based administrative console, as well as many Gluecode SE features (such as JDBC connectors for existing RDBMs), in WebSphere Application Server Community. In addition, WebSphere Application Server Community Edition, which is based on the open source Apache Geronimo Milestone 5 (M5) build, extends Gluecode SE into a full fledged, J2EE 1.4 certified server. You will therefore enjoy additional server capabilities, including built-in support for business tier EJB components.

If you are already using Apache Geronimo M5 to host your enterprise applications, you will find the move to WebSphere Application Server Community Edition to be extremely straightforward -- since its engine is the Apache Geronimo M5 server -- and a compact, robust, and well-supported alternative for your J2EE development efforts.

This article demonstrates how to migrate a sample application from either Gluecode SE 1.1 or Apache Geronimo M5 to WebSphere Application Server Community Edition. We will first deploy the sample application to Gluecode SE, then to Apache Geronimo M5, and finally migrate and deploy it 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: Gluecode, Geronimo, and Community Edition

Community Edition is essentially a merge of the best features of Gluecode SE (such as the user friendly Web console and JDBC support for Microsoft®'s SQL Server) with the robust J2EE certified engine provided by Apache Geronimo M5. Therefore, migrating applications from either Gluecode SE or Apache Geronimo M5 is almost always straightforward and often requires no additional work.

As an open source application server product, Community Edition replaces Gluecode SE 1.1, which is actually based on the Apache Geronimo M4 build, an older cousin of Geronimo M5. One major difference between Community Edition and Gluecode SE (and also the default binary distribution of Geronimo M5) is the Web-tier container. The standard Web-tier container of Gluecode SE 1.1 is Jetty 5.1.4 (and Jetty 5.1.5 for Geronimo M5), while the Web-tier container of Community Edition is Apache Tomcat 5.5. This is largely due to the fact that prior to M4, Jetty was the only choice of Web container with Geronimo. However, from a migration standpoint, this difference is not terribly significant since the version of Tomcat integrated into Community Edition maintains full backward compatibility with the earlier Jetty-based releases. In most cases, your J2EE Web tier assets will consist of:

  • servlets
  • JSPs
  • custom tag libraries
  • code for J2EE compatible programming frameworks.

Both Tomcat and Jetty fully support these J2EE Web-tier components (at the Servlet 2.4 and JSP 2.0 standard level). Table 1 provides a comparision of some key features between the three servers.

Feature comparision between Gluecode SE, Apache Geronimo M5, and WebSphere Application Server Community Edition
FeatureGluecode SE 1.1Geronimo M5Community Edition
J2EE 1.4 certificationNot applicable CertifiedCertified
HTTP serverJetty 5.1Your choice of Jetty 5.1, Tomcat 5.5 HTTP connector, or external Web server.Tomcat 5.5 HTTP connector or external Web server.
Web tier containerJetty 5.1Tomcat 5.5 or Jetty 5.1Tomcat 5.5
Business tier component container Not availableOpenEJB 2.0 serverOpenEJB 2.0 server
Web-based administration and configuration user interfaceConsole availableConsole available, based on Gluecode donated code Console available, merging the best features of Gluecode's console and the Apache Geronimo console.
Built-in JDBC support for popular third party RDBMSs.Support for Oracle®, Micrsoft's SQL Server, and Apache Derby.Support for Apache Derby only. Third party drivers may be added.Support for Oracle, Micrsoft's SQL Server, and IBM Cloudscape™.
Built-in RDBMS supporting JDBCApache Derby 10.0.2 built-inApache Derby 10.1.1.0 built-inIBM Cloudscape built-in; Cloudscape is a supported, commercial adaptation of Apache Derby 10.1.
Built-in message broker supporting JMSActiveMQ 3.1 built-inActiveMQ 3.2 built-inActiveMQ 3.2 built-in
User managementContainer managed, JACC-based user management, administered via console; LDAP realm supported.Configurable flexible login modules, including support for JACC and JAAS. LDAP and Kerboros realms supported.Support Gluecode SE's user management via web console, as well the full-fledged Geronimo container managed security.
Web services supportNone built-in, can add AXISAXIS 1.3 built-inAXIS 1.3 built-in
Core code baseLightweight adaptation of portion of Apache Geronimo Milestone 4Full Apache Geronimo Milestone 5Compact adaptation of Apache Geronimo Milestone 5 (for example, no Jetty support, no Spring framework, no Servicemix, and no directory service integration).
Java VM supportSupport SUN's Java VM 1.4.2Support SUN's Java VM 1.4.2Default configuration uses IBM's Java 1.4.2 VM, also supports SUN's Java™ 1.4.2 VM. Uses IBM's CORBA ORB when running under the IBM Java VM.

As you can see from Table 1, there are more similarity between these servers than there are differences. You will soon see how easy it is to migrate existing applications from these servers to Community Edition.


About the sample application

The sample application, included with this article in the download ZIP file, is a JMS-based application; the ActiveMQ message broker, supporting JMS, is integrated into all three servers (although Gluecode SE contains an older release). A JMS sample application is selected to show how to configure JMS connectors and message destinations on these servers. (For details on JDBC connector and authentication realm configuration, see Migrate from Apache Tomcat to WebSphere Application Server Community Edition.)

Figure 1 shows the components and data flow in this application.

Figure 1. The JMS-based sample application
The JMS-based sample application

As shown in Figure 1, the application consists of a message producer, which is the SenderServlet hosted in the server (Gluecode SE, Geronimo M5, or Community Edition). This servlet presents the user with a data entry form, shown in Figure 2 with text filled in.

Figure 2. Message sender form
Message sender form

The user enters text and selects the Send button. A JMS message is then created and sent to a message queue named SendReceiveQueue. The SendReceiveQueue is managed by the ActiveMQ message broker hosted inside the same server.

In Figure 1, you can see that there is another component, a message consumer called JMSReceiver. This message consumer is not a J2EE application; instead, it is a command line application that is an ActiveMQ client. This consumer application, JMSReceiver, is started waiting for messages to arrive on the message queue. When a user enters a message in the form, the message is immediately received by the command line client and displayed on the console.

Table 2 lists and describes the classes and files that makes up the application.

Table 2. Files in the JMS producer-consumer sample application
FileDescription
SenderServlet.javaA J2EE Web tier component hosted in the server. This is the message producer, presenting a form to the user for message input. It also uses container JNDI support to lookup the message destination: the SendReceive message queue.
JMSReceiver.javaA non-J2EE command line JMS client program. It monitors the SendReceive message queue for up to 5 messages, printing out each one as it receives it.

Required environment

To use this sample application with these instructions, you must have the following downloaded and installed in your environment:


Deploy to the Gluecode environment

Before you build the example, make sure you go into the build.xml file and edit the geronimo.home directory to point to your Gluecode SE installation.

1. Build the deployable WAR file of the sender

You can build the example Web application by going into the code directory and entering the command:

ant war

This will create a WAR file, named sender.war, in the dist directory. This is the Web application archive file that you can deploy to Gluecode SE.

2. Compile and copy ActiveMQ libraries for non-J2EE client

The client source code is in the clientsrc subdirectory. Before you can run the client successfully, you must compile it and copy the ActiveMQ libraries to the mqcient/lib subdirectory. This can be done using the command:

ant client

3. Configure a JMS message queue

In Gluecode SE, the ActiveMQ message broker is started by default, but you will need to create a message queue called SendReceive for the application. You can do this using the Gluecode SE console. Log onto the console and select the JMS link. On the right pane, select Add Queue/Topic, and complete both the Message Destination and Destination Physical Name fields with SendReceiveQueue, as shown in Figure 3.

Figure 3. Add SendReceive message queue
Add SendReceive message queue

Click Submit to add the queue. Note that you may not see it on the console display since the destination name and the physical name are the same. However, you can verify that the configuration is created and running by using this command in the Gluecode SE bin directory:

java -jar deploy.jar --user system --password manager list-modules

You should see the runtimedestination/SendReciveQueue listed. This is the configuration that Gluecode SE creates for you. This configuration maps the "Message destination name" of the queue, used by SenderServlet, to the "Destination Physical Name" -- used by JMSReceiver and the ActiveMQ message broker. If you look at the web.xml deployment descriptor for sender.war, located in the dd subdirectory, you will see the reference link to the queue as shown in Listing 1.

Listing1. Reference link to SendReceive queue in web.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">
	<description>
   developerWorks JMS Example - for WebSphere Application Server Community Edition
    </description>
  ...
<resource-ref>
		<res-ref-name>DefaultActiveMQConnectionFactory</res-ref-name>
		<res-type>javax.jms.QueueConnectionFactory</res-type>
		<res-auth>Container</res-auth>
	</resource-ref>

	<message-destination-ref>
		<message-destination-ref-name>dwSendReceiveQueue</message-destination-ref-name>
		<message-destination-type>javax.jms.Queue</message-destination-type>
		<message-destination-usage>Produces</message-destination-usage>
		<message-destination-link>SendReceiveQueue</message-destination-link>
	</message-destination-ref>

</web-app>

Internal to the SenderServlet, the code looks up the queue and sends a message to it. The code responsible for JNDI lookup from SenderServlet.java is shown in bold in Listing 2.

Listing 2. SenderServlet performing JNDI lookup for JMS queue

public class SenderServlet extends HttpServlet {
	private Context jndiContext = null;
	private QueueConnectionFactory factory = null;
	private Queue receiveQueue = null;
	private static final String QueueName = 
		"java:comp/env/dwSendReceiveQueue";
	private static final String FactoryName =
		"java:comp/env/DefaultActiveMQConnectionFactory";

	public void init() throws ServletException {
		super.init();
		try {
		jndiContext = new InitialContext();
		factory = (QueueConnectionFactory) 
		   jndiContext.lookup(FactoryName);

            receiveQueue = (Queue)
		   jndiContext.lookup(QueueName);
		}
		catch (Exception ex)  {
			ex.printStackTrace();
		}
	}
	  ...

The non-J2EE client calls ActiveMQ directly, without going through JNDI, and asks for a queue named SendReceive.

4. Run the client

To run the client, change the directory to the mqclient subdirectory under the code directory of the code distribution, then enter this command to start the JMSReceiver:

ant

The JMSReceiver will connect to the ActiveMQ message broker at the default port of 61616, and wait for messages to show up at the SendReceive queue.

5. Deploy the sender Web application

Use the Gluecode SE console to deploy the sender application. Click on the Applications link on the left, enter the path to sender.war into the Archive textbox, then click Install. This will install and start the sender application. Figure 4 shows successful deployment of the sender.war.

Figure 4. Successful deploy of sender.war
Successful deploy of sender.war

6. Try out the JMS Web application

After successful deployment, you can access the SenderServlet at the URL: http://localhost:8080/sender/sendform.cgi. Try entering some messages into the form and then click the Send button. Take a look at the running client application, and notice that it is printing out every message that you send from the servlet. Figure 5 shows the JMSReceiver running and receiving messages.

Figure 5. JMSReceiver running, showing received messages
JMSReceiver running, showing received messages

Deploy to the Geronimo environment

Now we will see how the sample application runs in Geronimo M5. Shutdown the Gluecode SE server, if it is running. This will also terminate any JMSReceiver clients that may be running.

Even if you performed the Gluecode deployment steps above, we will need to rebuild our example because Gluecode SE uses a different version of ActiveMQ than Geronimo M5. Othewise, we would see exceptions when the JMSReceiver runs due to mismatched versions. Before you rebuild the example, make sure you go into the Ant build.xml file and edit the geronimo.home directory to point to your Geronimo M5 installation.

1. Build the deployable WAR file of the sender

As usual, you can build the sample Web application by going into the code directory, then entering the command:

ant war

This will create a new sender.war file, usable with Geronimo M5, in the dist directory.

2. Compile and copy ActiveMQ libraries for non-J2EE client

To copy newer Geronimo M5 libraries to the mqclient/lib subdirectory, and to recompile the client, use the command:

ant client

3. Configure a JMS message queue

With Geronimo M5, the default system JMS deployment plan has already created the SendReceiveQueue for us. You can find this deployment plan under the doc/plan subdirectory of the Geronimo M5 installation directory. This is the directory where Geronimo M5 keeps a record of all the system deployment plans that are used for this binary assembly. The plan that you are interested in is called system-jms-plan.xml. Listing 3 shows this plan, with the creation of the SendReceiveQueue highlighted.

Listing 3. The system-jms-plan.xml deployment plan showing configuration of SendReceiveQueue

<?xml version="1.0" encoding="UTF-8"?>
...
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.0"
    configId="org/apache/geronimo/SystemJMS"
    parentId="org/apache/geronimo/ActiveMQServer">
    <resourceadapter>
        <resourceadapter-instance>
            <resourceadapter-name>ActiveMQ RA</resourceadapter-name>
            <config-property-setting name="ServerUrl">
             tcp://0.0.0.0:61616
            </config-property-setting>
            <config-property-setting name="UserName">
             geronimo</config-property-setting>
            <config-property-setting name="Password">
             geronimo</config-property-setting>
            <workmanager>
                <gbean-link>DefaultWorkManager</gbean-link>
            </workmanager>
        </resourceadapter-instance>
        <outbound-resourceadapter>
            <connection-definition>
                <connectionfactory-interface>
                  javax.jms.ConnectionFactory
                </connectionfactory-interface>
                <connectiondefinition-instance>
                    <name>DefaultActiveMQConnectionFactory</name>
                    <implemented-interface>
              javax.jms.QueueConnectionFactory</implemented-interface>
                    <implemented-interface>
              javax.jms.TopicConnectionFactory</implemented-interface>
                    <connectionmanager>
                        <xa-transaction>
                            <transaction-caching/>
                        </xa-transaction>
                        <single-pool>
                            <max-size>10</max-size>
                            <blocking-timeout-milliseconds>
                          5000</blocking-timeout-milliseconds>
                            <match-one/>
                        </single-pool>
                    </connectionmanager>
                </connectiondefinition-instance>
            </connection-definition>
        </outbound-resourceadapter>
    </resourceadapter>
    <adminobject>
        <adminobject-interface>javax.jms.Queue</adminobject-interface>
        <adminobject-class>
      org.codehaus.activemq.message.ActiveMQQueue</adminobject-class>
        <adminobject-instance>
            <message-destination-name>
            MDBTransferBeanOutQueue</message-destination-name>
            <config-property-setting name="PhysicalName">
               MDBTransferBeanOutQueue</config-property-setting>
        </adminobject-instance>
    </adminobject>
    
    <adminobject>
        <adminobject-interface>javax.jms.Queue</adminobject-interface>
        <adminobject-class>
         org.codehaus.activemq.message.ActiveMQQueue</adminobject-class>
        <adminobject-instance>
            <message-destination-name>SendReceiveQueue</message-destination-name>
            <config-property-setting name="PhysicalName">
         SendReceiveQueue</config-property-setting>
        </adminobject-instance>
    </adminobject>
</connector>

Since the Geronimo M5 server is already configured by the system deployment plan, you need only to start it to have the queue avaiable. To see the ActiveMQ broker instance that is running upon server startup, find its administration pages on the Geronimo M5 console by selecting Server => JMS Server. Figure 6 shows the Geronimo M5 console displaying the default ActiveMQ instance that it starts.

Figure 6. The ActiveMQ message broker configuration page on Geronimo M5 console
Figure 6. The ActiveMQ message broker configuration page on Geronimo M5 console

In Figure 6, the ActiveMQ message broker instance supports two transports, in-VM transport for fast interaction between Geronimo M5 components and the message broker, or TCP/IP transport for any external client (such as our non-J2EE JMSReceiver client).

4. Run the client

Change the directory to the mqclient subdirectory under the code directory of the Geronimo code distribution, then run the client using the command:

ant

This starts JMSReceiver as before. The client will connect to the Geronimo M5 managed ActiveMQ message broker, using the TCP transport shown in Figure 6, at the default port of 61616. This client blocks and waits for messages to show up at the SendReceive queue.

5. Deploy the sender Web application

Use the Geronimo M5 console to deploy the sender application. Select Applications => All Configuration. In the "Install New Application" section on the lower right, enter the path to sender.war into the Archive text box, then click the Install button. This will install and start the SenderServlet. Deploying from the Geronimo M5 Web console is almost identical to using the Gluecode SE console.

6. Try out the JMS Web application

After successful deployment, you can access the SenderServlet at the URL: http://localhost:8080/sender/sendform.cgi. Try entering some messages into the form and then Send. The application operates exactly the same as it did with Gluecode SE.


Migrate and deploy to Community Edition

Now, for perhaps the most uneventful migration exercise thus far, you will deploy the application to the Community Edition environment. Since Community Edition is largely composed of Geronimo M5 (with the exclusion of a few non-J2EE modules), the migration requires very little work. Of course, if you are migrating from Gluecode SE to Community Edition, remember that you first need to migrate to Geronimo M5, following the instructions above.

We will not need to rebuild the sample application this time. Community Edition and Geronimo M5's dependency library levels are identical. You also do not need to rebuild the client, since the ActiveMQ broker version of Community Edition is exactly the same as Geronimo M5.

1. Configure a JMS message queue

Identical, again, to Geronimo M5, the default system JMS deployment plan has already created the SendReceiveQueue for us. You will find the same system-jms-plan.xml deployment plan as Geronimo under the doc/plan subdirectory of the Community Edition installation directory. This plan is shown above in Listing 3, with the code creating the endReceiveQueue in bold. Thanks to the compatibility, this is another step we do not need to perform.

On the Community Edition web console, as with Gluecode SE, you can create additional JMS queues and topics. To do so, select Services => JMS. Figure 7 shows the JMS Destination Manager configuration page for adding JMS queues and topics.

Figure 7. Community Edition console page for adding JMS queues and topics
Figure 7. Community Edition console page for adding JMS queues and topics

2. Run the client

Change the directory to the mqclient subdirectory under the code directory of the Community Edition code distribution, then run the client using the command:

ant

With no configuration or compilation change required, the JMSReceiver will start, and the client will connect to the Community Edition managed ActiveMQ message broker. The client blocks and waits for messages at the SendReceive queue.

3. Deploy the sender Web application

Using the Community Edition console to deploy the sender application is exactly the same as with Geronimo M5. Select Applications => All Configuration, find the "Install New Application" section on the lower right, enter the path to sender.war into the Archive text box, and then click the Install button.

4. Try out the JMS Web application

After successful deployment, run and verify that the application operates exactly the same as it did when it was first hosted under Gluecode SE, and later Geronimo M5. This migration from Geronimo M5 to Community Edition requires no additional work.


Conclusion

In this article, we migrated a JMS-based sample application from Gluecode SE to WebSphere Application Server Community Edition, and from Apache Geronimo M5 to Community Edition, in both cases with very minor configuration changes, then recompiled to accomodate updated ActiveMQ libraries.

Since WebSphere Application Server Community Edition is based on Apache Geronimo M5, the migration of applications from Geronimo to Community Edition is straightforward and requires little or no work. Gluecode SE is based on the Apache Geronimo M4 build, yet migrating applications from Gluecode SE to Community Edition is also quite straightforward. As we have seen through these examples, with Community Edition you can rely on the user-friendly Web-based console for much of your deployment, administration, and configuration needs.


Download

DescriptionNameSize
Sample application for migration exerciseGer-Glu-to-WASCE-sampleapp.ZIP  ( HTTP | FTP | Download Director Help )15 KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Open source
ArticleID=98976
ArticleTitle=WebSphere migrations: Migrate from Gluecode SE or Apache Geronimo to WebSphere Application Server Community Edition
publish-date=11182005