{scrollbar}

top

Enterprise messaging has become an increasingly important component of loosely coupled, reliable enterprise frameworks. This is due in large part to the proliferation of enterprise applications and disparate enterprise resources, and the increasing need to integrate these applications into cohesive systems. Over the years Messaging and Message Oriented Middleware (MOM) has provided this integration proprietory manner. Introduction of Java Messaging Service (JMS) as a standard, eliminated many of the disadvantages in proprietory MOM based products. In addition,Message Driven Beans(MDBs) introduced together with Enterprise Java Beans 2.0 have served to get the best out of existing investments in J2EE application servers. Most of the J2EE application servers in modern era are acting as a MOM with a whole lot of value added services to JMS. As a J2EE 1.4 certified application server, Apache Geronimo comes into the party with support of JMS integrating with one of the best breed open source messaging frameworks, ActiveMQ. This article will provide you with a way to use JMS for your enterprise application scenario both as a local and remotely reffered environments with Geronimo and ActiveMQ.

The company reffered in this sample application sells one specific item in both retail and wholesale markets under different categories. All the placed orders in the application have to be authorized by a company sales employee before delivering goods to the customer. For the wholesale market, the company has placed their agents all over the country. They send their orders as a bunch at once, which is called a consignment. End users place their orders using the company web site while agents send their consignments with a special software installed in their premises. All the consignments must be approved by the company General Manager before it is handed over to a sales employee.

This is a typical application to use JMS as a solution because both consignment and order requests are processed in asynchronous manner.

After reading this article, you should be able to define Message Queues and their Connection Factories in Geronimo/ActiveMQ environment, send and recieve messages using different kinds of applications in your Enterprise Application with ease.

This article is organized into following sections.

Overview of JMS in Geronimo/ActiveMQ Enviroment overview

Geronimo server comes with a JMS server and application components that can access JMS resources like connection factories, topics and queues from it. This JMS server is also known as message broker. The default message broker supported by Geronimo is ActiveMQ, usually does not need to be changed since it is a mature and feature-rich JMS product. This implementation uses inbuilt Derby database for the message persistent features.

ActiveMQ supports a large variety of transports (such as TCP, SSL, UDP, multicast, intra-JVM, and NIO) and client interactions (such as push, pull, and publish/subscribe). In the Geronimo context ActiveMQ supports MDBs, which are EJBs that consume JMS messages. It allows JMS applications to take J2EE specific features from Geronimo and application components such as JSPs, Servlets or EJBs utilizing JMS. Geronimo has implemented this JMS API in an abstract layer to support any JMS provider. It has achieved this feature by supporting J2EE Connector (JCA) specification. The JCA 1.5 specification details the contracts required between the application server and the driver supplied by ActiveMQ (resource adapter). Applications deployed in the Geronimo access ActiveMQ message broker only through this resource adapter(RA).

Application Overview 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.

Application contents

The order placement application consist of following list of packages and classes.

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.

Finally, the core of the order placement application will be deployed as an EAR to the application server. Overview of the contents of EAR is given in the following depiction.

java

First, we will look at defining the connection factories and queues in the Geronimo server using jms-resource-plan.xml. It defines two JMS queues and a common queue connection factory to access them.

xmlsolidjms-resource-plan.xml

<?xml version="1.0" encoding="UTF-8"?> <connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>samples</dep:groupId> <dep:artifactId>jms-resources</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>rar</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>activemq-broker</dep:artifactId> <dep:type>car</dep:type> </dep:dependency> </dep:dependencies> </dep:environment> <resourceadapter> <resourceadapter-instance> <resourceadapter-name>CommonConnectionFactory</resourceadapter-name> <config-property-setting name="Password">geronimo</config-property-setting> <config-property-setting name="UserName">geronimo</config-property-setting> <nam:workmanager xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.1"> <nam:gbean-link>DefaultWorkManager</nam:gbean-link> </nam:workmanager> </resourceadapter-instance> <outbound-resourceadapter> <connection-definition> <connectionfactory-interface>javax.jms.QueueConnectionFactory</connectionfactory-interface> <connectiondefinition-instance> <name>CommonConnectionFactory</name> <connectionmanager> <xa-transaction> <transaction-caching/> </xa-transaction> <single-pool> <match-one/> </single-pool> </connectionmanager> </connectiondefinition-instance> </connection-definition> </outbound-resourceadapter> </resourceadapter> <adminobject> <adminobject-interface>javax.jms.Queue</adminobject-interface> <adminobject-class>org.activemq.message.ActiveMQQueue</adminobject-class> <adminobject-instance> <message-destination-name>OrderQueue</message-destination-name> <config-property-setting name="PhysicalName">OrderQueue</config-property-setting> </adminobject-instance> <adminobject-instance> <message-destination-name>ConsignmentQueue</message-destination-name> <config-property-setting name="PhysicalName">ConsignmentQueue</config-property-setting> </adminobject-instance> </adminobject> <adminobject> <adminobject-interface>javax.jms.Topic</adminobject-interface> <adminobject-class>org.activemq.message.ActiveMQTopic</adminobject-class> </adminobject> </connector>

In this application there is a MDB that will listen on OrderQueue. openejb-jar.xml defines Geronimo specific features of that MDB. It links OrderRecv MDB with OrderQueue via CommonConnectionFactory.

xmlsolidopenejb-jar.xml

<openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1" xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1" xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1" xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"> <sys:environment> <sys:moduleId> <sys:groupId>samples</sys:groupId> <sys:artifactId>OrderEjb</sys:artifactId> <sys:version>1.0</sys:version> <sys:type>car</sys:type> </sys:moduleId> <sys:dependencies> <sys:dependency> <sys:groupId>geronimo</sys:groupId> <sys:artifactId>activemq-broker</sys:artifactId> <sys:type>car</sys:type> </sys:dependency> <sys:dependency> <sys:groupId>samples</sys:groupId> <sys:artifactId>jms-resources</sys:artifactId> <sys:version>1.0</sys:version> <sys:type>rar</sys:type> </sys:dependency> </sys:dependencies> <sys:hidden-classes/> <sys:non-overridable-classes/> </sys:environment> <enterprise-beans> <message-driven> <ejb-name>OrderRecvMDB</ejb-name> <resource-adapter> <resource-link>CommonConnectionFactory</resource-link> </resource-adapter> <activation-config> <activation-config-property> <activation-config-property-name>destination</activation-config-property-name> <activation-config-property-value>OrderQueue</activation-config-property-value> </activation-config-property> <activation-config-property> <activation-config-property-name>destinationType</activation-config-property-name> <activation-config-property-value>javax.jms.Queue</activation-config-property-value> </activation-config-property> </activation-config> </message-driven> </enterprise-beans> </openejb-jar>

geronimo-application.xml and application.xml define the main components of the EAR. Both EJB component and Web archive information are given in these files as usual.

xmlsolidgeronimo-application.xml

<application xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>samples</dep:groupId> <dep:artifactId>Order</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>car</dep:type> </dep:moduleId> <dep:dependencies/> <dep:hidden-classes/> <dep:non-overridable-classes/> </dep:environment> </application>

xmlsolidapplication.xml

<?xml version="1.0" encoding="UTF-8"?> <application 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/application_1_4.xsd" version="1.4"> <module> <ejb>OrderEjb.jar</ejb> </module> <module> <web> <web-uri>OrderWeb.war</web-uri> <context-root>/Order</context-root> </web> </module> </application>

Order Processing Web application sends messages to the Order Queue. OrderSenderServlet will handle the relevant order request generation and the sending. web.xml of the archive has the relevant configurations for the both queue connection factory and the queue, which is essential to refer resources in a local enviroment.

xmlsolidweb.xml

<?xml version="1.0" encoding="UTF-8"?> <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"> <servlet> <display-name>OrderSenderServlet</display-name> <servlet-name>OrderSenderServlet</servlet-name> <servlet-class>org.apache.geronimo.samples.order.web.OrderSenderServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>OrderSenderServlet</servlet-name> <url-pattern>/order</url-pattern> </servlet-mapping> <resource-ref> <res-ref-name>jms/CommonConnectionFactory</res-ref-name> <res-type>javax.jms.QueueConnectionFactory</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref> <message-destination-ref> <message-destination-ref-name>jms/OrderQueue</message-destination-ref-name> <message-destination-type>javax.jms.Queue</message-destination-type> <message-destination-usage>Produces</message-destination-usage> <message-destination-link>OrderQueue</message-destination-link> </message-destination-ref> <welcome-file-list> <welcome-file>/jsp/index.jsp</welcome-file> </welcome-file-list> </web-app>

Please note that this web application supports Servlet 2.4 specification. Some of the configurations in older versions (2.3) are slightly different than given in the above web.xml.

geronimo-web.xml will act as a mediator between defined JMS resources in the application server and the web.xml.

xmlsolidgeronimo-web.xml

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1" xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"> <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1"> <dep:moduleId> <dep:groupId>samples</dep:groupId> <dep:artifactId>OrderWeb</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>car</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>geronimo</dep:groupId> <dep:artifactId>activemq-broker</dep:artifactId> <dep:type>car</dep:type> </dep:dependency> <dep:dependency> <dep:groupId>samples</dep:groupId> <dep:artifactId>jms-resources</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>rar</dep:type> </dep:dependency> </dep:dependencies> <dep:hidden-classes/> <dep:non-overridable-classes/> </dep:environment> <context-root>/Order</context-root> <resource-ref> <ref-name>jms/CommonConnectionFactory</ref-name> <resource-link>CommonConnectionFactory</resource-link> </resource-ref> <resource-env-ref> <ref-name>jms/OrderQueue</ref-name> <admin-object-link>OrderQueue</admin-object-link> </resource-env-ref> </web-app>

The next important part of this sample application is how to send messages from out side the application server context. Consignment sender will handle it for the application as given below.

javasolidConsignmentSender.java

Context ctx = new InitialContext(env); QueueConnectionFactory factory = (QueueConnectionFactory) ctx.lookup(propLoader.getValue(CONNECTION_FACTORY_NAMES)); conn = factory.createQueueConnection(); Queue myQueue = (Queue) ctx.lookup(propLoader.getValue(QUEUE_NAME)); session = conn.createQueueSession(false,javax.jms.Session.AUTO_ACKNOWLEDGE); producer = session.createProducer(myQueue); conn.start(); consignmentMessage = session.createTextMessage(); consignmentMessage.setText(content); producer.send(consignmentMessage); System.out.println("Consignment Sent !!!");

How to listen on a JMS queue other than a MDB? The answer for this question can be found in the consignment reciever application.

javasolidConsignmentReciever.java

System.out.println("Start Listening Consignment Data "); ActiveMQConnectionFactory connectionFactory = new ActiveMQConnectionFactory(propLoader.getValue(PROVIDER_URL)); connection = (QueueConnection)connectionFactory.createConnection(); connection.start(); session = connection.createQueueSession(false,Session.AUTO_ACKNOWLEDGE); Queue queue = session.createQueue(propLoader.getValue(QUEUE_NAME)); consumer = session.createConsumer(queue); while(true){ Message message = consumer.receive(); processMessage(message); }

Tools used

The tools used for developing and building the order placement application are:

XDoclet

XDoclet is an open source code generation engine. It enables Attribute-Oriented Programming for java. In short, this means that you can add more significance to your code by adding meta data (attributes) to your java sources. This is done in special JavaDoc tags.
Although XDoclet originated as a tool for creating EJBs, it has evolved into a general-purpose code generation engine. XDoclet consists of a core and a constantly growing number of modules. It is fairly straightforward to write new modules if there is a need for a new kind of component.
http://xdoclet.sourceforge.net/xdoclet/index.html

Eclipse

The Eclipse IDE was used for development of the sample application. This is a very powerful and popular open source development tool. It has integration plug-ins for the Geronimo too. 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 for the Inventory application. Ant can be downloaded from the following URL:
http://ant.apache.org

Back to Top

Configuring, Building and Deploying the Sample Application configure

Download the order processing application from the following link:
Order

After decompressing the given file, the Order directory will be created.

Configuring

Configuration of the application consists of creating JMS resources and accessing them via different sorts of environments.

Creating JMS Specific Resources

All JMS specific resource information can be found in the config/jms-resource-plan.xml file. Follow the given instructions to deployment, after logging into the Geronimo console.

Select Deploy New link from the Console Navigation in the left.
Load the <geronimo_home>/repository/geronimo/ge-activemq-rar/1.1.1/ge-activemq-rar-1.1.1.rar file to the Archive field.
Load the Order/config/jms-resource-plan.xml file to the Plan input field.
Press Install button. Make sure Start app after install is selected when this deployment happens
Upon successful installation message, verify the deployment by traversing JMS resources link. It will display the connection factory and two JMS queues.

Modify Property Files

This application has two very important property files in the config folder namely build.properties and order_mgmt.properties. Build process of the application entirely depends on the build.propeties and application will use order_mgmt.properties to load application related properties.

Set the correct paths for the xdoclet.home and geronimo.home directories to perform the application build process correctly.

xmlsolidbuild.properties

## Set the Geronimo 1.1 Home geronimo.home=/home/lsf/Lasantha/geronimo-1.1 ## Set the XDoclet Home xdoclet.home=/home/lsf/Lasantha/xdoclet-1.2.3

This build script depends on XDoclet version 1.2.3 and Geronimo 1.1.1. Also make sure to use "/" as you directory separator in Windows environment when you are setting the properties.

xmlsolidorder_mgmt.properties

########################################################### ## Order Sender(Web Application) Properties # Connection Factory Name. jms.connection=java:comp/env/jms/CommonConnectionFactory # Queue Name. jms.queue=java:comp/env/jms/OrderQueue ########################################################### ## Order Reciever(EJB Application) Properties # Change a directory in server to store order requests. order.repo=/home/lsf/Lasantha/Temp/order ########################################################### ## Consignment Sender Properties # Queue connection factory type. java.naming.factory.initial=org.activemq.jndi.ActiveMQInitialContextFactory # Server location, change according to your enviroment. java.naming.provider.url=tcp://localhost:61616 # Connection factory names. connectionFactoryNames=CommonConnectionFactory # Queue name. queue.ConsignmentQueue=ConsignmentQueue ########################################################### ## Consignment Reciever Properties # Provider url, change according to your enviroment. provider.url=tcp://localhost:61616 # Queue name. queue.name=ConsignmentQueue # Change a directory in client machine to store consignment requests. consignment.dir=/home/lsf/Lasantha/Temp/consignment

order_mgmt.properties file given is shared among four defferent application components. You may have to change those properties according to your local enviroment as given below.

Order Reciever Application
Point order.repo to a directory in the application server host.
Consignment Sender Application
Change java.naming.provider.url value according to the application server network information.
Consignment Reciever Application
Both provider.url and consignment.dir properties has to be changed. provider.url has to change according to server network information. consignment.dir need to point to a directory in the application deployed machine.

If you deploy one of these application components out side of application server, make sure you change the relevant network property in the above mentioned property file.

Building

Use a command prompt to navigate into the Order directory and just give ant command to build. It will create the Order.ear, recvclient.jar and sendclient.jar under the Order/releases folder. Also note it will create a lib folder and copy list of jar files reffered by the remote client applications. Now you are ready to deploy order processing application into the Geronimo Application server.

Deploying

Deploying Order processing sample application is pretty much the same as the deployment of JMS resources.

Navigate to Deploy New from the Console Navigation panel.
Load Order.ear from Order/releases folder in to the Archive input box.
Press Install button to deploy application in the server.

Back to Top

Testing of the Sample Application testing

Core business functionality of the order processing application is shared among the three different client applications. Testing of each client is can be done as given.

Order Placement Web Application

To test the sample web application open a browser and type http://localhost:8080/Order. It will forward you in to the Order Management Welcome page. Then user has to fill the necessary information for the order placement and submit it.

Consignment Placement Remote Application

This application will send consignment requests to the consignment queue. It will take consignment file as a command line argument and send it to the relevant queue. For the testing of this application a sample consignment has been given with the appication archive as Order/config/sample-consignment.xml. First travel to the Order folder from a command prompt and give the following command.

ant run-send-client -Dsendfile=<home>/Order/config/sample-consignment.xml

#000000solid lsf@lsf-laptop:~/workspace/Order/releases$ ant run-send-client -Dsendfile=config/sample-consignment.xml Buildfile: build.xml run-send-client: [java] Working directory ignored when same JVM is used. [java] Feb 7, 2007 1:51:31 PM org.activemq.ActiveMQConnection statusChanged [java] INFO: channel status changed: Channel: TcpTransportChannel: Socket[addr=localhost/127.0.0.1,port=61616,localport=48126] has connected [java] Consignment Sent !!! BUILD SUCCESSFUL

Consignment Listener Remote Application

Listener application to the consignment queue. It will download the consignment requests in the local repository. As in the above mentioned application, first navigate to the Order folder through command prompt. Then, issue the following command to start listening on the consignment queue.

ant run-recv-client

#000000solid lsf@lsf-laptop:~/workspace/Order/releases$ ant run-recv-client Buildfile: build.xml run-recv-client: [java] Start Listening Consignment Data [java] Feb 7, 2007 1:49:57 PM org.activemq.ActiveMQConnection statusChanged [java] INFO: channel status changed: Channel: TcpTransportChannel: Socket[addr=localhost/127.0.0.1,port=61616,localport=48125] has connected [java] Received a Consignment: [java] <?xml version="1.0" encoding="UTF-8"?> [java] <Consignment id="001"> [java] <Branch id="123"/> [java] <Orders> [java] <Order orderId="234" custId="889" qty="90" model="101"/> [java] <Order orderId="235" custId="776" qty="69" model="102"/> [java] <Order orderId="236" custId="245" qty="74" model="103"/> [java] <Order orderId="237" custId="232" qty="55" model="105"/> [java] <Order orderId="238" custId="354" qty="44" model="106"/> [java] <Order orderId="239" custId="267" qty="97" model="107"/> [java] </Orders> [java] </Consignment>

Summary summary

This article has demonstrated the use of JMS features in Apache Geronimo with the ActiveMQ JMS server.It provides a hypothetical example which extensively used JMS features.

Some of the highlights of this article : -

Apache Geronimo is a J2EE 1.4 Certified application server that provides all the necessary features to support asynchronous mode of communication in enterprise applications.
Define JMS connection factories and related queues in a Geronimo enviroment.
Message Driven Beans are the components listening on JMS queues providing by the J2EE container.
Sending and recieving data to a defined queue as a remote client.