Developing message-driven beans

You 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.

Before you begin

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

About this task

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, you 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>

Note: In WebSphere® Application Server version 9, the destinationLookup property can also be used instead of the destination activation configuration property. Both the activation configuration properties serve the same purpose of setting the destination JNDI name for MDBs. However, when both the activation properties are defined in the configuration, the destinationLookup property takes precedence over the destination property.

Procedure

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.

You 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, you 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. You can 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 that is defined in a different Java archive (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, you can package a message-driven bean in a JAR file, or in a web application archive (WAR) file.

Results

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