The Message-Driven Bean Class

An MDB class implements the javax.ejb.MessageDrivenBean and javax.jms.MessageListener interfaces, as shown in Figure 22.4.

Figure 22.4. The implementation of an MDB class.

The MessageDrivenBean interface, which extends the javax.ejb.EnterpriseBean interface, declares two methods : ejbRemove() and setMessageDrivenContext() . The bean developer must implement these methods along with the ejbCreate() method inherited from the EnterpriseBean interface. The MessageListener interface declares only one method that the bean developer must implement: onMessage() . Listing 22.1 shows the basic components required to implement an MDB.

Listing 22.1 The Basic Components of an MDB Class

 public class myMDB implements MessageDrivenBean, MessageListener{   public myMDB() {...}; // Required Bean Constructor   public void ejbCreate() {...}   public void setMessageDrivenContext(MessageDrivenContext ...) {...}   public void onMessage(javax.jms.Message MessageName) {...}   public void ejbRemove() {...} } 

The following sections briefly describe the four methods that constitute an MDB class and discuss how to handle exceptions in MDBs.

Note

The MDB class is allowed to implement other methods, such as utility methods called internally by onMessage() . However, these methods are never called directly by the container or any client.

The ejbCreate() Method

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 name must be ejbCreate .

• The method must be declared as public, not as final or static.

• The return type must be void.

• The method can have no arguments.

• The throws clause must not define any application exceptions.

The setMessageDrivenContext() Method

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:

• setRollbackOnly() ” Marks a transaction to roll back so that it cannot commit. The bean can use this method only if it uses Container-Managed Transaction demarcation .

• getRollbackOnly() ” Returns a Boolean value indicating whether the transaction can commit. The bean can use this method only if it uses Container-Managed Transaction demarcation.

  Caution

  The getRollbackOnly() and setRollbackOnly() methods should be used only in MDB methods that execute in the context of a transaction; otherwise , the container throws java.lang.IllegalStateException .

  
  

• getUserTransaction() ” Returns a reference to the javax.transaction.UserTransaction object that allows the bean to initiate, commit, and roll back transactions from within the bean. The bean can use this method only if it uses Bean-Managed Transaction demarcation.

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 bean does not receive a client security context.

• The bean does not have EJBHome or EJBLocalHome objects associated with it.

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

• The method must be declared as public, not as final or static.

• The method must accept one argument of type javax.ejb.MessageDrivenContext .

• The method must return void.

• The method should not include a throws clause.

The onMessage() Method

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 method must be declared as public, not as final or static.

• The return type must be void.

• The method must have a single argument of type javax.jms.Message .

• The throws clause must not define any application exceptions.

The ejbRemove() Method

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:

• The method must be declared as public, not as final or static.

• The method's return type must be void.

• The method can have no arguments.

• The throws clause must not define any application exceptions.

Handling Exceptions

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:

• For the onMessage() method, use a try-catch block to catch any exceptions.

• For the ejbCreate() method, you can include javax.ejb.CreateException in the throws clause.

• For the ejbRemove() method, you can use javax.ejb.EJBExecption in the throws clause.

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.