Exceptions in IBM MQ classes for JMS

For example, if an application specifies an incorrect port number when connecting to a queue manager, the exceptions form the following chain:

com.ibm.msg.client.jms.DetailIllegalStateException
   |
   +--->com.ibm.mq.MQException
           |
           +--->com.ibm.mq.jmqi.JmqiException
                   |
                   +--->java.net.ConnectionException

Typically, each exception in a chain is thrown from a different layer in the code. For example, the exceptions in the preceding chain are thrown by the following layers:

• The first exception, an instance of a subclass of JMSException, is thrown by the common layer in IBM MQ classes for JMS.
• The next exception, an instance of com.ibm.mq.MQException, is thrown by the IBM MQ messaging provider.
• The next exception, an instance of com.ibm.mq.jmqi.JmqiException, is thrown by the common Java interface to the MQI.
• The final exception, an instance of java.net.ConnectionException, is thrown by the Java class library.

For more information about the layered architecture of IBM MQ classes for JMS, see IBM MQ classes for JMS architecture.

Using code similar to the following code, an application can iterate through this chain to extract all the appropriate information:

import com.ibm.msg.client.jms.JmsExceptionDetail;
import com.ibm.mq.MQException;
import com.ibm.mq.jmqi.JmqiException;
import javax.jms.JMSException;
.
.
.
catch (JMSException je) {
    System.err.println("Caught JMSException");

    // Check for linked exceptions in JMSException
    Throwable t = je;
    while (t != null) {
        // Write out the message that is applicable to all exceptions
        System.err.println("Exception Msg: " + t.getMessage());
        // Write out the exception stack trace
        t.printStackTrace(System.err);

        // Add on specific information depending on the type of exception
        if (t instanceof JMSException) {
            JMSException je1 = (JMSException) t;
            System.err.println("JMS Error code: " + je1.getErrorCode());

            if (t instanceof JmsExceptionDetail){
                JmsExceptionDetail jed = (JmsExceptionDetail)je1;
                System.err.println("JMS Explanation: " + jed.getExplanation());
                System.err.println("JMS Explanation: " + jed.getUserAction());
            }
        } else if (t instanceof MQException) {
            MQException mqe = (MQException) t;
            System.err.println("WMQ Completion code: " + mqe.getCompCode());
            System.err.println("WMQ Reason code: " + mqe.getReason());
        } else if (t instanceof JmqiException){
            JmqiException jmqie = (JmqiException)t;
            System.err.println("WMQ Log Message: " + jmqie.getWmqLogMessage());
            System.err.println("WMQ Explanation: " + jmqie.getWmqMsgExplanation());
            System.err.println("WMQ Msg Summary: " + jmqie.getWmqMsgSummary());
            System.err.println("WMQ Msg User Response: "
                               + jmqie.getWmqMsgUserResponse());
            System.err.println("WMQ Msg Severity: " + jmqie.getWmqMsgSeverity());
        }

        // Get the next cause
        t = t.getCause();
    }
}

Note that an application should always check the type of each exception in a chain because the type of exception can vary and exceptions of different types encapsulate different information.

An MQException exception encapsulates the following information:

• A completion code, which an application obtains by calling the getCompCode() method
• A reason code, which an application obtains by calling the getReason() method

For example, if an application tries to connect to a queue manager that does not exist, a previous version of IBM MQ classes for JMS threw a JMSException exception with the following information:

MQJMS2005: Failed to create MQQueueManager for 'localhost:QM_test'.

This exception contained a linked MQException exception with the following information:

MQJE001: Completion Code 2, Reason 2058

By comparison in the same circumstances, Version 7.0 of IBM MQ classes for JMS throws a JMSException exception with the following information:

Message : JMSWMQ0018: Failed to connect to queue manager 'QM_test' with
          connection mode 'Client' and host name 'localhost'.
Class : class com.ibm.msg.client.jms.DetailedJMSException
Error Code : JMSWMQ0018
Explanation : null
User Action : Check the queue manager is started and if running in client mode,
              check there is a listener running. Please see the linked exception
              for more information.

This exception contains a linked MQException exception with the following information:

Message : JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED')
          reason '2058' ('MQRC_Q_MGR_NAME_ERROR').
Class : class com.ibm.mq.MQException
Completion Code : 2
Reason Code : 2058

APAR IT14820, included from IBM MQ 8.0.0, Fix Pack 6, updates IBM MQ classes for JMS so that:

• An ExceptionListener registered by an application is invoked for any connection broken exceptions, regardless of whether the application is using synchronous or asynchronous message consumers.
• An ExceptionListener registered by an application is invoked if a TCP/IP socket used by a JMS Session is broken.
• Non-connection broken exceptions (for example MQRC_GET_INHIBITED) that arise during message delivery are delivered to an application's ExceptionListener when the application is using asynchronous message consumers and the JMS ConnectionFactory used by the application has the ASYNC_EXCEPTIONS property set to the value ASYNC_EXCEPTIONS_ALL.