SCBCD Study Notes : Chapter 10 : Message-Driven Bean Component Contract (Part 1)

SCBCD Study Notes : Chapter 10 : Message-Driven Bean Component Contract (Part 1)

Please find the Study Notes and resources which covers 1st Part of Chapter 10 : Message-Driven Bean Component Contract, as part of the Sun Certified Business Component Developer exam CX-310-090.

1. Identify correct and incorrect statements or examples about the client view of a message-driven bean, and the life cycle of a message-driven bean.
2. Identify the interfaces and methods a JMS message-driven bean must implement.

Chapter 10. Message-Driven Bean Component Contract

Identify correct and incorrect statements or examples about the client view of a message-driven bean, and the life cycle of a message-driven bean.

To a client, a message-driven bean is simply a JMS message consumer. The client sends messages to the Destination (Queue or Topic) for which the message-driven bean is the MessageListener just as it would to any other Destination. The message-driven bean, like any other JMS message consumer, handles the processing of the messages.

From the perspective of the client, the existence of a message-driven bean is completely hidden behind the JMS destination for which the message-driven bean is the message listener.

A client locates the JMS Destination associated with a message-driven bean by using JNDI. For example, the Queue for the StockInfo message-driven bean can be located using the following code segment:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Context initialContext = new InitialContext(); ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Queue stockInfoQueue = (javax.jms.Queue)initialContext.lookup ;;;;;;;;;;;;;;;;
;;;;;;;("java:comp/env/jms/stockInfoQueue");;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Message-driven beans don't have home/local home and remote/local interfaces.

A client's JNDI name space may be configured to include the JMS Destinations of message-driven beans installed in MULTIPLE EJB Containers located on MULTIPLE machines on a NETWORK. The actual locations of an enterprise bean and EJB Container are, in general, transparent to the client using the enterprise bean.

When a client sends a message to a Destination for which a message-driven bean is the consumer, the container selects one of its METHOD-READY instances and invokes the instance's onMessage method.

The following steps describe the lifecyle of a message-driven bean instance:

• A message-driven bean instance's life starts when the container invokes newInstance() on the message-driven bean class to create a new instance. Next, the container calls setMessageDrivenContext(...) followed by ejbCreate() on the instance.
• The message-driven bean instance is now READY to be delivered a message sent to its Destination by any client.
• When the CONTAINER no longer needs the instance (which usually happens when the container wants to reduce the number of instances in the METHOD-READY POOL), the container invokes ejbRemove() on it. This ends the life of the message-driven bean instance.

The table defines the methods of a message-driven bean class in which the message-driven bean instances can access the methods of the javax.ejb.MessageDrivenContext interface, the java:comp/env environment naming context, resource managers, and other enterprise beans.

Table 10.1. Operations allowed in the methods of a message-driven bean class

• The getRollbackOnly() and setRollbackOnly() methods of the MessageDrivenContext interface should be used ONLY in the message-driven bean methods that execute in the context of a transaction. The Container must throw the java.lang.IllegalStateException if the methods are invoked while the instance is not associated with a transaction.

The reasons for disallowing operations in the table:

• Invoking the getCallerPrincipal() and isCallerInRole(...) methods is DISALLOWED in the message-driven bean methods because the Container DOES NOT HAVE a client security context. The Container MUST throw and log the java.lang.IllegalStateException if either of these methods is invoked.
• Invoking the getRollbackOnly() and setRollbackOnly() methods is DISALLOWED in the message-driven bean methods for which the Container DOES NOT HAVE a meaningful transaction context, and for all message-driven beans with bean-managed transaction demarcation (BMT).
• The UserTransaction interface is UNAVAILABLE to message-driven beans with container-managed transaction demarcation (CMT).
• Invoking getEJBHome() or getEJBLocalHome() is DISALLOWED in message-driven bean methods because THERE ARE NO EJBHome or EJBLocalHome objects for message-driven beans. The Container MUST throw and log the java.lang.IllegalStateException if these methods are invoked.

.

Identify the interfaces and methods a JMS message-driven bean must implement.

All message-driven beans MUST implement, directly or indirectly, the MessageDrivenBean interface. The class MUST be defined as public and it cannot be defined as final nor abstract. The MessageDrivenBean interface defines TWO methods all message-driven beans must implement:

1. The setMessageDrivenContext(...) method is called by the bean's container to associate a message-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 container calls this method at the beginning of the bean's life cycle.

2. 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 (possibly allocated in the ejbCreate() method).

The Bean Provider CANNOT assume that the Container will always invoke the ejbRemove() method on a message-driven bean instance. The following scenarios result in ejbRemove() NOT being called on an instance:

• A crash of the EJB Container.
• A system exception thrown from the instance's method to the Container.

If the message-driven bean instance allocates resources in the ejbCreate() method and/or in the onMessage(...) method, and releases normally the resources in the ejbRemove() method, these resources will NOT be automatically released in the above scenarios. The application using the message-driven bean should provide some clean up mechanism to periodically clean up the unreleased resources.

The MessageDrivenBean extends the EnterpriseBean interface:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
package javax.ejb; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
public interface MessageDrivenBean extends javax.ejb.EnterpriseBean { ;;;;;;;;
;;;;;;;public void setMessageDrivenContext(MessageDrivenContext context) ;;;;;
;;;;;;;;;;;;;;throws EJBException; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;public void ejbRemove() throws EJBException; ;;;;;;;;;;;;;;;;;;;;;;;;;;
} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
public interface EnterpriseBean extends java.io.Serializable { ;;;;;;;;;;;;;;;
};;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

All message-driven beans MUST implement, directly or indirectly, 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.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
package javax.jms; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
public interface MessageListener { ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;public void onMessage(Message message); ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

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.

EVERY message-driven bean class MUST implement following FOUR methods:

1. public void setMessageDrivenContext(MessageDrivenContext mdc)

The container normally calls this method exactly once, after instantiation, to pass in the associated MessageDrivenContext.

2. public void ejbCreate()

Called after the setMessageDrivenContext(...) method. This is a good time to access or obtain any resources that will be used for the life of the bean.

3. public void onMessage(Message msg)

Called by the container when a message has arrived on the bean's associated Queue or Topic. Your code should check for the expected message types, using the instanceof operator, because there is nothing to stop a client from sending any of the available message types. Other than those that deal with the Message object, no JMS methods need be invoked by the bean; it just cracks or parses the received message and performs any associated operations.

4. public void ejbRemove()

Called when the container intends to terminate the bean. All resources should be released at this time.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
public class ReservationProcessorBean ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;implements javax.ejb.MessageDrivenBean, ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;javax.jms.MessageListener { ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;MessageDrivenContext ejbContext; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;Context jndiContext; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;public void setMessageDrivenContext (MessageDrivenContext mdc) { ;;;;;;;;
;;;;;;;;;;ejbContext = mdc; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;try ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;{ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;jndiContext = new InitialContext (); ;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;} catch(NamingException ne) { ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;throw new EJBException (ne); ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;public void ejbCreate () {} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;public void onMessage (Message message) { ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;try { ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;MapMessage reservationMsg = (MapMessage)message; ;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;Integer customerPk = (Integer) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;reservationMsg.getObject ("CustomerID"); ;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;Integer cruisePk = (Integer) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;reservationMsg.getObject ("CruiseID"); ;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;.... ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;// can access other EJBs ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;ReservationHomeLocal resHome = (ReservationHomeLocal) ;;;;;;;;;
;;;;;;;;;;;;;;;jndiContext.lookup ("java:comp/env/ejb/ReservationHomeLocal");
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;ReservationLocal reservation = ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;resHome.create (customer, cruise, cabin, price, new Date ()); ;
;;;;;;;;;;;;;;;.... ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;} catch(Exception e) { ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;// can throw only runtime (unchecked) exceptions ;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;throw new EJBException (e); ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;... ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;public void ejbRemove () { ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;try { ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;jndiContext.close (); ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;ejbContext = null; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;} catch(NamingException ignored) { } ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;} ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
};;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

________________
Author: Mikalai Zaikin. Please Click Here to visit Authors site for any updates and changes to the study notes.