Message-driven beans

An MDB is a type of Enterprise JavaBean (EJB) specifically designed as a JMS message consumer. You can install an MDB as a message listener on a message queue or topic.

When an MDB is installed as a listener on a message consumer and a JMS message arrives, EAServer instantiates the MDB to process the message. An MDB must implement the MessageDrivenBean interface, which consists of these 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.

Unlike other EJBs, message-driven Beans do not have a home or remote interface, and clients cannot directly access an MDB. EAServer calls the onMessage method of the javax.jms.MessageListener interface to notify an MDB that a message has been delivered to the queue or topic on which it is installed. To prevent client access to the onMessage method, this component property is set automatically when you install and configure an MDB:

com.sybase.jaguar.component.roles = onMessage(security-roles=ServiceControl)

Installing and configuring an MDB

Create a new EJB component, as described in Chapter 7, “Creating Enterprise JavaBeans Components.”

You do not need to define remote or local interfaces.
On the General tab, supply these values:
- Description – summarize the bean’s purpose.
- Component Type – select EJB - Message Driven Bean from the drop-down list.
- EJB Version – choose 2.0.
- MDB Class – enter the name of the Java class that implements the MDB; for example com.sybase.jaguar.myPkg.MyBeanImpl.
On the MDB Type tab, enter:
- Destination Type – choose either Queue or Topic.
- Name – enter the name of the destination queue or topic.
- Listener – enter the package and component name for the MDB listener; for example, MyPkg/MyBeanImpl. To specify a thread pool, append the thread pool name in square brackets, for example, MyPkg/MyBeanImpl[MyThreadPool].
  
  You can create thread pools in EAServer Manager as described in Chapter 8, “Setting up the Message Service,” in the EAServer System Administration Guide. The thread pool must have one or more worker threads. A thread pool with multiple worker threads enables the message listener to process multiple messages at the same time. If you do not specify the name of a thread pool, the message listener uses the <system> default thread pool, which has a single worker thread.
- Acknowledge Mode – choose either Auto or Dups-ok. For an explanation of the acknowledgment modes, see “Creating sessions”.
- Message Selector – if the destination type is a queue, enter a message selector to filter incoming messages; for example, to receive all published messages with the topic “StockPrice.SY”, enter:
```
topic = ‘StockPrice.SY’
```
- Subscription/Durability – if the destination type is a topic, select either Durable or Non-durable. For a description of these options, see “Creating message consumers”.
On the Transactions tab:
- Select one of Not Supported, Required, or Bean Managed.
- Optionally, select Automatic Failover.
“Component properties: Transactions” describes the options on this tab.
On the Run-As Mode tab, define the identity properties used for intercomponent calls. “Component properties: Run-As Mode” describes this tab in detail. If you do not specify a Run As Mode, the default value for an MDB is “System.”
Optionally specify a retry timeout. If your MDB throws an exception while processing a message, EAServer can retry delivery for the time period you specify. By default, EAServer does not retry delivery. To configure this setting:
1. Enable the Automatic Failover option on the Transactions tab.
2. On the Advanced tab, set the property com.sybase.jaguar.component.retry.timeout to the number of seconds that EAServer should retry delivery. EAServer retries at intervals that increase by about one second after each failure; that is, after one second, again after 3 seconds, again after 6 seconds, and so forth.

Similar to other EJBs, you can enter information on these tabs, but it is not required. For more information, see:

Tab	Description link
Instances	“Component properties: Instances”
Resources	“Component properties: Resources”
EJB References	“EJB references”
EJB Local References	“EJB local references”
Environment	“Environment properties”
Resource References	“Resource references”
Resource Environment References	“Resource environment references”
Role References	“Configuring role references and method permissions”
Java Classes	Chapter 30, “Configuring Custom Java Class Lists”
Additional Files	“Component properties: Additional Files”

Running the sample JMS client and MDB

EAServer includes a sample JMS client and MDB listener. For more information, see “Using message-driven beans and JMS” in Chapter 5, “Using the EAServer Samples,” in the EAServer Cookbook.

Related chapters

For information about Enterprise JavaBeans, see these chapters: