JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle GlassFish Server Message Queue 4.5 Developer's Guide for Java Clients
search filter icon
search icon

Document Information


1.  Overview

2.  Using the Java API

3.  Message Queue Clients: Design and Features

Client Design Considerations

Developing Portable Clients

Choosing Messaging Domains

Connections and Sessions

Producers and Consumers

Assigning Client Identifiers

Message Order and Priority

Using Selectors Efficiently

Balancing Reliability and Performance

Managing Client Threads

JMS Threading Restrictions

Thread Allocation for Connections

Managing Memory and Resources

Managing Memory

Managing Message Size

Message Compression

Advantages and Limitations of Compression

Compression Examples

Managing the Dead Message Queue

Managing Physical Destination Limits

Programming Issues for Message Consumers

Using the Client Runtime Ping Feature

Preventing Message Loss for Synchronous Consumers

Synchronous Consumption in Distributed Applications

Factors Affecting Performance

Delivery Mode (Persistent/Nonpersistent)

Use of Transactions

Acknowledgment Mode

Durable vs. Nondurable Subscriptions

Use of Selectors (Message Filtering)

Message Size

Message Body Type

Connection Event Notification

Connection Events

Creating an Event Listener

Event Listener Examples

Consumer Event Notification

Consumer Events

Creating a Consumer Event Listener

Consumer Event Listener Examples

Client Connection Failover (Auto-Reconnect)

Enabling Auto-Reconnect

Single-Broker Auto-Reconnect

Parallel Broker Auto-Reconnect

Clustered-Broker Auto-Reconnect

Auto-Reconnect Behaviors

Auto-Reconnect Limitations

Handling Exceptions When Failover Occurs

Handling Exceptions in a Transacted Session

Transacted Session: Failover Producer Example

Transacted Session: Failover Consumer Example

Handling Exceptions in a Non-Transacted Session

Failover Producer Example

Failover Consumer Example

Custom Client Acknowledgment

Using Client Acknowledge Mode

Using No Acknowledge Mode

Schema Validation of XML Payload Messages

Communicating with C Clients

Client Runtime Logging

Logging Name Spaces, Levels, and Activities

Using the JRE Logging Configuration File

Using a Logging Configuration File for a Specific Application

Setting the Logging Configuration Programmatically

4.  Using the Metrics Monitoring API

5.  Working with SOAP Messages

6.  Embedding a Message Queue Broker in a Java Client

A.  Warning Messages and Client Error Codes


Connection Event Notification

Connection event notifications allow a Message Queue client to listen for closure and reconnection events and to take appropriate action based on the notification type and the connection state. For example, when a failover occurs and the client is reconnected to another broker, an application might want to clean up its transaction state and proceed with a new transaction.

If the Message Queue provider detects a serious problem with a connection, it calls the connection object's registered exception listener. It does this by calling the listener's onException method, and passing it a JMSException argument describing the problem. In the same way, the Message Queue provider offers an event notification API that allows the client runtime to inform the application about connection state changes. The notification API is defined by the following elements:

The following sections describe the events that can trigger notification and explain how you can create an event listener.

Connection Events

The following table lists and describes the events that can be returned by the event listener.

Note that the JMS exception listener is not called when a connection event occurs. The exception listener is only called if the client runtime has exhausted its reconnection attempts. The client runtime always calls the event listener before the exception listener.

Table 3-5 Notification Events

Event Type
The Message Queue client runtime generates this event when it receives a notification from the broker that a connection is about to be closed due to a shutdown requested by the administrator.
The Message Queue client runtime generates this event when a connection is closed due to a broker error or when it is closed due to a shutdown or restart requested by the administrator.

When an event listener receives a ConnectionClosedEvent, the application can use the getEventCode() method of the received event to get an event code that specifies the cause for closure.

The Message Queue client runtime has reconnected to a broker. This could be the same broker to which the client was previously connected or a different broker.

An application can use the getBrokerAddress method of the received event to get the address of the broker to which it has been reconnected.

The Message Queue client runtime has failed to reconnect to a broker. Each time a reconnect attempt fails, the runtime generates a new event and delivers it to the event listener.

The JMS exception listener is not called when a connection event occurs. It is only called if the client runtime has exhausted its reconnection attempts. The client runtime always calls the event listener before the exception listener.

Creating an Event Listener

The following code example illustrates how you set a connection event listener. Whenever a connection event occurs, the event listener's onEvent method will be invoked by the client runtime.

//create an MQ connection factory.

com.sun.messaging.ConnectionFactory factory =
    new com.sun.messaging.ConnectionFactory();

//create an MQ connection.

com.sun.messaging.jms.Connection connection = 
    (com.sun.messaging.jms.Connection )factory.createConnection();

//construct an MQ event listener.  The listener implements 
//com.sun.messaging.jms.notification.EventListener interface.

com.sun.messaging.jms.notification.EventListener eListener = 
    new ApplicationEventListener();

//set event listener to the MQ connection.

connection.setEventListener ( eListener );

Event Listener Examples

In this example, an application chooses to have its event listener log the connection event to the application's logging system.

public class ApplicationEventListener implements
    com.sun.messaging.jms.notification.EventListener {

  public void onEvent ( com.sun.messaging.jms.notification.Event connEvent ) {
    log (connEvent);
  private void log ( com.sun.messaging.jms.notification.Event connEvent ) {
    String eventCode = connEvent.getEventCode(); 
    String eventMessage = connEvent.getEventMessage();
    //write event information to the output stream.