JMS ExceptionListener in WebSphere MQ

Answer

As per the JMS specification, if a JMS provider detects a problem with a connection, it informs the connection’s ExceptionListener, if one has been registered. This lets a JMS client get asynchronous notification of a connection problem. Some connections only consume messages, so they have no other way to learn their connection has failed. The exceptions delivered to an ExceptionListener are those that are not reported anywhere else.

Note: The JMS specification states that, if an exception is thrown on a JMS call, it must not be delivered to an ExceptionListener (in other words, the ExceptionListener is not for the purpose of monitoring all exceptions thrown by a connection).

With reference to the above JMS specification, this technote explains how the JMS ExceptionListener is implemented and handled by WebSphere MQ.

Implementation of JMS ExceptionListener in WebSphere MQ v5.3 and v6

The earlier releases of WebSphere MQ v5.3 (prior to CSD13) and WebSphere MQ v6 (prior to Fix Pack 6.0.2.0) partially implemented the ExceptionListener functionality. The earlier implementation interpreted the definition of the ExceptionListener in such a way that only asynchronous consumers were told about connection problems.

As per the JMS specification; when an ExceptionListener is registered with a connection, then any connection broken exceptions should be reported to the ExceptionListener (if one has been registered). Prior to WebSphere MQ v5.3 CSD13 and WebSphere MQ v6.0.2.0, connection broken exceptions were only delivered to the Exception Listener in the case of Asynchronous delivery. In case of Synchronous calls, even if an ExceptionListener was registered, connection broken exceptions were not delivered to it.

APAR IY81774 (WebSphere MQ as JMS provider NOT adhering to JMS Specifications as per Section "4.3.8 ExceptionListener") added enhancements so that WebSphere MQ implemented the ExceptionListener functionality as stated in the JMS specification. With these enhancements, if an ExceptionListener is registered on a connection, then all connection broken exceptions are delivered to the ExceptionListener through its onException() method, whether the JMS application uses Asynchronous or Synchronous consumers, or Message producers.

APAR IY81774 is included in WebSphere MQ 5.3 CSD 13 and WebSphere MQ 6.0.2.0. The rest of this technote provides more information about it, including how to enable the above behavior for WebSphere MQ v5.3 and v6.0. It also provides a list of the WebSphere MQ error codes that map to a broken connection exception.

The enhancements made to the WebSphere MQ JMS layer through APAR IY81774 ensure that WebSphere MQ implements the ExceptionListener functionality as stated in the JMS specification. However, even with these enhancements there is a difference between how the ExceptionListener is triggered when used with MessageConsumers and MessageProducers. The difference is as follows:

• ExceptionListener when used with MessageConsumers (Asynchronous or Synchronous):

When MessageConsumers use a connection on which the ExceptionListener is registered, if any connection failure occurs on this connection, then the connection broken exception is immediately propagated to the ExceptionListener’s onException method. The triggering of the onException method happens internally from within the WebSphere MQ JMS layer without the application having to make any additional JMS calls.

• ExceptionListener when used with MessageProducers:

When MessageProducers use a connection on which an ExceptionListener is registered, if any connection failure occurs on this connection, then the connection broken exception is NOT immediately propagated to the ExceptionListener’s onException method. The triggering of the onException() method happens only when the application makes an additional JMS call (such as producer.send() ). The ExceptionListener is not triggered immediately, as it is with MessageConsumers.

Implementation of JMS ExceptionListener in WebSphere MQ v7.0 and later

The implementation in WebSphere MQ v7.0 and later takes things a step further, and delivers connection broken exceptions to an ExceptionListener immediately for the MessageProducers (similarly as handled with the MessageConsumers).

The changes to WebSphere MQ v7 are as follows:

• The ExceptionListener is only notified of exceptions indicating a connection failure, such as a loss of network connectivity to a messaging server, and not other exceptions such as the asynchronous receipt of unreadable messages
• The ExceptionListener is notified of all such ‘connection broken’ exceptions, even if these same exceptions are also thrown back to the application as a result of a failed call from the application on the JMS provider, such as a failed MessageProducer.send call.

WebSphere MQ v7, when working over a TCP/IP connection, can learn more quickly of connection failures. This uses the Share Conversations feature introduced in WebSphere MQ v7, and requires the client to work in WMQ Provider Normal Mode. You can configure the channel not to use this feature; in that case the client works in WMQ Provider Migration Mode and the exception listener functions as it did in WMQ v6.

For more details see: Rules for selecting the WebSphere MQ messaging provider mode

Sample Code snippet on the usage of ExceptionListener

Implementing an ExceptionListener is very much equivalent to using a MessageListener. An Exception Listener is called when a problem prevents delivery of a message, a situation that cannot be detected by a Message Listener. To create an ExceptionListener follow the steps outlined below:

1) Create a class that implements javax.jms.ExceptionListener
public class MyClass implements MessageListener, ExceptionListener {
....
....
}

2) Provide an onException method (as shown below)

public void onException(JMSException exception){
System.err.println("something went wrong : " + exception);
}

3) Register the exception listener with the connection by calling setExceptionListener on the connection object.

connection.setExceptionListener(this); // class implementing the ExceptionListener interface