JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle GlassFish Server 3.1 Application Development Guide
search filter icon
search icon

Document Information


Part I Development Tasks and Tools

1.  Setting Up a Development Environment

2.  Class Loaders

3.  Debugging Applications

Part II Developing Applications and Application Components

4.  Securing Applications

5.  Developing Web Services

6.  Using the Java Persistence API

7.  Developing Web Applications

8.  Using Enterprise JavaBeans Technology

Value Added Features

Read-Only Beans

The pass-by-reference Element

Pooling and Caching

Pooling Parameters

Caching Parameters

Priority Based Scheduling of Remote Bean Invocations

Immediate Flushing

EJB Timer Service

To Deploy an EJB Timer to a Cluster

Using Session Beans

About the Session Bean Containers

Stateless Container

Stateful Container

Stateful Session Bean Failover

Choosing a Persistence Store

Enabling Checkpointing

Specifying Methods to Be Checkpointed

Session Bean Restrictions and Optimizations

Optimizing Session Bean Performance

Restricting Transactions

EJB Singletons

Using Read-Only Beans

Read-Only Bean Characteristics and Life Cycle

Read-Only Bean Good Practices

Refreshing Read-Only Beans

Invoking a Transactional Method

Refreshing Periodically

Refreshing Programmatically

Deploying Read-Only Beans

Using Message-Driven Beans

Message-Driven Bean Configuration

Connection Factory and Destination

Message-Driven Bean Pool

Domain-Level Settings

Message-Driven Bean Restrictions and Optimizations

Pool Tuning and Monitoring

The onMessage Runtime Exception

9.  Using Container-Managed Persistence

10.  Developing Java Clients

11.  Developing Connectors

12.  Developing Lifecycle Listeners

13.  Developing OSGi-enabled Java EE Applications

Part III Using Services and APIs

14.  Using the JDBC API for Database Access

15.  Using the Transaction Service

16.  Using the Java Naming and Directory Interface

17.  Using the Java Message Service

18.  Using the JavaMail API


Using Message-Driven Beans

This section describes message-driven beans and explains the requirements for creating them in the GlassFish Server environment.

The following topics are addressed here:

Message-Driven Bean Configuration

The following topics are addressed here:

For information about setting up load balancing for message-driven beans, see Load-Balanced Message Inflow.

Connection Factory and Destination

A message-driven bean is a client to a Connector inbound resource adapter. The message-driven bean container uses the JMS service integrated into the GlassFish 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 glassfish-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 glassfish-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 glassfish-ejb-jar.xml file contains the elements that define the pool (that is, the bean-pool element):

For more information about glassfish-ejb-jar.xml, see The glassfish-ejb-jar.xml File in Oracle GlassFish Server 3.1 Application Deployment Guide.

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 32.

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, click the Help button in the Administration Console. Select the Stand-Alone Instances component, select the instance from the table, and select the Monitor tab. Or select the Clusters component, select the cluster from the table, select the Instances tab, select the instance from the table, and select the Monitor tab.

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 Chapter 8, Administering the Monitoring Service, in Oracle GlassFish Server 3.1 Administration Guide.

Message-Driven Bean Restrictions and Optimizations

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

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 glassfish-ejb-jar.xml file). For example, you can tune the GlassFish Server 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 Chapter 8, Administering the Monitoring Service, in Oracle GlassFish Server 3.1 Administration Guide for information on how to get message-driven bean pool statistics.

The 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, v3.0 provides the following guidelines:

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 GlassFish 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. Here is an example asadmin set command that sets this property:

asadmin set"5"

For more information about the asadmin set command, see the Oracle GlassFish Server 3.1-3.1.1 Reference Manual.

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 is deprecated.