Message-driven beans

An MDB is a type of Enterprise JavaBean (EJB) specifically designed as a message consumer. You can install an MDB as a listener on a message queue or topic. MDBs can listen for messages from either the EAServer JMS provider or a JCA 1.5 resource adapter.

By listening for messages from a resource adapter, MDBs can receive message types other than JMS. Resource adapters also enable an MDB to listen for messages from third-party JMS providers.

MDBs implement the javax.jms.MessageListener interface, which contains only the onMessage method. This example illustrates the skeleton code for a message listener:

class QueueMessageListener implements MessageListener
{
   public void onMessage(javax.jms.Message msg)
   {
      // process message, notify component
   }
}

Unlike other EJBs, message-driven beans do not have a home or remote interface, and clients cannot directly access an MDB. When an MDB is installed as a listener on a message queue or topic and a message arrives, EAServer instantiates the MDB and calls onMessage to notify the MDB that a message has been delivered to the queue or topic on which it is installed.

MDB interface methods

An MDB must implement the MessageDrivenBean interface, which consists of the following methods:

Method name	Description
ejbCreate	Creates an instance of an MDB.
setMessageDrivenContext	Associates an MDB instance with its context, which EAServer maintains. This provides the MDB instance access to the MessageDrivenContext interface.
ejbRemove	Notifies the MDB instance that it is being removed and should release its resources.

An MDB instance with container-managed transactions can call these MessageDrivenContext interface methods:

Method name	Description
setRollbackOnly	To specify that the current transaction must be rolled back.
getRollbackOnly	To test whether the current transaction has been marked to roll back.
getUserTransaction	Returns the javax.transaction.UserTransaction interface, with which the MDB can set and obtain transaction status.

For information about Enterprise JavaBeans, see the EJB User’s Guide.

Installing and configuring an MDB as a message listener

Deploy the EJB-JAR file that contains the MDB, as described in Chapter 2, “Deploying and Configuring EJB Components,” in the EJB User’s Guide.

When you deploy an EJB-JAR, EAServer creates an Ant configuration file, which contains the component property settings read from the EJB-JAR deployment descriptor. You may need to customize these settings.

The following example sets properties for the MDB called “MyQueueListener,” which is implemented by the ejb.components.cmstests.MyQueueListener component:

<setProperties component="ejb.components.cmstests.MyQueueListener">
  <property name="ejbName" value="MyQueueListener" /> 
  <property name="ejbClass"      value="ejb.components.cmstests.MyQueueListener_EJB" />
  <property name="j2eeType" value="MessageDrivenBean" />
  <messageListener queue="MyQueueListenerQueue" name="" />
  <activationConfig name="acknowledgeMode" value="Auto-acknowledge" />
  <classLoader name="ejb.components.cmstests" /> 
  <threadMonitor name="${ejb.serviceThreadMonitor}" /> 
  <instancePool timeout="${ejb.poolTimeout}" /> 
  <transaction type="NotSupported" batch="${ejb.transactionBatch}"      retry="${ejb.transactionRetry}" /> 
</setProperties>

To assign the MDB as a listener for a message queue or topic:

In the Management Console, expand the EJB Modules folder, and select the package that contains the MDB.
On the User Configuration tab, find the messageListener definition inside the <setProperties> tags for the MDB component.

To assign the listener to a message queue, set the value of messageListener queue to the name of a message queue; for example:
```
<setProperties component="ejb.components.cmstests.MyQueueListener">
  <messageListener queue="cts-mdb-test-queue" topic=""      threadCount="1" />
</setProperties>
```
To assign the listener to a message topic, set the value of messageListener topic to the name of a message topic; for example:
```
<setProperties component="ejb.components.cmstests.MyQueueListener">
  <messageListener queue="" topic="cts-mdb-test-topic"
     threadCount="1" />
</setProperties>
```

To configure the MDB to listen on the inbound resource adapter of a JCA 1.5 connector, instead of the JMS provider, set the value of messageListener name to the name of a com.sybase.djc.connector.MessageListener component; for example:
```
<setProperties component="ejb.components.cmstests.MyQueueListener">
  <messageListener name="myConnectorMessageListener" />
</setProperties>
```
Reconfigure or recompile the MDB properties—see “Updating component properties” in Chapter 2, “Deploying and Configuring EJB Components,” in the EAServer Enterprise JavaBeans User’s Guide.