Point-to-Point

In the P2P model, a message travels from a single producer to a single consumer. The model is built around the concept of message queues, senders, and receivers (see Figure 13-3). A queue retains the messages sent by the sender until they are consumed, and a sender and a receiver do not have timing dependencies. This means that the sender can produce messages and send them in the queue whenever he likes, and a receiver can consume them whenever he likes. Once the receiver is created, it will get all the messages that were sent to the queue, even those sent before its creation.

Each message is sent to a specific queue, and the receiver extracts the messages from the queue. Queues retain all messages sent until they are consumed or until they expire.

The P2P model is used if there is only one receiver for each message. Note that a queue can have multiple consumers, but once a receiver consumes a message from the queue, it is taken out of the queue, and no other consumer can receive it. In Figure 13-4, you can see one sender producing three messages.

Note that P2P doesn’t guarantee messages are delivered in any particular order (the order is not defined). A provider might pick them in arrival order, or randomly, or some other way.

Publish-Subscribe

In the pub-sub model, a single message is sent by a single producer to potentially several consumers. The model is built around the concept of topics, publishers, and subscribers (Figure 13-5). Consumers are called subscribers because they first need to subscribe to a topic. The provider manages the subscribing/unsubscribing mechanism as it occurs dynamically.

The topic retains messages until they are distributed to all subscribers. Unlike the P2P model, there is a timing dependency between publishers and subscribers; subscribers do not receive messages sent prior to their subscription, and, if the subscriber is inactive for a specified period, it will not receive past messages when it becomes active again. Note that this can be avoided, because the JMS API supports the concept of a durable subscriber, as you’ll later see.

Multiple subscribers can consume the same message. The pub-sub model can be used for broadcast-type applications, in which a single message is delivered to several consumers. In Figure 13-6, the publisher sends three messages that each subscriber will receive (in an undefined order).

Administered Objects

Administered objects are objects that are configured administratively, as opposed to programmatically. The message provider allows these objects to be configured, and makes them available in the JNDI namespace. Like JDBC datasources, administered objects are created only once. The two types of administered objects:

• Connection factories: Used by clients to create a connection to a destination.
• Destinations: Message distribution points that receive, hold, and distribute messages. Destinations can be queues (P2P) or topics (pub-sub).

Clients access these objects through portable interfaces by looking them up in the JNDI namespace or through injection. In GlassFish, there are several ways to create these objects as you’ll later see: by using the administration console, the asadmin command-line, or the REST interface. Since JMS 2.0 you can even use the @JMSConnectionFactoryDefinition and @JMSDestinationDefinition annotations to define programmatically these objects.

Message-Driven Beans

Message-Driven Beans (MDBs) are asynchronous message consumers that are executed inside an EJB container. As you’ve seen in Chapters 7 through 9, the EJB container takes care of several services (transactions, security, concurrency, message acknowledgment, etc.), while the MDB focuses on consuming messages. MDBs are stateless, meaning that the EJB container can have numerous instances, executing concurrently, to process messages coming in from various producers. Even if they look like stateless beans, client applications cannot access MDBs directly; the only way to communicate with an MDB is to send a message to the destination that the MDB is listening to.

In general, MDBs listen to a destination (queue or topic) and, when a message arrives, they consume and process it. They can also delegate business logic to other stateless session beans in a safe, transactional manner. Because they are stateless, MDBs do not maintain state across separate invocations from one message received to the next. MDBs respond to messages received from the container, whereas stateless session beans respond to client requests through an appropriate interface (local, remote, or no-interface).

A Brief History of Messaging

Up until the late 1980s, companies did not have any easy way to link different applications. Developers had to write separate software adapters for systems to translate data from source applications into a format that the destination system could understand (and vice versa). Because of the disparity of servers’ processing capabilities and availabilities, buffers were created to de-couple the processing so that the overall time wouldn’t be prolonged. A lack of homogeneous transport protocols created low-level protocol adapters. Toward the end of the 1980s, middleware began to emerge, which solved these integration issues. The first MOMs were created as separate pieces of software that could sit in the middle of applications and manage the “plumbing” between systems. They were able to manage different platforms, different programming languages, various network protocols, and diverse hardware.

The JMS specification was first published in August 1998. It was created by the major middleware vendors to bring messaging capabilities to Java. JSR 914 went through minor changes (JMS 1.0.1, 1.0.2, and 1.0.2b) to finally reach the 1.1 version in April 2002. JMS 1.1 was integrated into J2EE 1.2 and has been a part of Java EE since. However, JMS and MDBs are not part of the Web Profile specification. This means they are only available on application servers implementing the full Java EE 7 platform.

What’s New in JMS 2.0?

JMS 1.1 didn’t change for more than a decade. Since Java EE 5 the APIs have slowly been modernized to fit the language changes (annotations, generics . . .) except for JMS. It was time for JMS to follow the same path, make use of annotations and simplify its API. In fact, several changes have been made to the JMS API to make it simpler and easier to use:

• Connection, Session and other objects with a close() method now implement the java.jang.AutoCloseable interface to allow them to be used in a Java SE 7 try-with-resources statement
• A new "simplified API" has been added which offers a simpler alternative to the standard and legacy APIs
• A new method getBody has been added to allow an application to extract the body directly from a Message without the need to cast it first to an appropriate subtype
• A set of new unchecked exceptions have been created, all extending from JMSRuntimeException
• New send methods have been added to allow an application to send messages asynchronously

What’s New in EJB 3.2?

MDBs were introduced in EJB 2.0 and were improved with EJB 3.0 and the general Java EE 5 paradigm of “ease of use.” They were not internally modified as they continued to be message consumers, but the introduction of annotations and configuration by exception made them much easier to write. The new EJB 3.2 specification (JSR 345) brought some changes to MDBs by adding more portable configuration (more on that later).

As you’ve seen in Chapter 7, asynchronous calls are now possible within stateless session beans (using the @Asynchronous annotation). In previous versions of Java EE, it was impossible to have asynchronous calls between EJBs. Therefore, the only possible solution was to use JMS and MDBs—expensive, as many resources had to be used (JMS destinations, connections, factories, etc.) just to call a method asynchronously. Today asynchronous calls are possible between session beans without the need for MDBs, allowing them to focus on integrating systems through messaging.

Reference Implementation

Open Message Queue (OpenMQ) is the reference implementation of JMS. It has been open source since 2006 and can be used in stand-alone JMS applications or embedded in an application server. OpenMQ is the default messaging provider for GlassFish and, as this book is being written, is reaching version 5.0. It also adds many nonstandard features such as the Universal Message Service (UMS), wildcard topic destinations, XML message validation, clustering, and more.

Classic API

The JMS classic API provides classes and interfaces for applications that require a messaging system (see Figure 13-7). This API enables asynchronous communication between clients by providing a connection to the provider, and a session where messages can be created and sent or received. These messages can contain text or other different kinds of objects.

Context ctx = new InitialContext();
ConnectionFactory ConnectionFactory = →
                 (ConnectionFactory) ctx.lookup("jms/javaee7/ConnectionFactory");

public interface ConnectionFactory {
 
  Connection createConnection() throws JMSException;
  Connection createConnection(String userName, String password) throws JMSException;
  JMSContext createContext();
  JMSContext createContext(String userName, String password);
  JMSContext createContext(String userName, String password, int sessionMode);
  JMSContext createContext(int sessionMode);
}

Context ctx = new InitialContext();
Destination queue = (Destination) ctx.lookup("jms/javaee7/Queue");

Connection connection = connectionFactory.createConnection();

connection.start();
connection.stop();

connection.close();

Session session = connection.createSession(true, Session.AUTO_ACKNOWLEDGE);

message. set FloatProperty("orderAmount", 1245.5f);
message. get FloatProperty("orderAmount");

textMessage.setText("This is a text message");
textMessage.getText();
bytesMessage.readByte();
objectMessage.getObject();

public class Producer {
 
  public static void main(String[] args) {
 
    try {
      // Gets the JNDI context
      Context jndiContext = new InitialContext();
 
      // Looks up the administered objects
      ConnectionFactory connectionFactory = (ConnectionFactory) →
                        jndiContext.lookup(" jms/javaee7/ConnectionFactory ");
      Destination queue = (Destination) jndiContext.lookup(" jms/javaee7/Queue ");
 
      // Creates the needed artifacts to connect to the queue
      Connection connection = connectionFactory.createConnection();
      Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
      MessageProducer producer = session.createProducer(queue);
 
      // Sends a text message to the queue
      TextMessage message = session.createTextMessage("Text message sent at " + new Date());
      producer.send (message);
 
      connection.close();
 
    } catch ( NamingException | JMSException e ) {
      e.printStackTrace();
    }
  }
}

public class Consumer {
 
  public static void main(String[] args) {
 
    try {
      // Gets the JNDI context
      Context jndiContext = new InitialContext();
 
      // Looks up the administered objects
      ConnectionFactory connectionFactory = (ConnectionFactory) →
                        jndiContext.lookup(" jms/javaee7/ConnectionFactory ");
      Destination queue = (Destination) jndiContext.lookup(" jms/javaee7/Queue ");
 
      // Creates the needed artifacts to connect to the queue
      Connection connection = connectionFactory.createConnection();
      Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
      MessageConsumer consumer = session.createConsumer(queue);
 
      connection.start();
 
      // Loops to receive the messages
      while (true) {
        TextMessage message = (TextMessage) consumer.receive() ;
        System.out.println("Message received: " + message.getText());
      }
 
    } catch ( NamingException | JMSException e ) {
      e.printStackTrace();
    }
  }
}

Simplified API

As you can see, the code in Listing 13-2 and 13-3 is quite verbose and low level. You need several artifacts to be able to produce or consume a message (ConnectionFactory, Connection, Session . . .). On top of that you also need to deal with the JMSException which is a checked exception (JMSException has several sub classes). This API was created with JMS 1.1 in 2002 and was not changed until JMS 2.0.

JMS 2.0 introduces a new simplified API, which consists mainly of three new interfaces (JMSContext, JMSProducer and JMSConsumer). These interfaces rely internally on the ConnectionFactory and other classic APIs but leave the boilerplate code aside. Thanks to the new JMSRuntimeException, which is an unchecked exception, the code to send or receive a message is now much easier to write and read (code examples to follow).

Figure 13-9 shows a simplified class diagram of this new API. Note that the legacy, classic, and simplified APIs are all under the javax.jms package.

The simplified API provides the same messaging functionality as the classic API but requires fewer interfaces and is simpler to use. These main interfaces are:

• JMSContext: active connection to a JMS provider and a single-threaded context for sending and receiving messages
• JMSProducer: object created by a JMSContext that is used for sending messages to a queue or topic
• JMSConsumer: object created by a JMSContext that is used for receiving messages sent to a queue or topic

Producing a Message outside a Container

A message producer (JMSProducer) is an object created by the JMSContext and is used to send messages to a destination. The following steps explain how to create a producer that sends a message to a queue (see Listing 13-4) outside any container (in a pure Java SE environment):

• Obtain a connection factory and a queue using JNDI lookups
• Create a JMSContext object using the connection factory (notice the try-with-resources statement that will automatically close the JMSContext object)
• Create a javax.jms.JMSProducer using the JSMContext object
• Send a text message to the queue using the JMSProducer.send() method

Listing 13-4.  The Producer Class Produces a Message into a Queue

public class Producer {
 
  public static void main(String[] args) {
 
    try {
      // Gets the JNDI context
      Context jndiContext = new InitialContext();
 
      // Looks up the administered objects
      ConnectionFactory connectionFactory = (ConnectionFactory) →
                        jndiContext.lookup(" jms/javaee7/ConnectionFactory ");
      Destination queue = (Destination) jndiContext.lookup(" jms/javaee7/Queue ");
 
      // Sends a text message to the queue
      try ( JMSContext context = connectionFactory.createContext() ) {
        context.createProducer().send (queue, "Text message sent at " + new Date());
      }
 
    } catch ( NamingException e) {
      e.printStackTrace();
    }
  }
}

If you compare the code in Listing 13-4 with the one using the classic API in Listing 13-2, you will notice that the code is less verbose. Exception handling is also neater as the new JMSRuntimeException is used in the new API and is an unchecked exception.

Producing a Message inside a Container

Connection factories and destinations are administered objects that reside in a message provider and have to be declared in the JNDI namespace, which is why you use the JNDI API to look them up. When the client code runs inside a container, dependency injection can be used instead. Java EE 7 has several containers: EJB, servlet, and application client container (ACC). If the code runs in one of these containers, the @Resource annotation can be used to inject a reference to that resource by the container. With Java EE 7, using resources is much easier, as you don’t have the complexity of JNDI or are not required to configure resource references in deployment descriptors. You just rely on the container injection capabilities.

Table 13-7 lists the attributes that belong to the @Resource annotation.

To use the @Resource annotation let’s take the example of the producer in Listing 13-4, change it to a stateless session bean and use injection instead of JNDI lookups. In Listing 13-4, both the connection factory and the queue are looked up using JNDI. In Listing 13-5, the JNDI name is on the @Resource annotation. When the ProducerEJB runs in a container, references of ConnectionFactory and Queue are injected at initialization.

Listing 13-5.  The ProducerEJB Running inside a Container and using @Resource

@Stateless
public class ProducerEJB {
 
  @Resource (lookup = " jms/javaee7/ConnectionFactory ")
  private ConnectionFactory connectionFactory;
  @Resource (lookup = " jms/javaee7/Queue ")
  private Queue queue;
 
  public void sendMessage() {
 
    try ( JMSContext context = connectionFactory.createContext() ) {
      context.createProducer().send (queue, "Text message sent at " + new Date());
    }
  }
}

The code in Listing 13-5 is simpler than the one in Listing 13-4 because it doesn’t deal with JNDI lookups or the JNDI NamingException. The container injects the administered objects once the EJB is initialized.

Producing a Message inside a Container with CDI

When the producer is executed in a container (EJB or Servlet container) with CDI enabled, it can inject the JMSContext. The container will then manage its lifecycle (no need to create or close the JMSContext). This can be done thanks to the @Inject and @JMSConnectionFactory annotations.

The annotation javax.jms.JMSConnectionFactory may be used to specify the JNDI lookup name of the ConnectionFactory used to create the JMSContext (see Listing 13-6). If the JMSConnectionFactory annotation is omitted, then the platform default JMS connection factory will be used.

Listing 13-6.  A Managed Bean Producing a Message using @Inject

public class Producer {
 
  @Inject
  @JMSConnectionFactory (" jms/javaee7/ConnectionFactory ")
  private JMSContext context;
  @Resource (lookup = " jms/javaee7/Queue ")
  private Queue queue;
 
  public void sendMessage() {
    context.createProducer().send (queue, "Text message sent at " + new Date());
  }
}

The code in Listing 13-6 is quite minimalist. The container does all the work of injecting the needed components and managing their lifecycle. As a developer you just need one line of code to send a message.

The annotation javax.jms.JMSPasswordCredential can also be used to specify a user name and password for when the JMSContext is created:

@Inject
@JMSConnectionFactory("jms/connectionFactory")
@JMSPasswordCredential(userName="admin",password="mypassword")
private JMSContext context;

Synchronous Delivery

A synchronous consumer needs to start a JMSContext, loop to wait until a new message arrives, and request the arrived message using one of its receive() methods (see Table 13-6). There are several variations of receive() that allow a client to pull or wait for the next message. The following steps explain how you can create a synchronous consumer that consumes a message from a queue (see Listing 13-7):

• Obtain a connection factory and a topic using JNDI lookups (or injection)
• Create a JMSContext object using the connection factory
• Create a javax.jms.JMSConsumer using the JSMContext object
• Loop and call the receive() method (or in this case receiveBody) on the consumer object. The receive() methods block if the queue is empty and wait for a message to arrive. Here, the infinite loop waits for other messages to arrive

Listing 13-7.  The Consumer Class Consumes Messages in a Synchronous Manner

public class Consumer {
 
  public static void main(String[] args) {
 
    try {
      // Gets the JNDI context
      Context jndiContext = new InitialContext();
 
      // Looks up the administered objects
      ConnectionFactory connectionFactory = (ConnectionFactory) →
                        jndiContext.lookup(" jms/javaee7/ConnectionFactory ");
      Destination queue = (Destination) jndiContext.lookup(" jms/javaee7/Queue ");
 
      // Loops to receive the messages
      try ( JMSContext context = connectionFactory.createContext() ) {
        while (true) {
          String message = context.createConsumer(queue).receiveBody(String.class) ;
        }
      }
 
    } catch ( NamingException e) {
      e.printStackTrace();
    }
  }
}

Again, if you compare the code in Listing 13-7 with the one using the classic API in Listing 13-3, you will see how the new simplified API is easier to use and more expressive.

Asynchronous Delivery

Asynchronous consumption is based on event handling. A client can register an object (including itself) that implements the MessageListener interface. A message listener is an object that acts as an asynchronous event handler for messages. As messages arrive, the provider delivers them by calling the listener’s onMessage() method, which takes one argument of type Message. With this event model, the consumer doesn’t need to loop indefinitely to receive a message. MDBs use this event model (more on that later).

The following steps describe the process used to create an asynchronous message listener (see Listing 13-8):

• The class implements the javax.jms.MessageListener interface, which defines a single method called onMessage()
• Obtain a connection factory and a topic using JNDI lookups (or injection)
• Create a javax.jms.JMSConsumer using the JSMContext object
• Call the setMessageListener() method, passing an instance of a MessageListener interface (in Listing 13-8, the Listener class itself implements the MessageListener interface)
• Implement the onMessage() method and process the received message. Each time a message arrives, the provider will invoke this method, passing the message

Listing 13-8.  The Consumer Is a Message Listener

public class Listener implements MessageListener {
 
  public static void main(String[] args) {
 
    try {
      // Gets the JNDI context
      Context jndiContext = new InitialContext();
 
      // Looks up the administered objects
      ConnectionFactory connectionFactory = (ConnectionFactory) →
                        jndiContext.lookup("jms/javaee7/ConnectionFactory");
      Destination queue = (Destination) jndiContext.lookup("jms/javaee7/Queue");
 
      try (JMSContext context = connectionFactory.createContext()) {
        context.createConsumer(queue). setMessageListener(new Listener()) ;
      }
 
    } catch (NamingException e) {
      e.printStackTrace();
    }
  }
 
  public void onMessage (Message message) {
    System.out.println("Async Message received: " + message.getBody(String.class) );
  }
}

Filtering messages

Some messaging applications need to filter the messages they receive. When a message is broadcast to many clients, it becomes useful to set criteria so that it is only consumed by certain receivers. This eliminates both the time and bandwidth the provider would waste transporting messages to clients that don’t need them.

You’ve seen that messages are composed of three parts: header, properties, and body (see Figure 13-8). The header contains a fixed number of fields (the message metadata), and the properties are a set of custom name-value pairs that the application can use to set any values. Selection can be done on those two areas. Producers set one or several property values or header fields, and the consumer specifies message selection criteria using selector expressions. Only messages that match the selector are delivered. Message selectors assign the work of filtering messages to the JMS provider, rather than to the application.

A message selector is a string that contains an expression. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax and looks like this:

context.createConsumer(queue, " JMSPriority < 6 ").receive();
context.createConsumer(queue, " JMSPriority < 6 AND orderAmount < 200 ").receive();
context.createConsumer(queue, " orderAmount BETWEEN 1000 AND 2000 ").receive();

In the preceding code, a consumer is created with the JMSContext.createConsumer() method, passing a selector string. This string can use header fields (JMSPriority < 6) or custom properties (orderAmount < 200). The producer sets these properties into the message as follows:

context.createTextMessage(). setIntProperty("orderAmount", 1530) ;
context.createTextMessage(). setJMSPriority(5) ;

Selector expression can use logical operators (NOT, AND, OR), comparison operators (=, >, >=, <, <=, <>), arithmetic operators (+, -, *, /), expressions ([NOT] BETWEEN, [NOT] IN, [NOT] LIKE, IS [NOT] NULL), and so on.

Setting Message Time-to-Live

Under heavy load, a time-to-live can be set on messages to ensure that the provider will remove them from the destination when they become obsolete, by either using the JMSProducer API or setting the JMSExpiration header field. The JMSProducer has a setTimeToLive() method that takes a number of milliseconds:

context.createProducer(). setTimeToLive (1000).send(queue, message);

Specifying Message Persistence

JMS supports two modes of message delivery: persistent and nonpersistent. Persistent delivery ensures that a message is delivered only once to a consumer, whereas nonpersistent delivery requires a message be delivered once at most. Persistent delivery (which is the default) is more reliable, but at a performance cost, as it prevents losing a message if a provider failure occurs. The delivery mode can be specified by using the setDeliveryMode() method of the JMSProducer interface:

context.createProducer(). setDeliveryMode (DeliveryMode.NON_PERSISTENT).send(queue, message);

Controlling Acknowledgment

So far, the scenarios we’ve explored have assumed that a message is sent and received without any acknowledgment. But sometimes, you will want a receiver to acknowledge the message has been received (see Figure 13-11). An acknowledgment phase can be initiated either by the JMS provider or by the client, depending on the acknowledgment mode.

In transactional sessions, acknowledgment happens automatically when a transaction is committed. If a transaction is rolled back, all consumed messages are redelivered. But in nontransactional sessions, an acknowledgment mode must be specified:

• AUTO_ACKNOWLEDGE: The session automatically acknowledges the receipt of a message
• CLIENT_ACKNOWLEDGE: A client acknowledges a message by explicitly calling the Message.acknowledge() method
• DUPS_OK_ACKNOWLEDGE: This option instructs the session to lazily acknowledge the delivery of messages. This is likely to result in the delivery of some duplicate messages if the JMS provider fails, so it should be used only by consumers that can tolerate duplicate messages. If the message is redelivered, the provider sets the value of the JMSRedelivered header field to true

The following code uses the @JMSSessionMode annotation to set the acknowledgment mode to the JMSContext on the producer. The consumer explicitly acknowledges the message by calling the acknowledge() method:

// Producer
@Inject
@JMSConnectionFactory("jms/connectionFactory")
@JMSSessionMode(JMSContext.AUTO_ACKNOWLEDGE)
private JMSContext context;
...
context.createProducer().send(queue, message);
 
// Consumer
message. acknowledge ();

Creating Durable Consumers

The disadvantage of using the pub-sub model is that a message consumer must be running when the messages are sent to the topic; otherwise, it will not receive them. By using durable consumers, the JMS API provides a way to keep messages in the topic until all subscribed consumers receive them. With durable subscription, the consumer can be offline for some time, but, when it reconnects, it receives the messages that arrived during its disconnection. To achieve this, the client creates a durable consumer using the JMSContext:

context. createDurableConsumer (topic, "javaee7DurableSubscription").receive();

At this point, the client program starts the connection and receives messages. The name javaee7DurableSubscription is used as an identifier of the durable subscription. Each durable consumer must have a unique ID, resulting in the declaration of a unique connection factory for each potential, durable consumer.

Setting Priorities

You can use message priority levels to instruct the JMS provider to deliver urgent messages first. JMS defines ten priority values, with 0 as the lowest and 9 as the highest. You can specify the priority value by using the setPriority() method of the JMSProducer:

context.createProducer(). setPriority (2).send(queue, message);

Most of these methods return the JMSProducer to allow method calls to be chained together, allowing a fluid programming style. For example:

context.createProducer().setPriority(2)
                        .setTimeToLive(1000)
                        .setDeliveryMode(DeliveryMode.NON_PERSISTENT)
                        .send(queue, message);

Anatomy of an MDB

MDBs are different from session beans, as they do not implement a local or remote business interface but instead implement the javax.jms.MessageListener interface. Clients cannot invoke methods directly on MDBs; however, like session beans, MDBs have a rich programming model that includes a life cycle, callback annotations, interceptors, injection, and transactions. Taking advantage of this model provides applications with a high level of functionality.

It is important to be aware that MDBs are not part of the EJB Lite model, meaning that they cannot be deployed in a simple web profile application server, but still need the full Java EE stack.

The requirements to develop an MDB class are as follows:

• The class must be annotated with @javax.ejb.MessageDriven or its XML equivalent in a deployment descriptor
• The class must implement, directly or indirectly, the MessageListener interface
• The class must be defined as public, and must not be final or abstract
• The class must have a public no-arg constructor that the container will use to create instances of the MDB
• The class must not define the finalize() method.

The MDB class is allowed to implement other methods, invoke other resources, and so on. MDBs are deployed in a container and can be optionally packaged with an ejb-jar.xml file. Following the “ease of use” model of Java EE 7, an MDB can be simply an annotated POJO, eliminating most of the configuration. However, if you still need to customize the JMS configuration, you can use the elements of the @MessageDriven and @ActivationConfigProperty annotations (or XML equivalent).

@Target(TYPE) @Retention(RUNTIME)
public @interface MessageDriven {
  String name() default "";
  Class messageListenerInterface default Object.class;
  ActivationConfigProperty[] activationConfig() default {};
  String mappedName();
  String description();
}

@Target({}) @Retention(RUNTIME)
public @interface ActivationConfigProperty {
  String propertyName();
  String propertyValue();
}

@MessageDriven(mappedName = "jms/javaee7/Topic", activationConfig = {
  @ActivationConfigProperty (propertyName = " acknowledgeMode ", →
                            propertyValue = "Auto-acknowledge"),
  @ActivationConfigProperty (propertyName = " messageSelector ", →
                            propertyValue = "orderAmount < 3000")
})
public class BillingMDB implements MessageListener {
 
  public void onMessage(Message message) {
    System.out.println("Message received: " + message.getBody(String.class));
  }
}

@PersistenceContext
private EntityManager em;
@Inject
private InvoiceBean invoice;
@Resource (lookup = "jms/javaee7/ConnectionFactory")
private ConnectionFactory connectionFactory;

@Resource private MessageDrivenContext context;

MDB as a Consumer

As explained in the “Writing Message Consumers” section earlier in this chapter, consumers can receive a message either synchronously, by looping and waiting for a message to arrive, or asynchronously, by implementing the MessageListener interface. By nature, MDBs are designed to function as asynchronous message consumers. MDBs implement a message listener interface, which is triggered by the container when a message arrives.

Can an MDB be a synchronous consumer? Yes, but this is not recommended. Synchronous message consumers block and tie up server resources (the EJBs will be stuck looping without performing any work, and the container will not be able to free them). MDBs, like stateless session beans, live in a pool of a certain size. When the container needs an instance, it takes one out of the pool and uses it. If each instance goes into an infinite loop, the pool will eventually empty, and all the available instances will be busy looping. The EJB container can also start generating more MDB instances, growing the pool and eating up more and more memory. For this reason, session beans and MDBs should not be used as synchronous message consumers. Table 13-10 shows you the different receiving modes for MDBs and session beans.

MDB as a Producer

MDBs are capable of becoming message producers, something that often occurs when they are involved in a workflow, as they receive a message from one destination, process it, and send it to another destination. To add this capability, the JMS API must be used.

A destination and a connection factory can be injected by using the @Resource and @JMSConnectionFactory annotations or via JNDI lookup, and then methods on the javax.jms.JMSContext object can be invoked to create and send a message. The code of the BillingMDB (see Listing 13-13) listens to a topic (jms/javaee7/Topic), receives messages (onMessage() method), and sends a new message to a queue (jms/javaee7/Queue).

Listing 13-13.  A MDB Consuming and Producing Messages

@MessageDriven(mappedName = " jms/javaee7/Topic ", activationConfig = { →
        @ActivationConfigProperty(propertyName  = "acknowledgeMode", →
                                  propertyValue = "Auto-acknowledge"), →
        @ActivationConfigProperty(propertyName  = "messageSelector", →
                                  propertyValue = "orderAmount BETWEEN 3 AND 7")
})
public class BillingMDB implements MessageListener {
 
  @Inject
  @JMSConnectionFactory("jms/javaee7/ConnectionFactory")
  @JMSSessionMode(JMSContext.AUTO_ACKNOWLEDGE)
  private JMSContext context;
  @Resource(lookup = " jms/javaee7/Queue ")
  private Destination printingQueue ;
 
  public void onMessage(Message message) {
    System.out.println("Message received: " + message.getBody(String.class));
    sendPrintingMessage();
  }
 
  private void sendPrintingMessage () throws JMSException {
    context.createProducer().send (printingQueue, "Message has been received and resent");
  }
}

This MDB uses most of the concepts introduced thus far. First, it uses the @MessageDriven annotation to define the JNDI name of the topic it is listening to (mappedName = "jms/javaee7/Topic"). In this same annotation, it defines a set of properties, such as the acknowledge mode and a message selector using an array of @ActivationConfigProperty annotations, and it implements MessageListener and its onMessage() method.

This MDB also needs to produce a message. Therefore, it is injected with the two administered objects required: a connection factory (using JMSContext) and a destination (the queue named jms/javaee7/Queue). Finally, the business method that sends messages (the sendPrintingMessage() method) looks like what you’ve seen earlier: a JMSProducer is created and used to create and send a text message. For better readability, exception handling has been omitted in the entire class.

Transactions

MDBs are EJBs (see Chapter 7 and 8 for more information). MDBs can use BMTs or container-managed transactions (CMTs); they can explicitly roll back a transaction by using the MessageDrivenContext.setRollbackOnly() method, and so on. However, there are some specifics regarding MDBs that are worth explaining.

When we talk about transactions, we always think of relational databases. However, other resources are also transactional, such as messaging systems. If two or more operations have to succeed or fail together, they form a transaction (see Chapter 9). With messaging, if two or more messages are sent, they have to succeed (commit) or fail (roll back) together. How does this work in practice? The answer is that messages are not released to consumers until the transaction commits. The container will start a transaction before the onMessage() method is invoked and will commit the transaction when the method returns (unless the transaction was marked for rollback with setRollbackOnly()).

Even though MDBs are transactional, they cannot execute in the client’s transaction context, as they don’t have a client. Nobody explicitly invokes methods on MDBs, they just listen to a destination and consume messages. There is no context passed from a client to an MDB, and similarly the client transaction context cannot be passed to the onMessage() method. Table 13-11 compares CMTs with session beans and MDBs.

In CMTs, MDBs can use the @javax.ejb.TransactionAttribute annotation on business methods with the two following attributes:

• REQUIRED (the default): If the MDB invokes other enterprise beans, the container passes the transaction context with the invocation. The container attempts to commit the transaction when the message listener method has completed
• NOT_SUPPORTED: If the MDB invokes other enterprise beans, the container passes no transaction context with the invocation

Handling Exceptions

In the snippets of code in this chapter, exception handling has been omitted, as the JMS API can be verbose in dealing with exceptions. The classic API defines 12 different exceptions, all inheriting from javax.jms.JMSException. The simplified API defines 10 runtime exceptions all inheriting from javax.jms.JMSRuntimeException.

It is important to note that JMSException is a checked exception (see the discussion on application exception in the “Exception Handling” section in Chapter 9) and JMSRuntimeException is unchecked. The EJB specification outlines two types of exceptions:

• Application exceptions: Checked exceptions that extend Exception and do not cause the container to roll back
• System exceptions: Unchecked exceptions that extend RuntimeException and cause the container to roll back

Throwing a JMSRuntimeException will cause the container to roll back, but throwing a JMSException will not. If a rollback is needed, the setRollBackOnly() must be explicitly called or a system exception (such as EJBException) rethrown:

public void onMessage(Message message) {
  try {
    System.out.println("Message received: " + message.getBody(String.class));
  } catch (JMSException e) {
    context.setRollBackOnly();
  }
}

Writing the OrderDTO

The object that will be sent in the JMS message is a POJO that needs to implement the Serializable interface. The OrderDTO class, shown in Listing 13-14, gives some information about the order, including its total amount; it is the object that will be set into a JMS ObjectMessage and sent from the OrderProducer to the topic and then consumed by the OrderConsumer and ExpensiveOrderMDB.

Listing 13-14.  The OrderDTO Is Passed in a JMS ObjectMessage

public class OrderDTO implements Serializable {
 
  private Long orderId;
  private Date creationDate;
  private String customerName;
  private Float totalAmount ;
 
// Constructors, getters, setters
}

Writing the OrderProducer

The OrderProducer, shown in Listing 13-15, is a stand-alone client that uses the JMS simplified API to send an ObjectMessage to the jms/javaee7/Topic topic. It looks up for the necessary connection factory and destination, and in the main() method creates an instance of an OrderDTO class. Note that the totalAmount of the order is an argument passed to the class (args[0]). The JSMProducer sets the orderAmount property in the message for selection later, and the order is then sent to the topic.

Listing 13-15.  The OrderProducer Sends an OrderDTO

public class OrderProducer {
 
  public static void main(String[] args) throws NamingException {
 
    // Creates an orderDto with a total amount parameter
    Float totalAmount = Float.valueOf(args[0]);
    OrderDTO order = new OrderDTO(1234l, new Date(), "Betty Moreau", totalAmount );
 
    // Gets the JNDI context
    Context jndiContext = new InitialContext();
 
    // Looks up the administered objects
    ConnectionFactory connectionFactory = (ConnectionFactory) →
                      jndiContext.lookup(" jms/javaee7/ConnectionFactory ");
    Destination topic = (Destination) jndiContext.lookup(" jms/javaee7/Topic ");
 
    try (JMSContext jmsContext = connectionFactory.createContext()) {
     // Sends an object message to the topic
     jmsContext.createProducer(). setProperty("orderAmount", totalAmount) . send(topic, order) ;
    }
  }
}

Writing the OrderConsumer

The OrderConsumer, shown in Listing 13-16, is also a stand-alone JMS client listening to the jms/javaee7/Topic topic and using the JMSConsumer API to receive all the OrderDTO (there are no selectors).

Listing 13-16.  The OrderConsumer Consumes all the OrderDTO Messages

public class OrderConsumer {
 
  public static void main(String[] args) throws NamingException {
 
    // Gets the JNDI context
    Context jndiContext = new InitialContext();
 
    // Looks up the administered objects
    ConnectionFactory connectionFactory = (ConnectionFactory) →
                      jndiContext.lookup(" jms/javaee7/ConnectionFactory ");
    Destination topic = (Destination) jndiContext.lookup(" jms/javaee7/Topic ");
 
    // Loops to receive the messages
    try (JMSContext jmsContext = connectionFactory.createContext()) {
      while (true) {
        OrderDTO order = jmsContext.createConsumer(topic).receiveBody(OrderDTO.class) ;
        System.out.println("Order received: " + order);
      }
    }
  }
}

Writing the ExpensiveOrderMDB

The ExpensiveOrderMDB class (see Listing 13-17) is an MDB annotated with @MessageDriven that listens to the jms/javaee7/Topic destination. This MDB is only interested in orders greater than $1,000, using a message selector (orderAmount > 1000). At message arrival, the onMessage() method consumes it, casts it to an OderDTO (getBody(OrderDTO.class)), and gets the body of the message. For this example, only the message is displayed (System.out.println), but other processing could have also been done (by delegating to a stateless session bean for example).

Listing 13-17.  The ExpensiveOrderMDB only Consumes Orders with an Amount Greater than $1000

@MessageDriven(mappedName = " jms/javaee7/Topic ", activationConfig = { →
        @ActivationConfigProperty(propertyName  = "acknowledgeMode", →
                                  propertyValue = "Auto-acknowledge"), →
        @ActivationConfigProperty(propertyName  = " messageSelector ", →
                                  propertyValue = " orderAmount > 1000 ")
})
public class ExpensiveOrderMDB implements MessageListener {
 
  public void onMessage (Message message) {
    try {
      OrderDTO order = message.getBody(OrderDTO.class) ;
      System.out.println("Expensive order received: " + order.toString());
    } catch (JMSException e) {
      e.printStackTrace();
    }
  }
}

Compiling and Packaging with Maven

The ExpensiveOrderMDB and the OrderDTO should be packaged together in a jar file so they can be deployed to GlassFish. Because MDBs use annotations from the EJB package (@MessageDriven) and the JMS API (ConnectionFactory, Destination, etc.) the pom.xml shown in Listing 13-18 uses the glassfish-embedded-all dependency (which contains all the Java EE 7 APIs). This dependency has the scope provided because GlassFish, as an EJB container and a JMS provider, provides these APIs at runtime. Maven should be informed that you are using Java SE 7 by configuring the maven-compiler-plugin.

Listing 13-18.  The pom.xml to Build and Package the MDB

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns=" http://maven.apache.org/POM/4.0.0 " →
         xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance " →
         xsi:schemaLocation=" http://maven.apache.org/POM/4.0.0 →
         http://maven.apache.org/xsd/maven-4.0.0.xsd ">
  <modelVersion>4.0.0</modelVersion>
 
  <parent>
    <artifactId>chapter13</artifactId>
    <groupId>org.agoncal.book.javaee7</groupId>
    <version>1.0</version>
  </parent>
 
  <groupId>org.agoncal.book.javaee7.chapter13</groupId>
  <artifactId>chapter13-mdb</artifactId>
  <version>1.0</version>
 
  <dependencies>
    <dependency>
      <groupId>org.glassfish.main.extras</groupId>
      <artifactId> glassfish-embedded-all </artifactId>
      <version>4.0</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
 
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.5.1</version>
        <configuration>
          <source> 1.7 </source>
          <target>1.7</target>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

To compile and package the classes, open a command-line interpreter in the directory that contains the pom.xml file, and enter the following Maven command:

$ mvn package

Go to the target directory, where you should see the file chapter13-MDB-1.0.jar. If you open it, you will see that it contains the class file for the ExpensiveOrderMDB and OrderDTO.

Creating the Administered Objects

The administered objects required to send and receive messages need to be created in the JMS provider. Each one has a JNDI name, allowing clients to obtain a reference of the object through a JNDI lookup:

• The connection factory is called jms/javaee7/ConnectionFactory
• The topic is called jms/javaee7/Topic

As these objects are created administratively, GlassFish needs to be up and running. Once you’ve made sure that the asadmin command-line is in your path, execute the following command in the console:

$ asadmin create-jms-resource --restype javax.jms.ConnectionFactory →
                                        jms/javaee7/ConnectionFactory
$ asadmin create-jms-resource --restype javax. jms.Topic jms/javaee7/Topic

GlassFish’s web console can be used to set up the connection factory and the queue. Note, however, that in my experience the easiest and quickest way to administer GlassFish is through the asadmin script. Use another command to list all the JMS resources and ensure that the administered objects are created successfully:

$ asadmin list-jms-resources
jms/javaee7/Topic
jms/javaee7/ConnectionFactory

Since JMS 2.0, there is a programmatic way to declare administered objects. The idea is to annotate any managed bean (managed bean, EJB, MDB . . .) with @JMSConnectionFactoryDefinition and @JMSDestinationDefinition, deploy the bean, and the container will make sure to create the factory and the destination. This mechanism is similar to the one you saw in Chapter 8 Listing 8-15 with the @DataSourceDefinition annotation. Listing 13-19 shows the ExpensiveOrderMDB with two definition annotations.

Listing 13-19.  The ExpensiveOrderMDB Defining Administered Objects Programmatically

@JMSConnectionFactoryDefinition (name = "jms/javaee7/ConnectionFactory",
                           className = "javax.jms.ConnectionFactory")
@JMSDestinationDefinition (name = "jms/javaee7/Topic",
                     className = "javax.jms.Topic")
public class ExpensiveOrderMDB implements MessageListener {...}

Deploying the MDB on GlassFish

Once the MDB is packaged in the jar, it needs to be deployed into GlassFish. This can be done in several ways, including via the web administration console. However, the asadmin command-line does the job simply: open a command-line, go to the target directory where the chapter13-MDB-1.0.jar file is, make sure GlassFish is still running, and enter the following command:

$ asadmin deploy chapter13-MDB-1.0.jar

If the deployment is successful, the following command should return the name of the deployed jar and its type (ejb in the example):

$ asadmin list-components
chapter13-MDB-1.0 <ejb>

Running the Example

The MDB is deployed on GlassFish and is listening to the jms/javaee7/Topic destination, waiting for a message to arrive. It’s time to run the OrderConsumer and OrderProducer clients. These classes are stand-alone applications with a main method that has to be executed outside of GlassFish, in a pure Java SE environment. Enter the following command to run the OrderConsumer:

$ java –cp target/classes OrderConsumer

The consumer loops indefinitely and waits for an order to arrive. Now enter the following command to send a message with an order of $2,000:

$ java –cp target/classes OrderProducer 2000

Because the amount is greater than $1,000 (the amount defined in the selector message), the OrderExpensiveMDB and OrderConsumer should both receive the message. Check the GlassFish logs to confirm this. If you pass a parameter lower than $1,000, the MDB will not receive the message, just the OrderConsumer:

$ java –cp target/classes OrderProducer 500