JMS - Exceptions

The JMSException

JMS defines JMSException as the root class for exceptions thrown by JMS methods. JMSException is a checked exception and catching it provides a generic way of handling all JMS related exceptions. JMSException provides the following information:

• A provider-specific string describing the error - This string is the standard Java exception message, and is available via getMessage() .
• A provider-specific string error code
• A reference to another exception - Often a JMS exception will be the result of a lower level problem. If appropriate, this lower level exception can be linked to the JMS exception.

JMS methods include only JMSException in their signatures. JMS methods can throw any JMS standard exception as well as any JMS provider-specific exception. The javadoc for JMS methods documents only the mandatory exception cases.

Standard Exceptions

In addition to JMSException, JMS defines several additional exceptions that standardize the reporting of basic error conditions. There are only a few cases where JMS mandates that a specific JMS exception must be thrown. These cases are indicated by the words must be in the exception description. These cases are the only ones on which client logic should depend on a specific problem resulting in a specific JMS exception being thrown.

In the remainder of cases, it is strongly suggested that JMS providers use one of the standard exceptions where possible. JMS providers may also derive provider-specific exceptions from these if needed.

JMS defines the following standard exceptions:

• IllegalStateException: This exception is thrown when a method is invoked at an illegal or inappropriate time or if the provider is not in an appropriate state for the requested operation. For example, this exception must be thrown if Session.commit()  is called on a non-transacted session. This exception is also must be called when domain inappropriate method is called, such as calling TopicSession.CreateQueueBrowser() .
• JMSSecurityException: This exception must be thrown when a provider rejects a user name/password submitted by a client. It may also be thrown for any case where a security restriction prevents a method from completing.
• InvalidClientIDException: This exception must be thrown when a client attempts to set a connection’s client identifier to a value that is rejected by a provider.
• InvalidDestinationException: This exception must be thrown when a destination is either not understood by a provider or is no longer valid.
• InvalidSelectorException: This exception must be thrown when a JMS client attempts to give a provider a message selector with invalid syntax.
• MessageEOFException: This exception must be thrown when an unexpected end of stream has been reached when a StreamMessage or BytesMessage is being read.

• MessageFormatException: This exception must be thrown when a JMS client attempts to use a data type not supported by a message or attempts to read data in a message as the wrong type. It must also be thrown when equivalent type errors are made with message property values. For example, this exception must be thrown if StreamMessage.writeObject() is given an unsupported class or if StreamMessage.readShort() is used to read a boolean value. This exception also must be thrown if a provider is given a type of
  message it cannot accept. Note that the special case of a failure caused by attempting to read improperly formatted String data as numeric values must throw the java.lang.NumberFormatException.

• MessageNotReadableException: This exception must be thrown when a JMS client attempts to read a write-only message.
• MessageNotWriteableException: This exception must be thrown when a JMS client attempts to write to a read-only message.
• ResourceAllocationException: This exception is thrown when a provider is unable to allocate the resources required by a method. For example, this exception should be thrown when a call to createTopicConnection fails due to lack of JMS provider resources.
• TransactionInProgressException: This exception is thrown when an operation is invalid because a transaction is in progress. For instance, attempting to call Session.commit()  when a session is part of a distributed transaction should throw a TransactionInProgressException.
• TransactionRolledBackException: This exception must be thrown when a call to Session.commit results in a rollback of the current transaction.