1. It has no home or remote interfaces, and is only a bean class.
2. It resembles a stateless session bean - that is, short-lived instances and does not retain state for a client.
3. A client interacts with the MDB in the same way it interacts with a JMS application or JMS server.
4. Through the MDB, EJB 2.0 Container sets itself up as a listener for asynchronous invocation and directly invokes the bean (no interfaces), which then behaves like an enterprise bean.
5. All instances of a particular MDB type are equivalent as they are not directly visible to the client and maintain no conversational state. This means that the Container can pool instances to enhance scalability.

Lifecycle of an MDB

The EJB Container performs several tasks at the beginning of the life cycle of the MDB:

1. Creates a message consumer (a QueueReceiver or TopicSubscriber) to receive the messages
2. Associates the bean with a destination and connection factory at deployment
3. Registers the message listener and the message acknowledgement mode

The lifecycle of an MDB depends on the lifespan of the EJB Server in which it is deployed. As MDBs are stateless, bean instances are typically pooled by the EJB Server and retrieved by the Container when a message becomes available on the topic or queue.

Writing an MDB

Writing an MDB involves the following tasks:

1. Implement the javax.ejb.MessageDrivenBean and javax.jms.MessageListener interfaces in the MDB class
2. Provide an implementation of the business logic inside the onMessage()
3. Provide a setMessageDrivenContext() method that associates the bean with its environment
4. Provide an ejbCreate() method that returns void and takes no arguments. This method may be blank
5. Provide an ejbRemove() method implementation. This method may be blank, unless certain resources need to be acquired before the bean goes out of scope

Sample application

The tutorial uses a sample application, StockTrader, to illustrate the writing of an MDB using a simple message driven bean buyAgentMDB that is contacted by a client which wishes to buy shares. The client looks up the BuyQueue and implements the javax.jms.MessageListener. It provides a private method buy() that takes two arguments: a double value that holds the price and a string stockSymbol that holds the scrip symbol.

Defining the MDB Class

An MDB implements two interfaces: javax.jms.MessageListener and javax.ejb.MessageDrivenBean. The MDB class is defined as public and cannot be defined as abstract or final. The MDB class looks like this:

public class BuyAgentMDB
    implements MessageDrivenBean, MessageListener {
    private MessageDrivenContext mdbContext;

The class must consist of:

1. A public constructor with no argument
2. A single onMessage method
3. public void ejbCreate() with no arguments
4. public void ejbRemove() usually used to free resources allocated in ejbCreate method
5. public void setMessageDrivenContext(MessageDrivenContext mdc): called by the container after the instance creation, with no transaction context

The class must not contain the finalize method.

Implementing business logic

Business logic for the EJB is triggered by the onMessage() method of the MDB. The onMessage() is called by the Container when the JMS Queue or Topic receives a message. The onMessage() does not return any result and has one argument. The full JMS message object is passed as an argument.

The signature for the method is:

public void onMessage(Message msg) {}

In the sample, when there is a message on the BuyQueue, the onMessage() method of the BuyAgent picks up the message and sends it to the topic StockMarket. The StockRepository in turn looks up this topic.

The following code of the buyAgentMDB performs this function:

public void onMessage(Message msg) {
	// Retrieves the text message
	TextMessage priceMessage = (TextMessage)  msg;
	try {

        }
	catch(JMSException ex)
	{ ex.printStackTrace();
	}
}

Implementing the ejbCreate method

The ejbCreate() is called at the time of bean instantiation, in order to allocate resources such as connection factories if the bean send messages or datasources, if the bean accesses databases. This method is invoked once in the lifecycle - when the bean is created.

The following code of the BuyAgentMDB performs this function:

public void ejbCreate () throws CreateException
	{
	}

Providing methods for transactional management

The setMessageDrivenContext provides the methods for transaction management. The BuyAgentMDB implements setMessageDrivenContext. This method is called by the EJB Container to associate the BuyAgent instance. The context is maintained by the Container.

The input parameter for setMessageDrivenContext is an instance of the MessageDrivenContext interface. It gives the MDB access to information about the runtime environment.

In Container-managed transactions, de-queuing occurs out of the onMessage(). The only methods on the MessageDrivenContext that are accessible to the MDB are transaction-related methods.

Removing the instance

This method is invoked when an MDB is being removed from a pool. Application server vendors may implement an arbitrary algorithm that decides when to remove the MDB instances from the pool.

The following code of the BuyAgentMDB performs this function:

public void ejbRemove()
	{
	//Removes the bean from the pool
	}

Acknowledging messages

For MDBs that use container-managed transactions, the Container automatically acknowledges a message when the EJB transaction commits. The Container over-rides the acknowledgement mode given in the deployment descriptor. If the EJB uses bean-managed transactions, both the receipt and the acknowledgement of a message occur outside the EJB transaction context.

Setting up the response

Some business cases may require responding to the Sender of the message that triggered the MDB. To register the "reply to" destination of the Sender, the client can use getJMSReplyTo header.

The JMSReplyTo header field contains a destination supplied by the client along with the message. It is the destination where a "reply to the message" may be sent. Messages sent with JMSReply value typically expect a response.

The code to use JMSReplyTo header looks like this:

public void onMessage(Message msg){
	try{
		destination d = msg.getJMSReplyTo()
	    }
	catch(JMSException jmse){} }

Deploying the MDB

The destination associated with an MDB is specified in the deployment descriptor of the MDB in the ejb-jar.xml file. A destination is a JMS administered object accessible via JNDI.

Here is a sample destination entry in the deployment descriptor:

      <message-driven-destination>
        	<destination-type>javax.jms.Topic</destination-type>
       	 <subscription-durability>NonDurable</subscription-durability>
      </message-driven-destination>

Elements in the deployment descriptor

The description of a MDB in the EJB 2.0 deployment descriptor contains the following specific elements:

1. the JMS acknowledgement mode: auto-acknowledge or dups-ok-acknowledge
2. an eventual JMS message selector: this is a JMS concept which allows the filtering of the messages sent to the destination
3. a message-driven-destination, which contains the destination type (Queue or Topic) and the subscription durability (in case of Topic)

The MDB deployment descriptor specifies whether the bean is intended for a Topic or a Queue. A bean set for a Topic can act as a durable subscriber guaranteeing that the listener receives all messages even if the listener is unavailable for some time. The deployment descriptor also sets transaction demarcation and security.

If the transaction type is "container", the transactional behavior of MDB methods is defined as for other enterprise beans in the deployment descriptor.

Here is the entry for transaction type in the deployment descriptor:

<transaction-type>Container</transaction-type>
<acknowledge-mode>Auto-acknowledge</acknowledge-mode>

For the onMessage method, only the Required or NotSupported transaction attribute must be used as there are no incoming transaction context.

The important thing to notice is that the deployment descriptor contains all the information except the destination name required to deploy a message-driven bean. The destination name is set in an application server's vendor-specific configuration file or as a system property (deploy time mapping).

Message Server configuration

• BuyQueue
• SellQueue
• StockMarket

The configuration file is located in the directory
[install_dir]/jms/config/jms-config.xml.

Deployment steps

The following steps will deploy the application on Pramati Server:

1. Start Pramati Server along with the JMS Server.
2. Start the Pramati Management Console from the Windows shortcut. Unix users must run runadmin.sh from the Server installation directory.
3. In the Console, select Server > Start from the main menu. This brings up the Start Server dialog where the J2EE Server to start is identified. Check the Start JMS Server option to start the Message Server along with the J2EE Server. This is essential to be able to run the message driven beans.

Deploying the application

When the Server starts, click on the Deploy button in the view panel of the Console to start the Deploy Tool.

Select Archive > Open and open the application stockapp.ear from the following location:

[install_dir]/samples/mdb/

Deploy the application.

Running the client

Set the classpath as follows:

Windows

Run the file run.bat from the directory

[install_dir]/samples/mdb.

Add the following location of the application classes to the client classpath:

[install_dir]/server/samples/mdb/classes

Unix

export CLASSPATH=$install_root/server/samples/mdb/classes:%$CLASSPATH

Starting the stock repository

The stock repository is run by the client StockServer.java. Start the client by executing:

java com.pramati.samples.mdb.StockServer

This brings up the stock repository panel which displays the scrip and the price along with a Buy/Sell advisory message.

Observe the price fluctuates every time buying or selling happens.

Summary

MDBs overcome the limitations of synchronous messaging using session and entity beans in the EJB 1.1 container. MDBs can be deployed in EJB 2.0 Container, which acts as a message listener and uses inbound messages as a trigger to invoke business methods in an asynchronous manner.

This tutorial outlined the steps involved in writing an MDB using a sample application that may be downloaded from www.pramati.com.

 © Copyright 2001-2002, Pramati Technologies.