Chapter 7   Using Message Driven Beans


This chapter describes a Message Driven Bean and its properties. This chapter also provides additional guidelines for creating message- driven beans and deploying them to iPlanet Application Server.

This chapter contains the following sections:

• Components of Message Driven Beans

• Message Driven Bean Guidelines

• Accessing iPlanet Application Server Functionality

• Using the Deployment Tool

• Creating the Deployment Descriptors by Hand

  
  

  ---

  Note	The message-driven bean functionality in iPlanet Application Server is meant for developer use only. It has neither been tested or certified for production environments.

  ---

  
  

Introducing Message Driven Beans

---

iPlanet Application Server uses the iPlanet Message Queue for Java, 2.0 SP1 as the messaging middleware application that implements the JMS specifications. You must install iMQ for Java, 2.0 SP1 before you can use message-driven beans on iPlanet Application Server.

iMQ for Java, 2.0 SP1 is bundled on the iPlanet Application Server installation CD. If you don't have the installation CD, you can download a free, developer edition from http://www.iplanet.com/products/iplanet_message_queue/home_message_queue.html.

How a Message Driven Bean is Accessed

A message-driven bean interfaces with the Java Message Service (JMS). In other words, a Message Driven Bean is a JMS Listener. JMS middleware and the message-driven bean's container jointly control the delivery of messages to JMS MessageListener objects.

---

Note	To use message-driven beans, yopu must first configure a JMS Provider and set up the message queue object. For detailed information on setting up and configuring a JMS provider, see Chapter 11, "Administering Message Driven Beans," in iPlanet Application Server Administrator's Guide.

---

The following steps describe the actions that follow a client request:

1. When the application server boots up, it will load up all deployed message-driven beans and start up the message listeners.

   The application server registers it's destination specific representative with JMS, using iPlanet Application Server's ServerSessionPool.

2. A client, such as a browser, or a servlet, or a stand-alone application sends a message to the JMS destination.

3. The JMS calls the application server's callback for the specified destination to serve the request.

4. The JMS Session's MessageListener will be the container for an instance of a Message Driven Bean.

   When a message arrives, the container calls the message-driven bean's onMessage method to process the message. The onMessage method normally casts the message to one of the five JMS message types and handles it in accordance with the application's business logic. The onMessage method may call helper methods, or it may invoke a session or entity bean to process the information in the message or to store it in a database.

   A message may be delivered to a message-driven bean within a transaction context, so that all operations within the onMessage method are part of a single transaction. If message processing is rolled back, the message will be resent.

5. iPlanet Application Server takes care of the supported services, such as transactions, security, etc., and delegates the servicing of the request to the bean's business method.

6. The JMS removes the message from the queue and sends an acknowledgement back to the client if there was a reply-to property in the message.

7. In case of failure, the JMS tries to send the message again.

The following figure shows the request flow path for a deployed bean:

Figure 7-1   

Request flow path

The ConnectionConsumer and Session are part of the JMS Provider. The ServerSessionPool, ServerSession and the Message Listener are part of iPlanet Application Server.

Components of Message Driven Beans

---

When creating a message-driven beans, you must provide the following class files:

• Enterprise bean class definition.

• Enterprise bean metadata (Deployment Descriptors (DDs) and other configuration information).

Creating the Class Definition

For a message-driven bean, the bean class must be defined as public and cannot be abstract. The bean class must implement the javax.ejb.MessageDrivenBean interface. For example:

import javax.jms.*;
import javax.ejb.*;
public class MySessionBean implements MessageDrivenBean, MessageListener {
// message-driven bean implementation. These methods must always included.
public void ejbRemove() throws RemoteException{
}
public void setMessageDrivenContext(MessageDrivenContext ctx) throws RemoteException {
}

// other code omitted here....
}

The message-driven bean must also implement one or more ejbCreate(...) methods. There must be one method for each way a client invokes the bean. For example:

public void ejbCreate() {
}

Each ejbCreate (...) method must be declared as public, return void, and be named ejbCreate. The throws clause may include java.rmi.RemoteException or java.ejb.CreateException

Message Driven Bean Guidelines

---

Before deciding which parts of an application you can represent as message-driven beans, you should know a few more aspects about message-driven beans. A couple of these are related to the EJB specification for message-driven beans, and a couple are specific to iPlanet Application Server and its support for message-driven beans.

Accessing iPlanet Application Server Functionality

---

This section contains the following topics:

• Managing Transactions

• Committing a Transaction

• Accessing Databases

You can develop message-driven beans that adhere strictly to the EJB specification, you can develop message-driven beans that take advantage of both the specification and additional, value-added iPlanet Application Server features, or you can develop message-driven beans that adhere to the specification in non-iPlanet Application Server environments, but that take advantage of iPlanet Application Server features if they are available. Make the choice that is best for your intended deployment scenario.

The iPlanet Application Server offers several features through the iPlanet Application Server container, and the iPlanet Application Server APIs enable applications to take programmatic advantage of specific iPlanet Application Server environment features. Embed API calls in message-driven beans if you plan on using those beans only in an iPlanet Application Server environment.

For example, you can trigger a named application event from an EJB using the IAppEventMgr interface by using the following steps and example:

1. First obtain a com.kivasoft.IContext instance by casting javax.ejb.SessionContext or javax.ejb.EntityContext to IServerContext.

2. Next, use the GetAppEventMgr() method in the GXContext class to create an IAppEventMgr object.

3. Finally, trigger the application event with triggerEvent().

   javax.ejb.SessionContext m_ctx;
   ....
   com.netscape.server.IServerContext sc;
   sc = (com.netscape.server.IServerContext) m_ctx;
   com.kivasoft.IContext kivaContext = sc.getContext();
   IAppEventMgr mgr = com.kivasoft.dlm.GXContext.GetAppEventMgr(ic);
   mgr.triggerEvent("eventName");

Managing Transactions

Many message-driven beans interact with databases. You control bean transactions by using settings in the bean's property file. This permits specifying transaction attributes at bean deployment time. By having a bean handle transaction management there is no need to explicitly start, rollback, or commit transactions in the bean's database access methods.

By moving transaction management to the container level, you gain the ability to place all the bean's activities—even those not directly tied to the database access—under the same transaction control as your database calls. This guarantees that all application parts controlled by a message-driven bean run as part of the same transaction, and either everything the bean undertakes is committed, or it is rolled back in a failure case. In effect, a container managed transactional state permits synchronizing the application without programming any synchronization routines.

Committing a Transaction

When a commit occurs, it signals the container that the message-driven bean has completed its useful work and tells the container to synchronize its state with the underlying datasource. The container permits the transaction to complete and then frees the bean.

Note that transactions from the container are implicitly committed. Also, any participant can rollback a transaction. For details about transactions, see Chapter 8 "Handling Transactions with EJBs."

Accessing Databases

Many message-driven beans access and update data. Because message-driven beans are transient, be careful about how accesses occur. In general, use the JDBC API to make calls, and always use the transaction and security management methods described in Chapter 8 " Handling Transactions with EJBs" to manage the transaction isolation level and transaction requirements at the bean level.

For details about database access, see Chapter 9 "Using JDBC for Database Access."

Using the Deployment Tool

---

A simpler way to create the standard ejb-jar deployment descriptors for a message-driven bean is by using the iPlanet Application Server Deployment Tool.

Deploying a message-driven bean is similar to deploying other applications using the Deploy Tool.

Start by either opening an existing EJB Module or creating a new one. Once the EJB's class files have been added to the EJB Module, you can right-click on the bean to edit its descriptor, as shown in the following figure:

Figure 7-2   

Selecting a message-driven bean in Deployment Tool

---

Note

You can start creating your EJB's deployment descriptors in the iPlanet Application Server's Deployment Tool, save the application in the tool, edit the files by hand, and then go back into the tool. However, if you do this, make sure you re-open the EJB Module or J2EE Application in the tool before you edit the deployment descriptors, then re-save the application in the tool after you make the changes. If you fail to do this, your changes in the user interface will not reflected in the deployment descriptors.

---

You have to provide the following information in the Deploy Tool's deployment descriptor dialog box:

J2EE Specific Deployment Descriptor Fields

• Bean Name

• Bean Type (Message Driven Bean)

• Implementation Class Name

• Transaction Management Type ( Container managed or Bean Managed )

Message Driven Bean Specific Parameters

• Destination Type (Queue or Topic)

• Destinantion Name

• Durable Name (for Topic subscription only -- optional)

• Topic Subscription Durable (optional)

• Message Selector (optional)

• Acknowledgement Mode ( Auto-acknowledge, or Duplicates-Auto-Acknowledge)

• Max Message Limit

• Security Identity Type (Only Run-as-specified-user allowed)

• Run-As Role Name

  
  

  ---

  Note	There is a security risk here if the user role has administrative privileges over the data accesses by the message-driven bean. Any user who authenticates to the message-driven bean will inherit the privileges of the specified security role.

  ---

  
  

• Max Pool Size

• Min Pool Size

• Transaction Manager Type (Local or Global -- if not selected, the Transaction Manager Type for this module will be used)

Creating the Deployment Descriptors by Hand

---

Sample Deployment Descriptor File

<ias-mdbs>

<!-- This is an extract from the EJB 2.0 DTD based deployment descriptor --<&/tt>

<ejb-jar>

<enterprise-beans>

<message-driven>

<ejb-name>MyMDB1</ejb-name>

<ejb-class>mycompany.mypackage.MyMDB1</ejb-class>

<transaction-type>Container</transaction-type>

<message-driven-destination>

<jms-destination-type>javax.jms.Topic</jms-destination-type>

</message-driven-destination>

<security-identity>

<run-as-specified-identity>

<role-name>asmith</role-name>

</run-as-specified-identity>

</security-identity>

</message-driven>

</enterprise-beans>

</ejb-jar>

<!-- This contains all the ias specific deployment information --<&/tt>

<ias-ejb-jar>

<ias-enterprise-bean>

<ejb-name>MyMDB1</ejb-name>

<message-driven-descriptor>

<jms-destination>

<jndi-name>MyMDB1</jndi-name>

<jms-topic-subscription>

<durable>true</durable>

</jms-topic-subscription>

</jms-destination>

<pool>

<max-pool-size>100</max-pool-size>

<min-pool-size>10</min-pool-size>

</pool>

</message-driven-descriptor>

</ias-enterprise-bean>

</ias-ejb-jar>

For more information, refer to the XML DTD (IASEjb_jar_1_1.dtd) for an EJB JAR file in the iASInstallDir/ias/dtd.