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
- Sample application
- The JBoss environment
- The Geronimo environment
- Step-by-step migration
- Summary
MDB implementation analysis 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. |
Sample application sample
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
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
The JBoss enviroment jboss
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:
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.
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:
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.
The Geronimo enviroment geronimo
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>.
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
Step-by-step migration migration
Summary 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.