As an EJB type, MDBs reside within the context of an EJB container and, similar to standard JMS message listeners, cannot interact directly with their JMS clients because they do not have a home or remote interface. For this reason, MDBs are considered anonymous because they have no client-visible identity.

Similar to stateless session beans, MDB instances also have no conversational state, which implies that all bean instances are equivalent when they are not involved in servicing a client message. This characteristic permits the EJB container to pool and create multiple instances of the same MDB based on the throughput of messages in the MDB’s JMS destination, hence enabling the concurrent consumption of messages, as shown in Figure 22.2.

Figure 22.2. The concurrent consumption of messages by an MDB in an EJB container.

A client accesses an MDB through JMS by sending messages to a JMS destination (queue or topic) for which the MDB class is assigned as a message listener. MDBs are associated with a specific JMS destination via their deployment descriptors.

When a message arrives in a JMS destination targeted for an MDB, the JMS provider and the EJB container automatically collaborate to deliver the message to the MDB. One instance from the MDB bean pool is selected to handle the message. Similar to a standard JMS message listener, an MDB contains an onMessage() method that is called automatically when a message arrives. However, different messages can be processed concurrently by different MDB instances, which provides performance and scalability benefits.

After an MDB consumes a message, it can process the message or pass the message to another EJB type for processing, as shown in Figure 22.3.

Figure 22.3. An example of processing an MDB.

The primary benefit of using MDBs for asynchronous consumption of messages is derived from MDBs existing completely in the context of an EJB container and, therefore, being able to leverage EJB services the container provides. For example, the WebLogic EJB container provides a standard set of services, such as concurrency control, persistence, security, transaction management, locking, clustering, and complete JMS infrastructure support, which would otherwise need to be configured in code and via the Administration Console for a standard JMS Listener.

Although an MDB can serve only one JMS destination, its stateless nature allows the WebLogic EJB container to create multiple MDB instances as necessary to process large volumes of messages concurrently, hence providing a scalable mechanism for concurrent consumption/processing of messages. In contrast, you would have to configure the standard JMS Listener class to be a member of a serverwide session pool via the Administration Console.

Another benefit of using MDBs is that they inherit the write-once, deploy-anywhere quality of EJBs, as the associated JMS destination and server resource attributes are assigned only at deployment time. This provides better portability of MDBs between different implementations of the EJB container.

MDBs are suitable for use over standard JMS Consumers in the following situations:

One constraint of using MDBs compared to standard JMS Listeners is that you can associate an MDB only to a single JMS destination (queue or topic). If you require a single JMS Consumer to process messages from multiple JMS destinations, you can use a standard JMS Consumer or deploy MDB classes for each JMS destination.

Even though an MDB is a bean type that can mimic the behavior of stateless session bean instances at times (pooling) and, like other EJBs, live within the boundaries of an EJB container, the following differences between MDBs and the other bean types (session and entity) further clarify their unique message consumption characteristics:

Table 22.1 summarizes the differences between message-driven, session, and entity beans.

The container calls the ejbCreate() method for bean instantiation into the WebLogic EJB container’s free pool, which is an area of memory WebLogic Server reserves to maintain a set of method-ready stateless bean instances (session and MDBs). This method is a convenient place to implement logic for allocating the necessary resources to process messages. For example, if an MDB sends messages to other destinations, you can place code in the ejbCreate() method to look up JMS API connection factories and destinations and create the JMS API connection.

The MDB class must define one ejbCreate() method, and its signature must abide by the following rules:

The setMessageDrivenContext() method is called before ejbCreate() and invoked by the EJB container to associate an MDB instance with its context, which is maintained by the container. The EJB container passes the javax.ejb. MessageDrivenContext object into this method, which is usually established as a member variable, thus allowing the MDB instance to access its context information in subsequent methods.

For example, the transactional context that the EJB container sets for an MDB can be accessed via the following methods from the MessageDrivenContext interface:

Even though the getCallerPrincipal(), isCallerInRole(), getEJBHome(), and getEJBLocalHome() methods are inherited as part of the MessageDrivenContext interface, they should not be called by MDBs for these reasons:

The MDB class must define one setMessageDrivenContext() method. This method’s signature must abide by the following rules:

The EJB container calls the onMessage() method when it determines that an MDB instance should receive a message from a JMS queue or topic. The onMessage() method accepts an object of type javax.jms.Message object as an input argument. Within this method, the bean provider implements the business logic to process the received message, which is cast to one of the five JMS message types. After a message has been processed, the bean instance is available to receive other requests.

The MDB class must define one onMessage() method; its signature must abide by the following rules:

The EJB container calls this method to remove the bean from WebLogic Server’s free pool. You can also use this method to implement the code for releasing any resources allocated in the bean’s ejbCreate() or setMessageDrivenContext() methods, such as JMS or JDBC connections.

The MDB class must define one ejbRemove() method. This method’s signature must abide by the following rules:

MDBs do not propagate exceptions to the client, and for this reason they should not throw an application exception or a RemoteException. If any of the bean’s methods throws such an exception, WebLogic Server immediately removes the EJB instance without calling ejbRemove(). From a client’s perspective, the MDB still exists, as future messages are forwarded to a new bean instance that WebLogic Server allocates from the free pool. However, from a WebLogic Server perspective, these types of exceptions are undesirable because any resources the MDB allocated would not be released appropriately.

To counter these exceptions, the bean provider must handle all exceptions within the MDB’s methods, for example:

In addition to the preceding exception-handling techniques, a bean developer should implement additional internal methods to perform resource cleanup routines outside the ejbRemove() method—for example, to clean up resources allocated through the ejbCreate() and setMessageDrivenContext() methods.

Because MDBs have only four methods where you can implement code, they are quite easy to develop. The code for myMessageDrivenBean is shown in Listing 22.2.

package MDBExample;

import javax.ejb.EJBException;
import javax.ejb.CreateException;
import javax.ejb.MessageDrivenBean;
import javax.ejb.MessageDrivenContext;

import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageListener;
import javax.jms.TextMessage;

public class myMessageDrivenBean
       implements MessageDrivenBean, MessageListener {

  private MessageDrivenContext mdbContext;

// A simple logging mechanism
  private void log(String s) {
    if (true) System.out.println(s);
  }

  // container callback methods

  public void ejbRemove() throws EJBException {
    log("ejbRemove called");
  }

  public void setMessageDrivenContext(MessageDrivenContext ctx) {
    mdbContext = ctx;
    log("context set");
  }

  public void ejbCreate () throws CreateException {
    log("ejbCreate called");
  }

  // The implementation of the onMessage method

  public void onMessage(Message msg) {
    TextMessage tm = (TextMessage) msg;
    try {
      log("onMessage called");
      String text = tm.getText();
      System.out.println("[myMessageDrivenBean] Received message: " + text );
    }
    catch(JMSException ex) {
      System.out.println("Caught JMSException: " + ex );
    }
  }
}

After you have created this code using a Java IDE or text editor, follow these steps:

For this example, you need to create the following deployment descriptors with a text or XML editor and place them in the META-INF subdirectory within your staging directory.

<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN'
'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>

<!-- Generated XML! -->

<ejb-jar>
  <enterprise-beans>
    <message-driven>
      <ejb-name>myMDB</ejb-name>
      <ejb-class>MDBExample.myMessageDrivenBean</ejb-class>
      <transaction-type>Container</transaction-type>
      <acknowledge-mode>Auto-acknowledge</acknowledge-mode>
      <message-driven-destination>
        <destination-type>javax.jms.Topic</destination-type>
        <subscription-durability>NonDurable</subscription-durability>
      </message-driven-destination>
    </message-driven>
  </enterprise-beans>

  <assembly-descriptor>
    <container-transaction>
      <method>
        <ejb-name>myMDB</ejb-name>
        <method-name>onMessage</method-name>
      </method>
      <trans-attribute>NotSupported</trans-attribute>
    </container-transaction>
  </assembly-descriptor>

</ejb-jar>

<message-selector>company_name='objectmind'</message-selector>

<!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 7.0.0 EJB//EN'
'http://www.bea.com/servers/wls700/dtd/weblogic-ejb-jar.dtd'>

<!-- Generated XML! -->

<weblogic-ejb-jar>
  <weblogic-enterprise-bean>
    <ejb-name>myMDB</ejb-name>
    <message-driven-descriptor>
      <pool>
        <max-beans-in-free-pool>15</max-beans-in-free-pool>
        <initial-beans-in-free-pool>5</initial-beans-in-free-pool>
      </pool>

      <destination-jndi-name>myJMSTopic</destination-jndi-name>
      <jms-polling-interval-seconds>10</jms-polling-interval-seconds>
    </message-driven-descriptor>

    <transaction-descriptor>
    </transaction-descriptor>

    <jndi-name>myMDB</jndi-name>
  </weblogic-enterprise-bean>
</weblogic-ejb-jar>

<message-driven-descriptor>
  <connection-factory-jndi-name>myJMSConnectionFactory</connection-factory-jndi-name>
</message-driven-descriptor>

After the MDB class and its associated deployment descriptors are in their respective locations in the staging directory, the next step is packaging these files into a deployment unit—the EJB JAR file. To do this, issue the following jar command from within your staging directory after ensuring that you have set up your Java environment:

jar cvf std_mdb.jar MDBExample META_INF

Issuing this command creates the std_mdb.jar file (the deployment unit).

To generate container classes for this deployment unit, which the WebLogic EJB container uses to access the MDB, you need to use the WebLogic ejbc utility.

The ejbc compiler generates container classes according to the deployment elements you have specified in the weblogic-ejb.jar.xml deployment descriptor file. This is the ejbc command for generating container classes for the std_mdb.jar deployment unit:

java weblogic.ejbc std_mdb.jar mdb.jar

This command creates a new JAR file (mdb.jar) with the original EJB classes, interfaces, and XML deployment files in the JAR as well as the new container classes that ejbc generates. You will deploy mdb.jar to WebLogic Server later in this chapter.

Figure 22.7 shows issuing the jar and ejbc commands through a batch file named build.cmd.

Figure 22.7. Packaging the MDB example for deployment.

Before you can deploy your MDB to WebLogic Server, you must ensure that the JMS destination associated with the bean has been configured in the target WebLogic Server and, most important, that the topic is active. The JNDI name for the JMS topic associated with this example is myJMSTopic, which is specified via the <destination-jndi-name> weblogic-ejb-jar.xml element.

To deploy the mdb.jar deployment unit to your target WebLogic Server, follow these steps:

After your MDB has been deployed to WebLogic Server, the EJB container creates five instances of the bean in the free pool, as specified by the <initial-beans-in-free-pool> element in weblogic-ejb-jar.xml. Because logging was enabled in each method of myMessageDrivenBean (refer to Listing 22.2), the methods called to instantiate the been in the free pool are displayed in WebLogic Server’s stdout, as shown in Figure 22.9.

Figure 22.9. Use stdout to view the methods called to instantiate the MDB in the free pool.

After the MDB has been successfully deployed, using these steps to monitor the bean from the Administration Console is a good idea:

In the Deploy tab, shown in Figure 22.10, you can easily verify how many bean instances have been created and placed in the free pool and ensure that the bean is listening on an active JMS destination.

Figure 22.10. Monitoring your deployed MDB.

To test your MDB, you need to write a JMS client that sends a text message to the bean’s associated JMS topic (myJMSTopic). After the message is sent to the JMS topic, the EJB container calls the bean’s onMessage() method for message consumption and processing. Listing 22.5 provides the code for a JMS client (PubSubProducer) that sends five text messages to myJMSTopic.

import javax.naming.*;
import javax.jms.*;
import java.util.*;

public class PubSubProducer {

  private final static String NAMING_FACTORY=
                                     "weblogic.jndi.WLInitialContextFactory";
  private final static String TCON_FACTORY="javax.jms.TopicConnectionFactory";
  private final static String MESSAGE_TOPIC="myJMSTopic";

  public static void main ( String[] argv ){

    try {

      // Create a JNDI initial context
      Properties props = new Properties() ;
      props.put( Context.INITIAL_CONTEXT_FACTORY, NAMING_FACTORY);
      props.put( Context.PROVIDER_URL, "t3://einstein:7001");
      InitialContext ic = new InitialContext(props);

      // Look up a connection factory in JNDI
      TopicConnectionFactory tCF =
                           (TopicConnectionFactory)ic.lookup(TCON_FACTORY);

      // Create a connection
      TopicConnection tCon = tCF.createTopicConnection();

      // Create a session
      TopicSession tSession =
                   tCon.createTopicSession(false,Session.AUTO_ACKNOWLEDGE);

      // Look up the topic
      Topic topic = (Topic)ic.lookup(MESSAGE_TOPIC);

      // Create a TopicPublisher bound to the topic
      TopicPublisher tPublisher = tSession.createPublisher(topic);

      // Create a TextMessage
      TextMessage mes = tSession.createTextMessage("My First Message-Driven Bean Message!");

      // Start the topic, send the message, and close the topic
      tCon.start() ;

         for(int i = 0; i<5; i++ ) {
           tPublisher.publish(mes);
           System.out.println("  Sending Message - " + (i+1) +
                               " to the JMS Topic");
      }

         tCon.close() ;

    } catch ( NamingException e1 ) {
      System.out.println(e1);
    } catch ( JMSException e2 ) {
      System.out.println(e2);
    }
  }

}

To test your MDB, first compile the JMS client code (PubSubProducer.java) using the javac utility from a command shell. Then run the JMS client from the command shell by using the following command:

Java PubSubProducer

As shown in Figure 22.11, the JMS client sends five messages to the JMS topic, and the onMessage() method is called five times to process each message.

Figure 22.11. Testing your MDB with a JMS client.

When designing an MDB to use transactions, you must decide whether the bean will demarcate transactions programmatically via the onMessage() method (Bean-Managed Transaction, or BMT, demarcation) or whether the EJB container will perform transaction demarcation (Container-Managed Transaction, or CMT, demarcation).

You specify the transaction demarcation type of an MDB via the <transaction-type> element in the ejb-jar.xml deployment descriptor, for example:

With CMT demarcation, the EJB container demarcates transactions based on instructions in the ejb-jar.xml deployment descriptor. These instructions, called transaction attributes (as shown in Listing 22.6), tell the container whether it should run an MDB’s onMessage() method in a new transaction started by the container or run the method without any transactions.

<ejb-jar>
  ...
 <assembly-descriptor>
    ...
    <container-transaction>
      <description>Transactions required for this method.</description>
      <method>
        <ejb-name>myMDB</ejb-name>
        <method-name>onMessage</method-name>
      </method>
      <trans-attribute>NotSupported or Required</trans-attribute>
    </container-transaction>
    ...
 </assembly-descriptor>
  ...
</ejb-jar>

As shown in Listing 22.6, these are the only transaction attributes that are applicable to MDBs with CMT demarcations:

Avoiding Poison Messages with Container-Managed MDBs

If the onMessage() method does not successfully complete or the container rolls back the transaction, the container does not acknowledge a message receipt; the message remains in its associated JMS destination and is delivered again to the MDB. When a message continuously gets redelivered to a container-managed MDB only to be rolled back, the message is referred to as a poison message. Poison messages can have a negative impact on WebLogic JMS Server’s performance. They also consume MDB resources from the free pool, so they should removed from the JMS destination when they’re detected. WebLogic JMS Server has built-in support for detecting message redelivery attempts and for redirecting a message to an error destination when redelivery attempts for the message reach a specific limit. You can configure WebLogic JMS Server to manage poison messages via the Administration Console, as shown in Figure 22.12.

Figure 22.12. Manage poison messages via the Administration Console.

When an MDB uses BMT demarcation, you must use the EJBContext.getUserTransaction() callback to obtain a reference to the javax.transaction.UserTransaction object. After you have an instance of javax.transaction.UserTransaction, you can mark the beginning of a transaction with the begin() method, and end the transaction with the commit() or rollback() method. If the transaction commits, a message acknowledgement is sent to WebLogic JMS Server based on the value the <acknowledge-mode> element specifies in the ejb-jar.xml deployment descriptor: Auto-acknowledge or Dups-ok-acknowledge. The skeleton code for an onMessage() method using BMT is shown in Listing 22.7.

public void onMessage(Message msg) {
    try {
    // get the UserTranaction from the EJB context

    javax.transaction.UserTransaction mdbtx = mdb_context.getUserTransaction();

    // start the transaction

      mdbtx.begin();

      do some processing...

      if (OK Condition)

      {

        // commit the transaction

        mdbtx.commit();

      }

      else

      {

        // roll back transaction

        mdbx.rollback();

      }
    }
}