Develop message-driven beans

We can develop a bean implementation class for a message-driven bean as introduced by the Enterprise JavaBeans specification. A message-driven bean (MDB) is a message consumer that implements business logic and runs on the server.

Determine the messaging model we want for the application regarding use of topics, queues, producers and consumers, publish or subscribe, and so on. We can refer to the message-driven bean component contract described in the Enterprise JavaBeans™ specification.

A message-driven bean (MDB) is a consumer of messages from a Java Message Service (JMS) provider. An MDB is invoked on arrival of a message at the destination or endpoint that the MDB services. MDB instances are anonymous, and therefore, all instances are equivalent when not actively servicing a client message. The container controls the life cycle of bean instances, which hold no state that is visible to a client.

The following example is a basic message-driven bean:

@MessageDriven(activationConfig={
                @ActivationConfigProperty(propertyName="destination", propertyValue="myDestination"), @ActivationConfigProperty(propertyName="destinationType", propertyValue="javax.jms.Queue")
})
public class MsgBean implements javax.jms.MessageListener {
   public void onMessage(javax.jms.Message msg) {
       String receivedMsg = ((TextMessage) msg).getText();
      System.out.println("Received message: " + receivedMsg);
    }
 }

As with other enterprise bean types, we can also declare metadata for message-driven beans in the deployment descriptor rather than using annotations, for example:

<?xml version="1.0" encoding="UTF-8"?>
 <ejb-jar id="EJBJar_1060639024453" version="3.0"
      xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
      metadata-complete="false">
  <enterprise-beans>
     <message-driven>
       <ejb-name>MsgBean</ejb-name>
      <ejb-class>com.acme.ejb.MsgBean</ejb-class>
      <activation-config>
         <activation-config-property>
            <activation-config-property-name>destination</activation-config-property-name>
            <activation-config-property-value>myDestination</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>
</ejb-jar>

• Code the business logic of the message-driven bean, which must implement the appropriate message listener interface defined by the messaging type; for example, javax.jms.MessageListener. The business logic is invoked when the message listener method of the MDB is called to service a message; for example, MessageListener.onMessage(). If the MDB implements more than one interface, denote the message listener interface by coding the messageListenerInterface attribute of the MessageDriven annotation, or by coding the <messaging-type> element of the message-driven deployment descriptor element. You do not have to specify which is the message listener interface, as long as there is only one interface other than java.io.Serializable, java.io.Externalizable, or any of the javax.ejb package interfaces.

• We can optionally define message destination references on any type of enterprise bean. A message destination reference is a logical name by which an enterprise bean can refer to a message destination. The Resource annotation is used to inject a message destination reference, for example:
  @Resource (name="jms/Outlet", type=javax.jms.Queue) Queue salesOutlet;

  Alternatively, we can use the <message-destination-ref> element in the deployment descriptor to specify the message destination reference; for example:

  <message-destination-ref>
     <message-destination-ref-name>jms/Outlet</message-destination-ref-name>
     <message-destination-type>javax.jms.Queue</message-destination-type>
     <injection-target>
       <injection-target-class>com.acme.ejb.MsgBean</injection-target-class>
       <injection-target-name>salesOutlet</injection-target-name>
    </injection-target>
  </message-destination-ref>

  The message-destination-ref element is similar to the resource-env-ref element, but also has subelements, message-destination-usage with possible values Produces, Consumes or ProducesConsumes, and message-destination-link. Use the message-destination-link element to tie two or more message-destination-ref references in the deployment descriptor together, which allows the deployer to bind the destination for several enterprise beans all at once, to the same destination. The message-destination-link value must match the message-destination-name value in the message-destination element; for example:

  <ejb-jar>
     <enterprise-beans>
       <session>
        <ejb-name>OutletBean</display-name>
        ...
        <message-destination-ref>
          <message-destination-ref-name>jms/target</message-destination-ref-name>
          <message-destination-type>javax.jms.Queue</message-destination-type>
          <message-destination-usage>Produces</message-destination-usage>
          <message-destination-link>destination</message-destination-link>
        </message-destination-ref>
        ...
      </session>
       <session>
        <ejb-name>InletBean</display-name>
        ...
        <message-destination-ref>
          <message-destination-ref-name>jms/source</message-destination-ref-name>
          <message-destination-type>javax.jms.Queue</message-destination-type>
          <message-destination-usage>Consumes</message-destination-usage>
          <message-destination-link>destination</message-destination-link>
        </message-destination-ref>
        ...
      </session>
   
      <message-driven>
        <ejb-name>InletBean</display-name>
        ...
         <ejb-name>MsgBean</ejb-name>
        <ejb-class>com.acme.MsgBean</ejb-class>
        <messaging-type>javax.jms.MessageListener</messaging-type>
        <message-destination-type>javax.jms.Queue</message-destination-type>
        <message-destination-link>destination</message-destination-link>
         ...
      </message-driven>
     </enterprise-beans>
        ...
    <assembly-descriptor>
      ...
      <message-destination>
        <message-destination-name>destination</message-destination-name>
      </message-destination>
      ...
    </assembly-descriptor>
   </ejb-jar>

  The message-destination-link element can refer to a destination defined in a different JAR file within the same application, as with an ejb-link element. For example, to link to the destination, ProduceQueue, defined in the grocery.jar file, enter the following line in the deployment descriptor:

  <message-destination-link>grocery.jar#ProduceQueue</message-destination-link>

• As with any enterprise bean, we can package a message-driven bean in a JAR file, or in a WAR file.

Results

You developed a simple message-driven bean, along with some deployment and packaging options.

What to do next

Read related information about designing an enterprise application that uses message-driven beans.

Related tasks

Design an enterprise application to use message-driven beans

EJB 3.0 and EJB 3.1 application bindings overview

Preparing for application installation binding settings