45.5.1 Creating Resources for Java EE Applications

You can use annotations to create application-specific connection factories and destinations for Java EE enterprise bean or web components. The resources you create in this way are visible only to the application for which you create them.

You can also use deployment descriptor elements to create these resources. Elements specified in the deployment descriptor override elements specified in annotations. See Packaging Applications for basic information about deployment descriptors. You must use a deployment descriptor to create application-specific resources for application clients.

To create a destination, use a @JMSDestinationDefinition annotation like the following on a class:

@JMSDestinationDefinition(
    name = "java:app/jms/myappTopic",
    interfaceName = "javax.jms.Topic",
    destinationName = "MyPhysicalAppTopic"
  )

The name, interfaceName, and destinationName elements are required. You can optionally specify a description element. To create multiple destinations, enclose them in a @JMSDestinationDefinitions annotation, separated by commas.

To create a connection factory, use a @JMSConnectionFactoryDefinition annotation like the following on a class:

@JMSConnectionFactoryDefinition(
    name="java:app/jms/MyConnectionFactory"
)

The name element is required. You can optionally specify a number of other elements, such as clientId if you want to use the connection factory for durable subscriptions, or description. If you do not specify the interfaceName element, the default interface is javax.jms.ConnectionFactory. To create multiple connection factories, enclose them in a @JMSConnectionFactoryDefinitions annotation, separated by commas.

You need to specify the annotation only once for a given application, in any of the components.

When you inject the resource into a component, use the value of the name element in the definition annotation as the value of the lookup element in the @Resource annotation:

@Resource(lookup = "java:app/jms/myappTopic")
private Topic topic;

The following portable JNDI namespaces are available. Which ones you can use depends on how your application is packaged.

• java:global: Makes the resource available to all deployed applications

• java:app: Makes the resource available to all components in all modules in a single application

• java:module: Makes the resource available to all components within a given module (for example, all enterprise beans within an EJB module)

• java:comp: Makes the resource available to a single component only (except in a web application, where it is equivalent to java:module)

See the API documentation for details on these annotations. The examples in Sending and Receiving Messages Using a Simple Web Application, Sending Messages from a Session Bean to an MDB, and Using an Entity to Join Messages from Two MDBs all use the @JMSDestinationDefinition annotation. The other JMS examples do not use these annotations. The examples that consist only of application clients are not deployed in the application server and must therefore communicate with each other using administratively created resources that exist outside of individual applications.

45.5.2 Using Resource Injection in Enterprise Bean or Web Components

You may use resource injection to inject both administered objects and JMSContext objects in Java EE applications.

@Resource(lookup = "java:comp/DefaultJMSConnectionFactory")
private static ConnectionFactory connectionFactory;

@Resource(lookup = "jms/MyQueue")
private static Queue queue;

@Resource(lookup = "java:comp/DefaultJMSConnectionFactory")
private ConnectionFactory connectionFactory;

@Resource(lookup = "jms/MyTopic")
private Topic topic;

@Inject
private JMSContext context1;

@Inject
@JMSConnectionFactory("jms/MyConnectionFactory")
private JMSContext context2;

45.5.3 Using Java EE Components to Produce and to Synchronously Receive Messages

An application that produces messages or synchronously receives them can use a Java EE web or EJB component, such as a managed bean, a servlet, or a session bean, to perform these operations. The example in Sending Messages from a Session Bean to an MDB uses a stateless session bean to send messages to a topic. The example in Sending and Receiving Messages Using a Simple Web Application uses managed beans to produce and to consume messages.

Because a synchronous receive with no specified timeout ties up server resources, this mechanism usually is not the best application design for a web or EJB component. Instead, use a synchronous receive that specifies a timeout value, or use a message-driven bean to receive messages asynchronously. For details about synchronous receives, see JMS Message Consumers.

Using the JMS API in a Java EE component is in many ways similar to using it in an application client. The main differences are the areas of resource management and transactions.

45.5.4 Using Message-Driven Beans to Receive Messages Asynchronously

The sections What Is a Message-Driven Bean? and How Does the JMS API Work with the Java EE Platform? describe how the Java EE platform supports a special kind of enterprise bean, the message-driven bean, which allows Java EE applications to process JMS messages asynchronously. Other Java EE web and EJB components allow you to send messages and to receive them synchronously but not asynchronously.

A message-driven bean is a message listener to which messages can be delivered from either a queue or a topic. The messages can be sent by any Java EE component (from an application client, another enterprise bean, or a web component) or from an application or a system that does not use Java EE technology.

A message-driven bean class has the following requirements.

• It must be annotated with the @MessageDriven annotation if it does not use a deployment descriptor.

• The class must be defined as public, but not as abstract or final.

• It must contain a public constructor with no arguments.

It is recommended, but not required, that a message-driven bean class implement the message listener interface for the message type it supports. A bean that supports the JMS API implements the javax.jms.MessageListener interface, which means that it must provide an onMessage method with the following signature:

void onMessage(Message inMessage)

The onMessage method is called by the bean's container when a message has arrived for the bean to service. This method contains the business logic that handles the processing of the message. It is the message-driven bean's responsibility to parse the message and perform the necessary business logic.

A message-driven bean differs from an application client's message listener in the following ways.

• In an application client, you must create a JMSContext, then create a JMSConsumer, then call setMessageListener to activate the listener. For a message-driven bean, you need only define the class and annotate it, and the EJB container creates it for you.

• The bean class uses the @MessageDriven annotation, which typically contains an activationConfig element containing @ActivationConfigProperty annotations that specify properties used by the bean or the connection factory. These properties can include the connection factory, a destination type, a durable subscription, a message selector, or an acknowledgment mode. Some of the examples in Chapter 46, "Java Message Service Examples" set these properties. You can also set the properties in the deployment descriptor.

• The application client container has only one instance of a MessageListener, which is called on a single thread at a time. A message-driven bean, however, may have multiple instances, configured by the container, which may be called concurrently by multiple threads (although each instance is called by only one thread at a time). Message-driven beans may therefore allow much faster processing of messages than message listeners.

• You do not need to specify a message acknowledgment mode unless you use bean-managed transactions. The message is consumed in the transaction in which the onMessage method is invoked.

Table 45-3 lists the activation configuration properties defined by the JMS specification.

For example, here is the message-driven bean used in Receiving Messages Asynchronously Using a Message-Driven Bean:

@MessageDriven(activationConfig = {
    @ActivationConfigProperty(propertyName = "destinationLookup",
            propertyValue = "jms/MyQueue"),
    @ActivationConfigProperty(propertyName = "destinationType",
            propertyValue = "javax.jms.Queue")
})
public class SimpleMessageBean implements MessageListener {

    @Resource
    private MessageDrivenContext mdc;
    static final Logger logger = Logger.getLogger("SimpleMessageBean");

    public SimpleMessageBean() {
    }

    @Override
    public void onMessage(Message inMessage) {

        try {
            if (inMessage instanceof TextMessage) {
                logger.log(Level.INFO,
                        "MESSAGE BEAN: Message received: {0}",
                        inMessage.getBody(String.class));
            } else {
                logger.log(Level.WARNING,
                        "Message of wrong type: {0}",
                        inMessage.getClass().getName());
            }
        } catch (JMSException e) {
            logger.log(Level.SEVERE,
                    "SimpleMessageBean.onMessage: JMSException: {0}",
                    e.toString());
            mdc.setRollbackOnly();
        }
    }
}

If JMS is integrated with the application server using a resource adapter, the JMS resource adapter handles these tasks for the EJB container.

The bean class commonly injects a MessageDrivenContext resource, which provides some additional methods you can use for transaction management (setRollbackOnly, for example):

    @Resource
    private MessageDrivenContext mdc;

A message-driven bean never has a local or remote interface. Instead, 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, 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. The container attempts to deliver messages in chronological order when that would not impair the concurrency of message processing, but no guarantees are made as to the exact order in which messages are delivered to the instances of the message-driven bean class. If message order is essential to your application, you may want to configure your application server to use just one instance of the message-driven bean.

For details on the lifecycle of a message-driven bean, see The Lifecycle of a Message-Driven Bean.

45.5.5 Managing JTA Transactions

Java EE application clients and Java SE clients use JMS local transactions (described in Using JMS Local Transactions), which allow the grouping of sends and receives within a specific JMS session. Java EE applications that run in the web or EJB container commonly use JTA transactions to ensure the integrity of accesses to external resources. The key difference between a JTA transaction and a JMS local transaction is that a JTA transaction is controlled by the application server's transaction managers. JTA transactions may be distributed, which means that they can encompass multiple resources in the same transaction, such as a JMS provider and a database.

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 Java EE 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 can 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.

JTA transactions within the EJB and web containers can be either of two kinds.

• Container-managed transactions: The container controls the integrity of your transactions without your having to call commit or rollback. Container-managed transactions are easier to use than bean-managed transactions. You can specify appropriate transaction attributes for your enterprise bean methods.

  Use the Required transaction attribute (the default) to ensure that a method is always part of a transaction. If a transaction is in progress when the method is called, the method will be part of that transaction; if not, a new transaction will be started before the method is called and will be committed when the method returns. See Transaction Attributes for more information.

• Bean-managed transactions: You can use these in conjunction with the javax.transaction.UserTransaction interface, which provides its own commit and rollback methods you can use to delimit transaction boundaries. Bean-managed transactions are recommended only for those who are experienced in programming transactions.

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 use the Required transaction attribute (the default) for the onMessage method.

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

• setRollbackOnly: Use this method for error handling. If an exception occurs, setRollbackOnly marks the current transaction so that the only possible outcome of the transaction is a rollback.

• getRollbackOnly: Use this method to test whether the current transaction has been marked for rollback.

If you use bean-managed transactions, the delivery of a message to the onMessage method takes place outside the JTA transaction context. The transaction begins when you call the UserTransaction.begin method within the onMessage method, and it ends when you call UserTransaction.commit or UserTransaction.rollback. Any call to the Connection.createSession method must take place within the transaction.

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. However, if you use container-managed transactions, the message is received by the MDB and processed by the onMessage method within the same transaction. It is not possible to achieve this behavior with bean-managed transactions.

When you create a JMSContext in a JTA transaction (in the web or EJB container), the container ignores any arguments you specify, because it manages all transactional properties. When you create a JMSContext in the web or EJB container and there is no JTA transaction, the value (if any) passed to the createContext method should be JMSContext.AUTO_ACKNOWLEDGE or JMSContext.DUPS_OK_ACKNOWLEDGE.

When you use container-managed transactions, you normally use the Required transaction attribute (the default) for your enterprise bean's business methods.

You do not specify the activation configuration property acknowledgeMode 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. You can set the activation configuration property acknowledgeMode to Auto-acknowledge or Dups-ok-acknowledge to specify how you want the message received by the message-driven bean to be acknowledged.

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.