| <?xml version="1.0"?> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| |
| <appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="JMS-Client-0-8-Appendix-Exceptions"> |
| <title>Exceptions</title> |
| |
| <para>The methods of the Client throw <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/JMSException.html">JMSExceptions</link> in response to error |
| conditions. Typically the exception's message (#getMessage()) summarises the error condition, |
| with contextual information being provided by the messages of linked exception(s). To understand |
| the problem, it is important to read the messages associated with <emphasis>all</emphasis> the |
| linked exceptions.</para> |
| |
| <para>The following table describes some of the more common exceptions linked to JMSException |
| thrown by JMS methods whilst using the client:</para> |
| |
| <table pgwide="1"> |
| <title>Exceptions linked to JMSExceptions thrown by JMS methods</title> |
| <tgroup cols="3"> |
| <thead> |
| <row> |
| <entry>Linked Exception</entry> |
| <entry>Message</entry> |
| <entry>Explanation/Common Causes</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>AMQUnresolvedAddressException</entry> |
| <entry><emphasis>message varies</emphasis></entry> |
| <entry><para>Indicates that the hostname included in the Connection URL's <link linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Brokerlist">brokerlist</link>, could not be resolved, . This could mean that the hostname is |
| mispelt, or there is name resolution problem.</para></entry> |
| </row> |
| <row> |
| <entry>AMQConnectionFailure</entry> |
| <entry>Connection refused</entry> |
| <entry><para>Indicates that the host included in the Connection URL's <link linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Brokerlist">brokerlist</link>, actively refused the connection. This could mean that the |
| hostname and/or port number is incorrect, or the Broker may not be |
| running.</para></entry> |
| </row> |
| <row> |
| <entry>AMQConnectionFailure</entry> |
| <entry>connect timed out</entry> |
| <entry><para>Indicates that the host included in the Connection URL's <link linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Brokerlist">brokerlist</link>, could not be contacted within the <link linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-ConnectTimeout">connecttimeout</link>. This could mean that the host is shutdown, or a networking |
| routing problem means the host is unreachable.</para></entry> |
| </row> |
| <row> |
| <entry>AMQConnectionFailure</entry> |
| <entry>General SSL Problem; PKIX path building failed; unable to find valid certification |
| path to requested target</entry> |
| <entry><para>Indicates that the CA that signed the Broker's certificate is not trusted by |
| the JVM of the client. If the Broker is using a private-CA (or a self signed |
| certificate) check that the client has been properly configured with a truststore. See |
| <xref linkend="JMS-Client-0-8-Client-Understanding-Connection-SSL"/></para></entry> |
| </row> |
| <row> |
| <entry>AMQConnectionFailure / AMQAuthenticationException</entry> |
| <entry>not allowed</entry> |
| <entry><para>Indicates that the user cannot be authenticated by the Broker. Check the |
| username and/or password elements within the <link linkend="JMS-Client-0-8-Connection-URL">Connection URL</link>.</para></entry> |
| </row> |
| <row> |
| <entry>AMQConnectionFailure / AMQSecurityException</entry> |
| <entry>Permission denied: <emphasis>virtualhost name</emphasis>; access refused</entry> |
| <entry><para>Indicates that the user is not authorised to connect to the given |
| virtualhost. The user is recognised by the Broker and is using the correct password |
| but does not have permission. This exception normally indicates that the user (or |
| group) has not been permissioned within the Broker's <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${qpidJavaBrokerBook}Java-Broker-Security-ACLs.html">Access Control List |
| (ACL)</link>.</para></entry> |
| </row> |
| <row> |
| <entry>AMQTimeoutException</entry> |
| <entry>The server's response was not received within the time-out period of %d ms.</entry> |
| <entry> |
| <para>Indicates that the Broker's response to the request sent by the client was not received |
| within a timely fashion. The timeout is governed by |
| <link linkend="JMS-Client-0-8-System-Properties-SyncOpTimeout"> |
| <literal>qpid.sync_op_timeout</literal> |
| </link>. |
| </para> |
| <para>This can be a symptom of a heavily loaded Broker, an overloaded network or a client JVM itself which |
| is too overloaded to process incoming responses. Check for unreasonably long garbage collection pauses. |
| </para> |
| </entry> |
| </row> |
| <row> |
| <entry>AMQSecurityException</entry> |
| <entry>Permission denied: <emphasis>message varies</emphasis></entry> |
| <entry><para>Indicates that the user is not authorised to use the given resource or |
| perform the given operation. This exception normally indicates that the user (or |
| group) has not been permissioned within the Broker's <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${qpidJavaBrokerBook}Java-Broker-Security-ACLs.html">Access Control List |
| (ACL)</link>.</para></entry> |
| </row> |
| <row xml:id="JMS-Client-0-8-Appendix-Exceptions-CertificateException"> |
| <entry>CertificateException</entry> |
| <entry>Unable to find certificate for recipient '<recipient>'</entry> |
| <entry> |
| <para>When using end to end message encryption, this exception indicates the the message recipent's |
| principal cannot be found in the truststore. See <xref linkend="JMS-Client-Message-Encryption"/> |
| </para> |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para>The following table describes some of the more common exceptions linked to JMSException sent |
| to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/ExceptionListener.html">ExceptionListener</link> |
| instances.</para> |
| |
| <table pgwide="1"> |
| <title>Exceptions linked to JMSExceptions received by ExceptionListeners</title> |
| <tgroup cols="3"> |
| <thead> |
| <row> |
| <entry>Linked Exception</entry> |
| <entry>Message</entry> |
| <entry>Explanation/Common Causes</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row xml:id="JMS-Client-0-8-Appendix-Exceptions-AMQNoRouteException"> |
| <entry>AMQNoRouteException</entry> |
| <entry>No Route for message [Exchange: <emphasis>exchange name</emphasis>, Routing key: |
| <emphasis>routing key</emphasis>] [error code 312: no route]</entry> |
| <entry><para>Indicate that the named exchange is unable to route a message to at least one |
| queue.</para> |
| <para>This will occur if a queue has been improperly bound to an exchange. Use the |
| Broker's management interface to check the bindings. See <xref linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-MandatoryMessage"/></para></entry> |
| </row> |
| <row xml:id="JMS-Client-0-8-Appendix-Exceptions-AMQNoConsumersException"> |
| <entry>AMQNoConsumersException</entry> |
| <entry>Immediate delivery is not possible. [error code 313: no consumers]</entry> |
| <entry><para>Immediate delivery was requested by the MessageProducer, but as there are no |
| consumers on any target queue, the message has been returned to the publisher. See |
| <xref linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-ImmediateMessage"/> |
| </para></entry> |
| </row> |
| <row> |
| <entry>AMQDisconnectedException</entry> |
| <entry>Server closed connection and reconnection not permitted</entry> |
| <entry><para>Indicates that the connection was closed by the Broker, and as <link linkend="JMS-Client-0-8-Client-Understanding-Connection-Failover">failover |
| options</link> are not included in the Connection URL, the client has been unable to |
| reestablish connection.</para> |
| <para>The Connection is now closed and any attempt to use either Connection object, or |
| any objects created from the Connection will receive an <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/IllegalStateException.html">IllegalStateException</link>.</para></entry> |
| </row> |
| <row xml:id="JMS-Client-0-8-Appendix-Exceptions-AMQDisconnectedException"> |
| <entry>AMQDisconnectedException</entry> |
| <entry>Server closed connection and no failover was successful</entry> |
| <entry><para>Indicates that the connection was closed by the Broker. The client has tried |
| failover according to the rules of the <link linkend="JMS-Client-0-8-Client-Understanding-Connection-Failover">failover |
| options</link>within the Connection URL, but these attempts were all |
| unsuccessful.</para> |
| <para>The Connection is now closed and any attempt to use either Connection object, or |
| any objects created from the Connection will receive an <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/IllegalStateException.html">IllegalStateException</link>.</para></entry> |
| </row> |
| |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <!-- |
| : |
| AMQDisconnectedException: Server closed connection |
| --> |
| |
| </appendix> |
