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:

• Implementation analysis: Gluecode, Geronimo, and Community Edition
• About the sample application
• Deploy to the Gluecode environment
• Deploy to the Geronimo environment
• Migrate and deploy to Community Edition

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.

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.

Back to top

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.

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.

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.

Required environment

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

• Apache Ant 1.6.5
• Gluecode SE 1.1 (if you are migrating from Gluecode SE)
• Apache Geronimo Milestone 5 (if you are migrating from Apache Geronimo)
• IBM WebSphere Applicaion Server Community Edition 1.0

Back to top

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.

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.

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.

Back to top

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.

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.

Back to top

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.

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.

Back to top

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.

Back to top

Download

Description	Name	Size	Download method
Sample application for migration exercise	Ger-Glu-to-WASCE-sampleapp.ZIP	15 KB	FTP|HTTP|Download Director

Information about download methods

Resources

Learn

• IBM WebSphere Application Server Community Edition resources
  
  
• Get started now with Apache Geronimo
  
  
• Gluecode Web site
  
  
• IBM WebSphere Application Server Community Edition, Apache Geronimo, and Gluecode: What is IBM's direction?
  
  
• Magic with JMS, MDBs, and ActiveMQ in Geronimo
  
  

Get products and technologies

• Download the latest version of IBM WebSphere Application Server Community Edition
  
  
• Download an earlier version of IBM WebSphere Application Server Community Edition
  
  

Discuss

• Participate in the discussion forum.
  
  

About the author

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

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Implementation analysis: Gluecode, Geronimo, and Community Edition
• About the sample application
• Deploy to the Gluecode environment
• Deploy to the Geronimo environment
• Migrate and deploy to Community Edition
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

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

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers