Original URL: http://www.theregister.co.uk/2007/09/25/java_message_services/

Programming message services in Java

Asynchronous interactions seem to be the way of the future

By John Hunt

Posted in Developer, 25th September 2007 17:40 GMT

Lately I seem to be involved increasingly in systems relying on asynchronous interactions for efficient and effective integration. In these cases, the asynchronous behaviour has been implemented using JMS (or Java Message Service) queues, with message driven beans, and with the underlying message server provided by application servers such as WebLogic, WebSphere and JBoss.

As a point to note, "asynchronous" here indicates that the initiating process (the client) returns immediately that a message is sent rather than waiting for the invoked process to complete before returning. This is usually desirable if the invoked process is long running or may require human intervention.

Although JMS has been around for some time, I’ve found that knowledge of how JMS works and its use with EJB3 Message Driven Beans is actually quite limited and I realise that I’ve never actually written a column about JMS before. This Java column therefore looks at what JMS is, how it works, and at the use of queues. It also provides an example of implementing a JSM client and an EJB3 based Message Driven Bean (MDB) to act as the consumer of JMS messages.

Java Message Service

The Java Message Service (more commonly referred to as JMS) is a standard Java Standard Edition API that can be used to access a variety of different message servers. Although the name might suggest otherwise, it’s not of itself a message service, but rather a generic interface to a message server.

In this sense, it’s similar to the JDBC and JNDI, in that it is trying to provide a standardised and unified interface to a variety of disparate vendor specific message servers. In the case of JMS, you use JMS to interface to message services such as IBM’s MQ Series message service, the JBoss MQ messaging system, or Oracle AQ queues etc.

The JMS API is defined within the javax.jms package. This package defines numerous interfaces, only two classes, and a number of exceptions. Before going into further detail about JMS we’ll look at the general concepts behind messaging services.

What is a message service?

So what is a message service? A message service provides for distributed, loosely coupled communication between software components or applications. That is, it allows an application running on one host using one particular technology to communicate with another application running on another host, without the two clients needing to know anything directly about each other.

The communication is achieved by an intermediary, called the queue, on which a message can be placed, and from which messages can be read. As the intermediary is a queue, the general rule is that messages are read form the queue in a First In/First Out (or FIFO) manner.

Illustrates typical message queuing.

For example, in the above diagram (Figure 1), two message producers send messages to a queue. The queue sends the message onto the message consumer in a different thread of execution. Thus, the producers are not blocked while the consumer is processing the message. The messages may be held in the queue until the consumer is available to process them and delivery of the message to the consumer may be guaranteed (the promise of IBM’s MQ Series, for example, to deliver messages once and once only, was an important contribution to processing integrity when it first came out – Ed).

In addition, a message service may support many-to-one connections as above, or many-to-many as supported by the JMS topic concept. Both queues and topics can alter the order in which messages are retrieved using concepts such as priorities etc.

Implementing the producers and consumers

So, now we have the basic concepts of a message service, how do we use JMS to create producers and consumers of messages using the JMS API? To explore these concepts, I’ll step through the definition of a message producer and the implementation of an EJB3 based Message Driven Bean. Note that I could just implement a stand alone message consumer application, (it does not need to be an EJB) however, in my experience in a Java Enterprise Edition environment, it’s much more common to use an EJB for this; and EJBs make the whole process so much easier.

As the application server used to support our example, I’ll be using JBoss (in particular, I’m using JBoss 4.2.1) and the JBossMQ message service. Note that it’s also possible with JBOSS 4.2.1 to use the newer JBOSS Messaging JMS provider, which can give better performance than the older JBossMQ system and which replaces it entirely in JBoss 5.x. However, this requires some configuration and from a Java perspective it is hidden behind the façade of the JMS API.

Having sorted our message service provider, we can now consider the steps we must follow to create our JMS based application. These steps are presented below:

  1. Publish destinations (queues) using a server-specified mechanism. This can be done in JBoss using the JBossmq-destinations-service.xml file. Essentially this is a JNDI entry that is used to define a queue (or topic) as a destination.
  2. Define producers that generate messages.
  3. Define consumers that receive messages (note there is nothing to stop a client being both a producer and a consumer).
  4. Start the message server.
  5. Compile and start the producers and consumers.

We shall follow each of these steps below for a simple queue based application.

Publish destinations

How a destination is published is message service dependent. In the case of the JBossMQ message server a destination can be published by providing an entry in the JBossmq-destinations-service.xml file (found under the \server\default\deploy\jms directory for the default Jboss server configuration). By default a number of queues are already defined and we will use one of these, the queue/testQueue. By contrast, in WebLogic and WebSphere queues can be defined using the application server consoles.

The entry for the JBossmq-destinations-service.xml file for the queue/testQueue is presented below:

  <mbean code="org.jboss.mq.server.jmx.Queue"
         name="jboss.mq.destination:service=Queue,name=testQueue">
    <depends optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
    <depends optional-attribute-name="SecurityManager">jboss.mq:service=SecurityManager</depends>
    <attribute name="MessageCounterHistoryDayLimit">-1</attribute>
    <attribute name="SecurityConf">
      <security>
        <role name="guest" read="true" write="true"/>
        <role name="publisher" read="true" write="true" create="false"/>
        <role name="noacc" read="false" write="false" create="false"/>
      </security>
    </attribute>
  </mbean>

Define a client

To send a message to a JMS message server queue, there are a number of steps that must be performed. These steps are the same whether you wish to send the message from a stand-alone application, from a Servlet or JSP, or indeed from an Enterprise JavaBean. These steps are:

Step 1: Obtain a queue connection factory. A queue connection factory is used to create the queue connection object used to handle the connection to the message servers’ queue.

Step 2: Create a queue connection. This is done by calling the createQueueConnection method on the factory object just obtained.

Step 3: Create a queue session. A queue session is obtained from the queue connection, as illustrated below:

QueueSession qs = 
             qc.createQueueSession(false, 
             Session.AUTO_ACKNOWLEDGE);

The first argument to the createQueueSession method above indicates that this is not part of a transaction. The second argument indicates that the queue session automatically acknowledges messages when they have been received successfully. Until a JMS message has been acknowledged, it is not considered to be successfully consumed.

Step 4: Look up the queue. This is done by using the initial context object we created earlier and looking up the queue using its JNDI name (e.g. queue/testQueue).

Step 5: Create a queue sender. A queue sender is a message producer that allows messages to be sent to the specified queue. A queue sender is created using the createSender method on the queue session:

Step 6: Create the message object.

Step 7: Send the message via the QueueSender object created in step 5.

Step 8: Close the queue connection.

At this point, the client will have sent a message to the JMS message server available within the JBoss application server.

The complete JMS client is presented below, based on the above description:

package com.regdeveloper.jms.client;

import javax.jms.Queue;
import javax.jms.QueueConnection;
import javax.jms.QueueConnectionFactory;
import javax.jms.QueueSender;
import javax.jms.QueueSession;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.naming.Context;
import javax.naming.InitialContext;

public class NewsClient {

   public static void main(String [] args) throws Exception {
      if (args.length == 0) {
         printUsage();
      } else {
         String text = args[0];
         System.out.println("Sending Msg: " + text);
         
         Context context = new InitialContext();
         System.out.println("Got Initial Context");
         // Get connection factory from naming service
         QueueConnectionFactory f =  
                 (QueueConnectionFactory)
                            context.lookup("ConnectionFactory");
         System.out.println("Obtained queue connection factory");
         // Create the connection
         QueueConnection qc = f.createQueueConnection();
         System.out.println("Obtained the queue connection");
         // Create the session
         QueueSession qs = 
             qc.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
         System.out.println("Obtained the queue session");
         // Note queue must be placed before the queue name
         Queue q = (Queue)context.lookup("queue/testQueue");
         System.out.println("Obtained the queue: " +
                                q.getQueueName());
         QueueSender sender = qs.createSender(q);
         TextMessage message = qs.createTextMessage();
         message.setText(text);
         System.out.println("Sending message to queue");
         sender.send(q, message);
         System.out.println("Message sent");
         // Must close the connection
         qc.close();
      }  
   }
   public static void printUsage() {  
         System.out.println("java NewsClient <message>"); 
   }
}

The consumer

In our case, our consumer will be a Message Driven Bean (MDB). This is a type of Enterprise Java Bean (or EJB) that can be deployed within a J2EE application server such as JBoss. However, unlike other EJBs it only has an implementation class. In addition, the lifecycle of a MDB is also simpler than that of either session beans or entity beans. This is because all communication with a MDB is via a JMS queue or topic, no direct synchronous interaction is allowed.

With the advent of EJB3, the creation and definition of all EJBS and of MDBs in particular has become a lot simpler. It is only now necessary to implement the MessageListener interface (a standard JMS interface) and to use some annotations to completely define your MDB. The MessageListener interface defines a single method, namely the onMessage method.

package com.regdeveloper.jms.mdb;

import javax.ejb.ActivationConfigProperty;
import javax.ejb.MessageDriven;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageListener;
import javax.jms.TextMessage;

@MessageDriven(name="NewsMessageDrivenBean", 
         activationConfig = {
            @ActivationConfigProperty(
                    propertyName="destinationType", 
                    propertyValue="javax.jms.Queue"),
            @ActivationConfigProperty(
                    propertyName="destination", 
                    propertyValue="queue/testQueue")
})
public class NewsMDB implements MessageListener {

   public void onMessage(Message message) {
      try {
         String text = ((TextMessage)message).getText();
         System.out.println("In the onMessage method(" + text + ")");  
      } catch (JMSException exp) {
         exp.printStackTrace();
      }
   }
   
}

The annotations on the class (the elements before the class definition starting with an “@” sign) are used to specify to the application server how to bind the message driven bean to an appropriate JMS queue. In this case, we give the MDB a name (“NewsMessageDrivenBean”) and a configuration to be used during deployment. This configuration indicates that the MDB should be bound to a queue and that the queue to bind it to has a JNDI name of “queue/testQueue”.

The MDB is packaged up in a jar file (news.jar) and placed within an EAR file using the following application.xml file:

<?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"> 
        <display-name>News MDB App</display-name> 
        <module> 
                <ejb>news.jar</ejb> 
        </module> 
</application> 

Deployment and execution

To deploy to JBoss, the ear file can be copied to the ${JBoss.home}/server/default/deploy directory and the JBoss server started. As JBoss starts up, it will discover the new jar file and deploy it automatically (which makes deploying to JBoss very easy). As the JBoss server is being started up, you should see messages telling you that it is deploying the new ear file and linking the MDB to the queue.

After the JBoss server has fully started up, you can start the client application. I ran the NewsClient form within the Eclipse IDE, specifying the j2ee.jar file of my Enterprise Java installation for the JMS classes and including a command line string to send to the MDB. In my case, this string was the message “Hello”.

The end result is that the string “Hello” is printed out in the JBoss console window, as illustrated below:

20:03:45,656 INFO  [Server] JBoss (MX MicroKernel) [4.2.1.GA (build: 
SVNTag=JBoss_4_2_1_GA date=200707131605)] Started in 52s:235ms 
20:04:43,468 INFO  [STDOUT] In the onMessage method(Hello)

There you have it; you’ve now stepped through and run a simple JMS based asynchronous application.

EJB3 versus old MDBs

It is interesting to compare this with what I would have had to define prior to EJB3. With older message driven beans I would have had to implement the javax.ejb.MessageDrivenBean interface as well as the MessageListener interface. It would also have been necessary to define any application server specific files used to define the destination type and destination of the queue.

For example, as well as the default ejb-jar.xml JAR file; with JBoss I would also have had to define a JBoss.xml file. The first file, the JAR file, would have been used to specify that this was a MDB and that it should be bound to a queue. The JBoss specific file would then have been used to bind the MDB to the appropriate queue (the queue/testQueue). The two files, as would be defined for EJB 2.0 are presented below.

The ejb-jar.xml file:

<ejb-jar>
    <enterprise-beans>
        <!-- Some descriptors omitted -->
        <message-driven>
            <ejb-name>DebugMonitor</ejb-name>
            <ejb-class>util.DebugMonitorBean</ejb-class>
            <message-selector>JMSType = ‘DEBUG’</message-selector>
            <transaction-type>Container</transaction-type>
            <acknowledge-mode>Auto-acknowledge</acknowledge-mode>
            <message-driven-destination>
               <destination-type>javax.jms.Queue</destination-type>
            </message-driven-destination>
         </message-driven>
    </enterprise-beans>
    <!-- Some descriptors omitted -->
</ejb-jar>

The JBoss.xml file

<?xml version="1.0"?>
<JBoss>
   <enterprise-beans>
       <!-- Some descriptors omitted -->
       <message-driven>
           <ejb-name>TestMonitor</ejb-name>
           <configuration-name>
              Standard Message Driven Bean
           </configuration-name>
           <destination-jndi-name>queue/queueTest</destination-jndi-name>
           <container-pool-conf>
              <MaximumSize>1</MaximumSize>
              <MinimumSize>1</MinimumSize>
           </container-pool-conf>
       </message-driven>
    </enterprise-beans>
</JBoss>

Conclusion

In this column, we’ve looked at how asynchronous applications can be defined using the JMS API. The example, although very simple, is essentially the same as used by any asynchronous JMS based applications. As you can see the actual implementation is very straight forward and particularly with EJB3, simple to implement. ®