Home | Download | PDF | API | FAQ | Search | Feedback | History

The Message-Driven Bean Class

The code for the SimpleMessageBean class illustrates the requirements of a message-driven bean class:

It must implement the message listener interface for the message type it supports. A bean that supports the JMS API implements the javax.jms.MessageListener interface.
It must be annotated with the MessageDriven annotation if it does not use a deployment descriptor.
The class must be defined as public.
The class cannot be defined as abstract or final.
It must contain a public constructor with no arguments.
It must not define the finalize method.

Unlike session beans and entities, message-driven beans do not have the remote or local interfaces that define client access. Client components do not locate message-driven beans and invoke methods on them. Although message-driven beans do not have business methods, they may contain helper methods that are invoked internally by the onMessage method.

The MessageDriven annotation typically contains a mappedName element that specifies the JNDI name of the destination from which the bean will consume messages. For complex message-driven beans there can also be an activationconfig element containing ActivationConfigProperty annotations used by the bean. See A Java EE Application That Uses the JMS API with a Session Bean (page 1096) for an example.

A message-driven bean can also inject a MessageDrivenContext resource. Commonly you use this resource to call the setRollbackOnly method to handle exceptions for a bean that uses container-managed transactions.

Therefore, the first few lines of the SimpleMessageBean class look like this:

@MessageDriven(mappedName="jms/Queue")
public class SimpleMessageBean implements MessageListener { 
  @Resource
  private MessageDrivenContext mdc;
  ... 

The onMessage Method

When the queue receives a message, the EJB container invokes the message listener method or methods. For a bean that uses JMS, this is the onMessage method of the MessageListener interface.

A message listener method must follow these rules:

The method must be declared as public.
The method must not be declared as final or static.

The onMessage method is called by the bean's container when a message has arrived for the bean to service. This method contains the business logic that handles the processing of the message. It is the message-driven bean's responsibility to parse the message and perform the necessary business logic.

The onMessage method has a single argument: the incoming message.

The signature of the onMessage method must follow these rules:

The return type must be void.
The method must have a single argument of type javax.jms.Message.

In the SimpleMessageBean class, the onMessage method casts the incoming message to a TextMessage and displays the text:

public void onMessage(Message inMessage) {
  TextMessage msg = null;

  try {
    if (inMessage instanceof TextMessage) {
      msg = (TextMessage) inMessage;
      logger.info("MESSAGE BEAN: Message received: " +
        msg.getText());
    } else {
      logger.warning("Message of wrong type: " +
        inMessage.getClass().getName());
    }
  } catch (JMSException e) {
    e.printStackTrace();
    mdc.setRollbackOnly();
  } catch (Throwable te) {
    te.printStackTrace();
  }
} 

All of the material in The Java™ EE 5 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.