Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Using Read-Only Beans
- Next: Handling Transactions with Enterprise Beans

# Using Message-Driven Beans

This section describes message-driven beans and explains the requirements for creating them in the Application Server environment. This section contains the following topics:

- Message-Driven Bean Configuration

- Restrictions and Optimizations

- Sample Message-Driven Bean XML Files

## Message-Driven Bean Configuration

This section addresses the following configuration topics:

- Using Session Beans

- Message-Driven Bean Pool

- Domain-Level Settings

### Connection Factory and Destination

A message-driven bean is a client to a Connector 1.5 inbound resource adapter. The message-driven bean container uses the JMS service integrated into the Application Server for message-driven beans that are JMS clients. JMS clients use JMS Connection Factory- and Destination-administered objects. A JMS Connection Factory administered object is a resource manager Connection Factory object that is used to create connections to the JMS provider.

The `mdb-connection-factory` element in the `sun-ejb-jar.xml`file for a message-driven bean specifies the connection factory that creates the container connection to the JMS provider.

The `jndi-name` element of the `ejb` element in the `sun-ejb-jar.xml` file specifies the JNDI name of the administered object for the JMS `Queue` or `Topic` destination that is associated with the message-driven bean.

### Message-Driven Bean Pool

The container manages a pool of message-driven beans for the concurrent processing of a stream of messages. The `sun-ejb-jar.xml` file contains the elements that define the pool (that is, the `bean-pool` element):

- `steady-pool-size`

- `resize-quantity`

- `max-pool-size`

- `pool-idle-timeout-in-seconds`

For more information about `sun-ejb-jar.xml`, see The sun-ejb-jar.xml File.

### Domain-Level Settings

You can control the following domain-level message-driven bean settings in the EJB container:

- Initial and Minimum Pool Size - Specifies the initial and minimum number of beans maintained in the pool. The default is `0`.

- Maximum Pool Size - Specifies the maximum number of beans that can be created to satisfy client requests. The default is 3`2`.

- Pool Resize Quantity - Specifies the number of beans to be created if a request arrives when the pool is empty (subject to the Initial and Minimum Pool Size), or the number of beans to remove if idle for more than the Idle Timeout. The default is `8`.

- Idle Timeout - Specifies the maximum time in seconds that a bean can remain idle in the pool. After this amount of time, the bean is destroyed. The default is `600` (10 minutes). A value of `0` means a bean can remain idle indefinitely.

For information on monitoring message-driven beans, see the Application Server Administration Console online help and the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

Note –

Running monitoring when it is not needed might impact performance, so you might choose to turn monitoring off when it is not in use. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

## Restrictions and Optimizations

This section discusses the following restrictions and performance optimizations that pertain to developing message-driven beans:

- Pool Tuning and Monitoring

- onMessage Runtime Exception

### Pool Tuning and Monitoring

The message-driven bean pool is also a pool of threads, with each message-driven bean instance in the pool associating with a server session, and each server session associating with a thread. Therefore, a large pool size also means a high number of threads, which impacts performance and server resources.

When configuring message-driven bean pool properties, make sure to consider factors such as message arrival rate and pattern, `onMessage` method processing time, overall server resources (threads, memory, and so on), and any concurrency requirements and limitations from other resources that the message-driven bean accesses.

When tuning performance and resource usage, make sure to consider potential JMS provider properties for the connection factory used by the container (the `mdb-connection-factory` element in the `sun-ejb-jar.xml` file). For example, you can tune the Sun Java System Message Queue flow control related properties for connection factory in situations where the message incoming rate is much higher than `max-pool-size` can handle.

Refer to the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide for information on how to get message-driven bean pool statistics.

### onMessage Runtime Exception

Message-driven beans, like other well-behaved MessageListeners, should not, in general, throw runtime exceptions. If a message-driven bean’s `onMessage` method encounters a system-level exception or error that does not allow the method to successfully complete, the Enterprise JavaBeans Specification, v2.1 provides the following guidelines:

- If the bean method encounters a runtime exception or error, it should simply propagate the error from the bean method to the container.

- If the bean method performs an operation that results in a checked exception that the bean method cannot recover, the bean method should throw the `javax.ejb.EJBException` that wraps the original exception.

- Any other unexpected error conditions should be reported using `javax.ejb.EJBException` (`javax.ejb.EJBException` is a subclass of `java.lang.RuntimeException`).

Under container-managed transaction demarcation, upon receiving a runtime exception from a message-driven bean’s `onMessage` method, the container rolls back the container-started transaction and the message is redelivered. This is because the message delivery itself is part of the container-started transaction. By default, the Application Server container closes the container’s connection to the JMS provider when the first runtime exception is received from a message-driven bean instance’s `onMessage` method. This avoids potential message redelivery looping and protects server resources if the message-driven bean’s `onMessage` method continues misbehaving. To change this default container behavior, use the `cmt-max-runtime-exceptions` property of the `mdb-container` element in the `domain.xml` file.

The `cmt-max-runtime-exceptions` property specifies the maximum number of runtime exceptions allowed from a message-driven bean’s `onMessage` method before the container starts to close the container’s connection to the message source. By default this value is 1; -1 disables this container protection.

A message-driven bean’s `onMessage` method can use the `javax.jms.Message` `getJMSRedelivered` method to check whether a received message is a redelivered message.

Note –

The `cmt-max-runtime-exceptions` property might be deprecated in the future.

## Sample Message-Driven Bean XML Files

This section includes the following sample files:

- Sample ejb-jar.xml File

- Sample sun-ejb-jar.xml File

For general information on the `sun-ejb-jar.xml` file, see The sun-ejb-jar.xml File.

### Sample ejb-jar.xml File

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans
    2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>
    <ejb-jar>
    <enterprise-beans>
    	<message-driven>
    		<ejb-name>MessageBean</ejb-name>
    		<ejb-class>samples.mdb.ejb.MessageBean</ejb-class>
    		<transaction-type>Container</transaction-type>
    		<message-driven-destination>
    			<destination-type>javax.jms.Queue</destination-type>
    		</message-driven-destination>
    		<resource-ref>
    			<res-ref-name>jms/QueueConnectionFactory</res-ref-name>
    			<res-type>javax.jms.QueueConnectionFactory</res-type>
    			<res-auth>Container</res-auth>
    		</resource-ref>
    	</message-driven>
    </enterprise-beans>
    	<assembly-descriptor>
    		<container-transaction>
    			<method>
    				<ejb-name>MessageBean</ejb-name>
    				<method-intf>Bean</method-intf>
    				<method-name>onMessage</method-name>
    				<method-params>
    					<method-param>javax.jms.Message</method-param>
    				</method-params>
    			</method>
    		<trans-attribute>NotSupported</trans-attribute>
    	</container-transaction>
    </assembly-descriptor
    </ejb-jar>

### Sample sun-ejb-jar.xml File

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE sun-ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Application
    Server 8.1 EJB 2.1//EN'
    'http://www.sun.com/software/appserver/dtds/sun-ejb-jar_2_1-1.dtd'>
    <sun-ejb-jar>
    <enterprise-beans>
    	<ejb>
    		<ejb-name>MessageBean</ejb-name>
    		<jndi-name>jms/sample/Queue</jndi-name>
    		<resource-ref>
    			<res-ref-name>jms/QueueConnectionFactory</res-ref-name>
    			<jndi-name>jms/sample/QueueConnectionFactory</jndi-name>
    			<default-resource-principal>
    				<name>guest</name>
    				<password>guest</password>
    			</default-resource-principal>
    		</resource-ref>
    		<mdb-connection-factory>
    			<jndi-name>jms/sample/QueueConnectionFactory</jndi-name>
    			<default-resource-principal>
    				<name>guest</name>
    				<password>guest</password>
    			</default-resource-principal>
    		</mdb-connection-factory>
    	</ejb>
    </enterprise-beans>
    </sun-ejb-jar>

- Previous: Using Read-Only Beans
- Next: Handling Transactions with Enterprise Beans

- © 2010, Oracle Corporation and/or its affiliates