Before looking at Message Driven Beans (MDBs) a brief overview of the Java Messaging Service (JMS) API is in order. JMS is a way for applications to send and receive messages.

There are three distinct components in JMS:

A destination - is where messages are sent.
A publisher - sends messages to a destination.
A subscriber - tells a destination that it is interested in receiving messages that are sent to the destination. In other words a subscriber recieves messages that are sent to a destination.

For more details on the JMS API see the JCP Specification at the following URL:

http://jcp.org/aboutJava/communityprocess/final/jsr914/index.html

MDBs are different from other Enterprise JavaBeans because clients/users of MDBs, typically do not interact directly with MDBs. Instead they send messages to a JMS Destination and, if the MDB is a registered listener of this destination, the MDB recieves the message and acts accordingly.

This article is organized in the following sections:

MDB implementation analysis

EJB implementations may vary from one vendor to another. The purpose of this section is to provide an EJB specific feature-to-feature comparison between JBoss v4 and Apache Geronimo so you can clearly identify the differences and plan accordingly before migration.

Given that MDBs are dependent on parts of the Java Messaging Service API (JMS), there will be an overlap of some JMS features when comparing the platform specific MDB features.

Features	JBoss v4.0.5	Apache Geronimo
EJB Container	JBoss Application Server comes with its own EJB Container implementation.	Geronimo uses OpenEJB as its EJB Container.
JMS implementation	JBoss Application Server packaged with JBoss MQ.	Geronimo uses ActiveMQ as its JMS implementation.

Back to Top

Sample application

Order processing application has two defined message queues to recieve orders and consignments. Order requests can be generated and sent via the company's web application. When order requests are recieved to the order queue, a MDB will be triggered. It will carry out the next level of order request processing by saving those requests in to a server repository. Those saved order requests will be processed by a company employee later.

The company's sales agents are using the consignment sender application to send consignment (collection of orders) requests from their locations. First, they will prepare consignment as an XML file, then it will be passed as an application parameter. Consignment sender application will read the content of an XML file (with a consignment request) and send it to the consignment queue. General Manager in the company uses the consignment reciever application to find out the consignment requests. When a consignment request recieved to the consignment queue, consignment reciever listener application will download those requests to the General Manager's computer. He will then authorize it and hand it over to a sales employee for further processing.

The following figure gives the overall architecture of the order processing application.

Download the Order manager application from the following link:
[Order Manager|^order_manager.zip]

After extracting the ZIP file, a order_manager directory is created, from now on this directory will be referred as <order_manager_home>.

Application classes and JSP pages

Following are the list of packages and their classes in the system.

org.apache.geronimo.samples.order.client
- ConsignmentReciever - Listening on recieving of consignment requests to a defined queue.
- ConsignmentSender - Send consignment requests to their queue.
org.apache.geronimo.samples.order.ejb
- OrderRecvMDB - A MDB that listens on recieving of order requests to a defined queue.
org.apache.geronimo.samples.order.util
- PropertyLoader - Loads configuration properties to application.
org.apache.geronimo.samples.order.web
- OrderSenderServlet - Creates order requests based on the user input and sends them to respective queue.

Additionally application contains the following list of JSP pages:

index.jsp - The index page wich forwards web request to the main.jsp page.
main.jsp - Order form of the application.
error.jsp - The common error page of the application.

Tools used

The tools used for developing and building the sample application are:

Eclipse

The Eclipse IDE was used for development of the sample application. This is a very powerful and popular open source development tool. Integration plug-ins are available for both JBoss and Geronimo. Eclipse can be downloaded from the following URL:
http://www.eclipse.org

Apache Ant

Ant is a pure Java build tool. It is used for building the war files and populating the database for the Online Brokerage application. Ant can be downloaded from the following URL:
http://ant.apache.org

XDoclet

XDoclet is a tool for generating various artifacts (deployment descriptors, source code) basing on the JavaDoc tags. XDoclet can be downloaded from the following URL:

http://xdoclet.sourceforge.net

Back to Top

The JBoss enviroment

This section shows you how and where the sample JBoss reference environment was installed so you can map this scenario to your own implementation.

Detailed instructions for installing, configuring, and managing JBoss are provided in the product documentation. Check the product Web site for the most updated documents.

The following list highlights the general tasks you will need to complete to install and configure the initial environment as the starting point for deploying the sample application.

1. Download and install JBoss v4.0.5 as explained in the product documentation guides. From now on the installation directory will be referred as <jboss_home>
2. Create a copy of the default JBoss v4.0.5 application server. Copy recursively <jboss_home>\server\default to <jboss_home>\server\<your_server_name>
3. Start the new server by running the run.sh -c <your_server_name> command from the <jboss_home>\bin directory.
4. Once the server is started, you can verify that it is running by opening a Web browser and pointing it to this URL: http://localhost:8080. You should see the JBoss Welcome window and be able to access the JBoss console.
5. Once the application server is up and running, the next step is to install and configure all the remaining prerequisite software required by the sample application. This step is described in the following section.

Install and configure prerequisite software

Compilation of source code of the sample applications is based on Java libraries distributed along with JBoss. The only additional software which is required for building the applications is Apache Ant.

Apache Ant

If you do not have Ant installed, this is a good time for doing so and making sure that <ant_home>\bin directory is added to the path system environment variable. Apache Ant can be downloaded from the following URL:
http://ant.apache.org

XDoclet

If you do not have XDoclet installed, this is a good time for doing so. Although XDoclet installation is not required to build the sources at this time. It will be required for modifying the source code. The XDoclet can be downloaded from the following URL:
http://xdoclet.sourceforge.net

Build the sample application

The Order Management sample application included with this article provides an Ant script that you will use in order to build modules of the application. If you have not downloaded the sample application yet, this is a good time for doing it. Download the Order Management Application from the following link:

[Order Manager|^order_manager.zip]

After extracting the zip file, a order_manager directory is created. From now on this directory will be referred as <order_manager_home>. In the <order_manager_home>/config directory open the build.properties file and edit the geronimo.home & xdoclet.home as given in below.

build.properties

## Set the Geronimo 1.1 home here
geronimo.home=<geronimo_home>

## Set the XDoclet 1.2.3 home here 
xdoclet.home=<xdoclet_home>

From a command prompt or shell go to the <order_manager_home> directory and run the ant jboss command. This will create the EAR file and place it directly into the <order_manager_home>/releases/jboss directory.

Deploy the sample application

To deploy the sample application just copy the OrderManager.ear will be created under the <order_manager_home>/releases/jboss folder to the <jboss_home>/server/<your_server_name>/deploy folder.

If JBoss is already started, it will automatically deploy and start the application; otherwise, the application will be deployed and started at the next startup.

Test the sample application

To test the application, open a Web browser and access the following URL:

http://localhost:8080/order

It will main page of the order management web application. Fill the all requested fields and create an order and place it through this web site.

Back to Top

The Geronimo enviroment

Download and install Geronimo from the following URL:

http://geronimo.apache.org/downloads.html

The release notes available there provide clear instructions on system requirements and how to install and start Geronimo. Throughout the rest of this article we will refer to the Geronimo installation directory as <geronimo_home>.

TCP/IP ports conflict

If you are planning to run JBoss and Geronimo on the same machine consider to change the default service ports on, at least, one of these servers.

Download and install Geronimo from the following URL:
http://geronimo.apache.org/downloads.html

Back to Top

Step-by-step migration

Back to Top

Summary

The sample application used for this migration exercise, while simple, provides you with detailed instructions on how to migrate an application that uses MDB from JBoss V4.0.5 to Apache Geronimo. The modifications to make this happen were restricted to the xml configuration files with no java code changes necessary.