JavaTM Message Service Tutorial
Tutorial Homepage | TOC | Prev | Next | Index

6    Using the JMS API in a J2EETM Application

This chapter describes the ways in which using the JMS API in a J2EETM application differs from using it in a standalone client application:

This chapter assumes that you have some knowledge of the J2EE platform and J2EE components. If you have not already done so, you may wish to read the J2EE Tutorial ( or the JavaTM 2 Platform, Enterprise Edition Specification, v1.3 (available from

6.1   Using Enterprise Beans to Produce and to Synchronously Receive Messages

A J2EE application that produces messages or synchronously receives them may use any kind of enterprise bean to perform these operations. The example in Chapter 8 uses a stateless session bean to publish messages to a topic.

Because a blocking synchronous receive ties up server resources, it is not a good programming practice to use such a receive call in an enterprise bean. Instead, use a timed synchronous receive, or use a message-driven bean to receive messages asynchronously. For details about blocking and timed synchronous receives, see Section 4.2.1, "Writing the PTP Client Programs."

Using the JMS API in a J2EE application is in many ways similar to using it in a standalone client. The main differences are in administered objects, resource management, and transactions.

6.1.1   Administered Objects

The Platform Specification recommends that you use java:comp/env/jms as the environment subcontext for Java Naming and Directory InterfaceTM (JNDI) API lookups of connection factories and destinations. With the J2EE SDK 1.3.1, you use the Application Deployment Tool, commonly known as the deploytool, to specify JNDI API names that correspond to those in your source code.

Instead of looking up a JMS API connection factory or destination each time it is used in a method, it is recommended that you look up these instances once in the enterprise bean's ejbCreate method and cache them for the lifetime of the enterprise bean.

6.1.2   Resource Management

A JMS API resource is a JMS API connection or a JMS API session. In general, it is important to release JMS resources when they are no longer being used. Here are some useful practices to follow.

6.1.3   Transactions

Instead of using local transactions, you use the deploytool to specify container-managed transactions for bean methods that perform sends and receives, allowing the EJBTM container to handle transaction demarcation. (You can use bean-managed transactions and the javax.transaction.UserTransaction interface's transaction demarcation methods, but you should do so only if your application has special requirements and you are an expert in using transactions. Usually, container-managed transactions produce the most efficient and correct behavior.)

6.2   Using Message-Driven Beans

As we noted in Section 1.4, "How Does the JMS API Work with the J2EE Platform?," the J2EE platform supports a new kind of enterprise bean, the message-driven bean, which allows J2EE applications to process JMS messages asynchronously. Session beans and entity beans allow you to send messages and to receive them synchronously but not asynchronously.

A message-driven bean is a message listener that can reliably consume messages from a queue or a durable subscription. The messages may be sent by any J2EE component--from an application client, another enterprise bean, or a Web component--or from an application or a system that does not use J2EE technology.

Like a message listener in a standalone JMS client, a message-driven bean contains an onMessage method that is called automatically when a message arrives. Like a message listener, a message-driven bean class may implement helper methods invoked by the onMessage method to aid in message processing.

A message-driven bean differs from a standalone client's message listener in five ways, however.

See for a simple example of a message-driven bean.

The main difference between a message-driven bean and other enterprise beans is that a message-driven bean has no home or remote interface. Rather, it has only a bean class.

A message-driven bean is similar in some ways to a stateless session bean: its instances are relatively short-lived and retain no state for a specific client. The instance variables of the message-driven bean instance can contain some state across the handling of client messages: for example, a JMS API connection, an open database connection, or an object reference to an enterprise bean object.

Like a stateless session bean, a message-driven bean can have many interchangeable instances running at the same time. The container can pool these instances to allow streams of messages to be processed concurrently. Concurrency can affect the order in which messages are delivered, so you should write your application to handle messages that arrive out of sequence.

To create a new instance of a message-driven bean, the container instantiates the bean and then

  1. Calls the setMessageDrivenContext method to pass the context object to the instance
  2. Calls the instance's ejbCreate method

Figure 6.1 shows the life cycle of a message-driven bean.

Figure 6.1   Life Cycle of a Message-Driven Bean

6.3   Managing Distributed Transactions

JMS client applications use JMS API local transactions, described in Section 5.2.2, "Using JMS API Local Transactions," which allow the grouping of sends and receives within a specific JMS session. J2EE applications commonly use distributed transactions in order to ensure the integrity of accesses to external resources. For example, distributed transactions allow multiple applications to perform atomic updates on the same database, and they allow a single application to perform atomic updates on multiple databases.

In a J2EE application that uses the JMS API, you can use transactions to combine message sends or receives with database updates and other resource manager operations. You can access resources from multiple application components within a single transaction. For example, a servlet may start a transaction, access multiple databases, invoke an enterprise bean that sends a JMS message, invoke another enterprise bean that modifies an EIS system using the Connector architecture, and finally commit the transaction. Your application cannot, however, both send a JMS message and receive a reply to it within the same transaction; the restriction described in Section 5.2.2, "Using JMS API Local Transactions," still applies.

Distributed transactions can be either of two kinds:

You can use either container-managed transactions or bean-managed transactions with message-driven beans.

To ensure that all messages are received and handled within the context of a transaction, use container-managed transactions and specify the Required transaction attribute for the onMessage method. This means that a new transaction will be started before the method is called and will be committed when the method returns. An onMessage call is always a separate transaction, because there is never a transaction in progress when the method is called.

When you use container-managed transactions, you can call the following MessageDrivenContext methods:

If you use bean-managed transactions, the delivery of a message to the onMessage method takes place outside of the distributed transaction context. The transaction begins when you call the UserTransaction.begin method within the onMessage method and ends when you call UserTransaction.commit. If you call UserTransaction.rollback, the message is not redelivered, whereas calling setRollbackOnly for container-managed transactions does cause a message to be redelivered.

Neither the JMS API Specification nor the Enterprise JavaBeansTM Specification (available from specifies how to handle calls to JMS API methods outside transaction boundaries. The Enterprise JavaBeans Specification does state that the EJB container is responsible for acknowledging a message that is successfully processed by the onMessage method of a message-driven bean that uses bean-managed transactions. Using bean-managed transactions allows you to process the message by using more than one transaction or to have some parts of the message processing take place outside a transaction context. In most cases, however, container-managed transactions provide greater reliability and are therefore preferable.

When you create a session in an enterprise bean, the container ignores the arguments you specify, because it manages all transactional properties for enterprise beans. It is still a good idea to specify arguments of true and 0 to the createQueueSession or the createTopicSession method to make this situation clear:

queueSession = queueConnection.createQueueSession(true, 0);

When you use container-managed transactions, you usually specify the Required transaction attribute for your enterprise bean's business methods.

You do not specify a message acknowledgment mode when you create a message-driven bean that uses container-managed transactions. The container acknowledges the message automatically when it commits the transaction.

If a message-driven bean uses bean-managed transactions, the message receipt cannot be part of the bean-managed transaction, so the container acknowledges the message outside of the transaction. When you package a message-driven bean using the deploytool, the Message-Driven Bean Settings dialog box allows you to specify the acknowledgment mode, which can be either AUTO_ACKNOWLEDGE (the default) or DUPS_OK_ACKNOWLEDGE.

If the onMessage method throws a RuntimeException, the container does not acknowledge processing the message. In that case, the JMS provider will redeliver the unacknowledged message in the future.

6.4   Using the JMS API with Application Clients and Web Components

An application client can use the JMS API in much the same way a standalone client program does. It can produce messages, and it can consume messages by using either synchronous receives or message listeners. See Chapter 7 for an example of an application client that produces messages; see Chapter 9 and Chapter 10 for examples of using application clients to produce and to consume messages.

The J2EE Platform Specification does not define how Web components implement a JMS provider. In the J2EE SDK 1.3.1, a Web component--one that uses either the Java Servlet API or JavaServerPagesTM (JSPTM) technology--may send messages and consume them synchronously but may not consume them asynchronously.

Because a blocking synchronous receive ties up server resources, it is not a good programming practice to use such a receive call in a Web component. Instead, use a timed synchronous receive. For details about blocking and timed synchronous receives, see Section 4.2.1, "Writing the PTP Client Programs."

TOC | Prev | Next | Index

This Tutorial contains information on the 1.3.1 version of the Java 2 Platform, Enterprise Edition.

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.