1. Using Oracle Messaging Cloud Service
  2. Best Practices
  3. Diagnosing Exceptions in the Java Library

Diagnosing Exceptions in the Java Library

The Oracle Messaging Cloud Service Java library provides support for diagnosing problems that are indicated by a JMSException (or subclass thereof) being thrown by an invocation of a Java library method or being dispatched to an ExceptionListener.

The Java library is an implementation of JMS 1.1. As such, the problem indicated by an exception can sometimes be inferred from the class of the exception. For example, if an invocation of the setClientID() method of the Connection class throws InvalidClientIDException, the JMS standard and Javadoc indicates that this may indicate that there may be an existing Connection with the same client ID. If you receive this exception, you should implement logic to check for and handle this case, or you should modify the application’s code to eliminate such a possibility.

In some cases, the JMS 1.1 specification may not define the problem indicated by an exception. This will be true, for example, if the exception thrown is of the generic class JMSException, or if the exception is a MessagingException thrown from a (non-JMS) method of the MessagingService interface. In such cases, Oracle Messaging Cloud Service may provide additional information about the problem behind the exception.

Subclasses of MessagingException for Specific Problems

In some cases, a non-JMS method may be declared to throw MessagingException, and documented to throw subclasses of MessagingException to indicate specific problems. When this is the case, it is documented in the Java library Javadocs.

Examples:

  • The createQueue() method of MessagingService creates a persistent queue with a particular name. It can throw a generic MessagingException, but it can also throw an exception of the DestinationExistsException subclass, which indicates that there is already a queue with the given name in the service instance.

  • The getTopicProperties() method of MessagingService returns information about a persistent topic with a particular name. It can throw a generic MessagingException, but it can also throw an exception of the DestinationNotFoundException subclass, which indicates that there is no topic with the given name in the service instance.

HttpResponseException

The Java library interacts with the Oracle Messaging Cloud Service as a client of the Oracle Messaging Cloud Service REST API. Thus, many of the exceptions thrown by the Java library are caused by receiving an HTTP error response from the REST API. HttpResponseException is a subclass of MessagingException that provides programmatic access to information provided by an HTTP error response received by the Java library. The Javadocs for this exception give full details. However, here are some key points to be noted:

  • The response code of the HTTP response from the REST API can be obtained by invoking the exception's getResponseCode() method. This is of particular interest because, if the response code is in the 400-499 range, this generally indicates a problem that the client code must correct, whereas a response code in the 400-499 range indicates a problem on the server side.

  • The error key in the HTTP response of the REST API (the errorCode part of the Oracle Messaging Cloud Service REST API error response) can be obtained as an ErrorKey object by invoking the exception's getErrorKey() method. If the return value of this method is not null, it will provide additional information beyond what is given by the the HTTP response code.

    Note: If getErrorKey() returns null, this indicates that the HTTP response received by the Java library was not generated by Oracle Messaging Cloud Service. In such cases, the response may have been generated by Oracle Cloud infrastructure, such as a load balancer, or it may even have come from some part of the user's infrastructure, such as an HTTP proxy. If getErrorKey() returns null, the content of the HTTP response may be examined to attempt to diagnose the problem.

  • The error message in the HTTP response of the REST API (the errorMessage part of the Oracle Messaging Cloud Service REST API error response) can be obtained by the getErrorMessage() method. The errorMessage generally contains additional information beyond what is given by the error key.

  • The exception message for HttpResponseException (that is, the return value of the standard getMessage() method) is the full HTTP response, including the status line, headers, and body of the error response. The error message text will be in the exception's message, but it will be embedded in the HTTP response with other information.

HttpResponseExceptions in Non-JMS Methods

When a MessagingException is thrown by a non-JMS method (e.g. the MessagingService methods), and its class is not one of the subclasses that indicate a specific problem, its class may be HttpResponseException. In such a case, it will contain the information alluded to in the previous section.

If a MessagingException is thrown whose class is not one of the problem-specific classes or HttpResponseException, it generally indicates that the exception was thrown purely on the client side. Users must not assume that a thrown MessagingException is an HttpResponseException if its class is not one of the problem-specific exception classes.

HttpResponseExceptions in JMS Methods

When a JMSException is thrown by the JMS part of the client library, if it's thrown because of an HTTP error response from Oracle Messaging Cloud Service, its cause (the value returned by the standard getCause() method) will be an HttpResponseException which can be used in the same way as above. Again, the cause must be checked to ensure that it's an HttpResponseException.