Sun Microsystems Inc

Protocol between a message-driven bean instance and its containerEnterprise JavaBeans 2.0, Public Draft Message-driven Bean Com-

The setMessageDrivenContext method is called by the bean’s container to associate a mes- sage-driven bean instance with its context maintained by the container. Typically a message-driven bean instance retains its message-driven context as part of its state.

The ejbRemove notification signals that the instance is in the process of being removed by the container. In the ejbRemove method, the instance releases the resources that it is holding.

14.4.2 The required javax.jms.MessageListener interface

The MessageDrivenBean interface extends the javax.jms.MessageListener interface.

The onMessage method is called by the bean’s container when a message has arrived for the bean to service. The onMessage method contains the business logic that handles the processing of the message. The onMessage method has a single argument, the incoming message.

Only message-driven beans can asynchronously receive messages. Session and entity beans are not permitted to be JMS MessageListeners.

14.4.3 The MessageDrivenContext interface

The container provides the message-driven bean instance with a MessageDrivenContext. This gives the message-driven bean instance access to the instance’s context maintained by the container. The MessageDrivenContext interface has the following methods:

•The setRollbackOnly method allows the instance to mark the current transaction such that the only outcome of the transaction is a rollback. Only instances of a message-driven bean with container-managed transaction demarcation can use this method.

•The getRollbackOnly method allows the instance to test if the current transaction has been marked for rollback. Only instances of a message-driven bean with container-managed transaction demarcation can use this method.

•The getUserTransaction method returns the javax.transaction.UserTransaction interface that the instance can use to demarcate transactions, and to obtain transaction status. Only instances of a message-driven bean with bean-managed transaction demarcation can use this method.

•The getCallerPrincipal method is inherited from the EJBContext interface. Mes- sage-driven bean instances must not call this method.

•The isCallerInRole method is inherited from the EJBContext interface. Message-driven bean instances must not call this method.

•The getEJBHome method is inherited from the EJBContext interface. Message-driven bean instances must not call this method.

Sun Microsystems Inc.

14.4.4 Message-driven bean’s ejbCreate() method

The container creates an instance of a message-driven bean in three steps. First, the container calls the bean class’ newInstance method to create a new message-driven bean instance. Second, the container calls the setMessageDrivenContext method to pass the context object to the instance. Third, the container calls the instance’s ejbCreate method.

Each message-driven bean class must have one ejbCreate method, with no arguments.

14.4.5 Serializing message-driven bean methods

A container serializes calls to each message-driven bean instance. Most containers will support many instances of a message-driven bean executing concurrently; however, each instance sees only a serialized sequence of method calls. Therefore, a message-driven bean does not have to be coded as reentrant.

The container must serialize all the container-invoked callbacks (i.e. ejbRemove methods), and it must serialize these callbacks with the onMessage method calls.

14.4.6 Concurrency of message processing

A container allows many instances of a message-driven bean class to be executing concurrently, thus allowing for the concurrent processing of a stream of messages. No guarantees are made as to the exact order in which messages are delivered to the instances of the message-driven bean class, although the container should attempt to deliver messages in order when it does not impair the concurrency of message processing. Message-driven beans should therefore be prepared to handle messages that are out of sequence: for example, the message to cancel a reservation may be delivered before the message to make the reservation.

14.4.7 Transaction context of message-driven bean methods

The onMessage method is invoked in the scope of a transaction determined by the transaction attribute specified in the deployment descriptor. If the bean is specified as using container-managed

transaction demarcation, either the Required or the NotSupported transaction attribute must be used.[21]

When a message-driven bean using bean-managed transaction demarcation uses the javax.transaction.UserTransaction interface to demarcate transactions, the message receipt that causes the bean to be invoked is not part of the transaction. If the message receipt is to be part of the transaction, container-managed transaction with the Required transaction attribute must be used.

A message-driven bean’s newInstance,setMessageDrivenContext, ejbCreate, and ejbRemove methods are called with an unspecified transaction context. Refer to Subsection 16.7.5 for how the Container executes methods with an unspecified transaction context.

[21]Use of the other transaction attributes is not meaningful for message-driven beans, because there can be no pre-existing transaction context and no client to handle exceptions.

Sun Microsystems Inc

Protocol between a message-driven bean instance and its containerEnterprise JavaBeans 2.0, Public Draft Message-driven Bean Com-

There is never a client transaction context available when a message-driven bean is invoked because a distributed transaction context does not flow with a JMS message.

14.4.8 Message acknowledgement

Message-driven beans should not attempt to use the JMS API for message acknowledgment. Message acknowledgment is automatically handled by the container. If the message-driven bean uses container managed transaction demarcation, message acknowledgment is handled automatically as a part of the transaction commit. If bean managed transaction demarcation is used, the message receipt cannot be part of the bean-managed transaction, and, in this case, the receipt is acknowledged by the container. If bean managed transaction demarcation is used, the Bean Provider can indicate in the jms-acknowedge-mode deployment descriptor element whether JMS AUTO_ACKNOWLEDGE semantics or DUPS_OK_ACKNOWLEDGE semantics should apply. If the jms-acknowl- edge-mode deployment descriptor element is not specified, JMS AUTO_ACKNOWLEDGE semantics are assumed.

14.4.9 Association of a message-driven bean with a destination

A message-driven bean is associated with a JMS Destination (Queue or Topic) when the bean is deployed in the container. It is the responsibility of the Deployer to associate the message-driven bean with a Queue or Topic.

The Deployer should avoid associating more than one message-driven bean with the same JMS Queue. If there are multiple JMS consumers for a queue, JMS does not define how messages are distribued between the queue receivers.

The Bean Provider may provide advice to the Deployer as to whether a message-driven bean is intended to be associated with a queue or a topic by using the message-driven-destination deployment descriptor element.

If the message-driven bean is intended to be used with a topic, the Bean Provider may further indicate whether a durable or non-durable subscription should be used by specifying the jms-subscrip- tion-durability element. If a topic subscription is specified and the jms-subscrip- tion-durability element is not specified, a non-durable subscription is assumed.

14.4.10 Dealing with exceptions

The onMessage method of a message-driven bean must not throw application exceptions or the java.rmi.RemoteException.

Message-driven beans, like other well-behaved JMS MessageListeners, should not, in general, throw

RuntimeExceptions.

A RuntimeException thrown from any method of the message-driven bean class (including the onMessage method and the callbacks invoked by the Container) results in the transition to the “does not exist” state. Exception handling is described in detail in Chapter 17.