QPID-5374: [Documentation] Add chapters describing client logging and exceptions.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1554547 13f79535-47bb-0310-9956-ffa450edef68

9 files changed, 276 insertions, 94 deletions

diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml
new file mode 100644
index 0000000000..eb021f3132
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml
@@ -0,0 +1,173 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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 id="JMS-Client-0-8-Appendix-Exceptions">
+  <title>Exceptions</title>
+
+  <para>The methods of Qpid JMS Client throw <ulink url="&oracleJeeDocUrl;javax/jms/JMSException.html"
+      >JMSExceptions</ulink> 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>AMQTimeoutException</entry>
+          <entry>Server did not respond in a timely fashion; Request Timeout</entry>
+          <entry><para>Indicates that the broker did not respond to a request sent by the client in
+              a reasonable length of time. 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 that cannot respond or the Broker may have failed in
+              unexpected manner. Check the broker and the host on which it runs and performance of
+              its storage.</para></entry>
+        </row>
+      </tbody>
+    </tgroup>
+  </table>
+
+  <para>The following table describes some of the more common exceptions linked to JMSException sent
+    to <ulink url="&oracleJeeDocUrl;javax/jmx/ExceptionListener.html">ExceptionListener</ulink>
+    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 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 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 <ulink
+                url="&oracleJeeDocUrl;javax/jms/IllegalStateException.html"
+                >IllegalStateException</ulink>.</para></entry>
+        </row>
+        <row 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 <ulink
+                url="&oracleJeeDocUrl;javax/jms/IllegalStateException.html"
+                >IllegalStateException</ulink>.</para></entry>
+        </row>
+
+      </tbody>
+    </tgroup>
+  </table>
+
+  <!--
+  : 
+  AMQDisconnectedException: Server closed connection 
+  -->
+
+</appendix>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
index c433d459b5..956981ecdc 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
@@ -35,12 +35,12 @@
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Connection-URL.xml"/>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Binding-URL.xml"/>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-System-Properties.xml"/>
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Turning-On-Logging.xml"/>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Logging.xml"/>
 
     <!-- TODO:
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Interoperability.xml"/>
     -->
-   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Exceptions.xml"/>
+   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-Exceptions.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-Maven.xml"/>
  
  
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
index b435abe065..09ad985368 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
@@ -56,7 +56,7 @@
 				</row>
 			</thead>
 			<tbody>
-				<row>
+				<row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-Brokerlist">
 					<entry> brokerlist </entry>
 					<entry> see below </entry>
 					<entry> List of one or more broker addresses. </entry>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
index 13b30b0e05..d4b88f61d2 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
@@ -37,11 +37,10 @@
     client. The specifications for these protocols is available from the <ulink
       url="http://www.amqp.org">AMQP web site</ulink>. </para>
 
-  <para>
-    The document covers some specific implementation details of JMS connections, sessions, consumers and producers
-    in <xref linkend="JMS-Client-0-8-Client-Understanding"/>. It also demonstrates how to write a simple
-    point to point and simple publish/subscribe application using Qpid JMS Client in <xref linkend="JMS-Client-0-8-Examples"/>. 
-  </para>
+  <para> The document covers some specific implementation details of JMS connections, sessions,
+    consumers and producers in <xref linkend="JMS-Client-0-8-Client-Understanding"/>. It also
+    demonstrates how to write a simple point to point and simple publish/subscribe application using
+    Qpid JMS Client in <xref linkend="JMS-Client-0-8-Examples"/>. </para>
 
   <para>The Qpid JMS Client supports various configuration options which can be set via JVM system
     properties, connection URLs and JNDI configuration file. The setting of system properties is
@@ -56,10 +55,10 @@
     provides the extended operation set to invoke those features. </para>
 
   <para>
-    <xref linkend="JMS-Client-0-8-Turning-On-Logging"/> provides the details about turning on client logging
-    which can help in debugging of various issues while developing the messaging applications.
-  </para>
+    <xref linkend="JMS-Client-0-8-Logging"/> provides the details about turning on client logging
+    which can help in debugging of various issues while developing the messaging applications. </para>
 
-   <para>The details about Qpid JMS Client Exceptions are provided in <xref linkend="JMS-Client-0-8-Exceptions"/></para>
+  <para>The details about Qpid JMS Client Exceptions are provided in <xref
+      linkend="JMS-Client-0-8-Appendix-Exceptions"/></para>
 
 </chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Exceptions.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Exceptions.xml
deleted file mode 100644
index f81e99d6ee..0000000000
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Exceptions.xml
+++ /dev/null
@@ -1,33 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
-[
-<!ENTITY %  entities SYSTEM  "commonEntities.xml">
-%entities;
-]>
-<!--
-
- 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.
-
--->
-
-<chapter id="JMS-Client-0-8-Exceptions">
-  <title>Exceptions</title>
-
-  <para>TODO</para>
-</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml
new file mode 100644
index 0000000000..b231972784
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-Logging">
+  <title>Logging</title>
+  <para>The Qpid JMS client uses the <ulink url="http://www.slf4j.org">Apache SLF4J</ulink> logging
+    framework. All logging activity created by the client is directed through the SLF4J API. SLF4J
+    is a is a façade for other common logging frameworks. This makes it easy for application authors
+    to use their prefered logging framework in their application stack, and have the Qpid JMS Client
+    use it too. </para>
+  <para>SLF4J suppplies bindings for many common logging frameworks (<ulink
+      url="&oracleJdkDocUrl;java/util/logging/package-summary.html">JUL</ulink>, <ulink
+      url="http://logging.apache.org/log4j/1.2/">Apache Log4J</ulink>, <ulink
+      url="http://logback.qos.ch">Logback</ulink>.</para>
+  <para>Include the SLF4J binding corresponding to the logging framework of your choosen logging
+    framework on classpath. For full details, see the SLF4J <ulink url="http://www.slf4j.org"
+      >documentation</ulink>.</para>
+
+  <section id="JMS-Client-0-8-Logging-RecommendedProductionLoggingLevel">
+    <title>Recommended Production Logging Level</title>
+    <para>In production, it is recommended that you configure your logging framework is configured
+      with logger <literal>org.apache.qpid</literal> set to <literal>WARN</literal>.</para>
+    <para>If you are using Apache Log4j with a log4j.properties file, this simply means adding the
+      following line:</para>
+    <screen>
+      org.apache.qpid=WARN
+    </screen>
+    <para>If you are using another logging framework, or you are using Log4j but configuring in
+      another manner, refer to the documentation accompanying the logging framework for details of
+      how to proceed.</para>
+  </section>
+  <section id="JMS-Client-0-8-Logging-EnablingDebugLogging">
+    <title>Enabling Debug</title>
+    <para>If you are experiencing a problem, it can be informative to enable debug logging to allow
+      the behaviour of the Qpid JMS client to be understood at a deeper level.</para>
+    <para>To do this, set the <literal>org.apache.qpid</literal> logger to
+      <literal>DEBUG</literal>.</para>
+    <para>If you are using Apache Log4j with a log4j.properties file, this simply means adding (or
+      changing) the following line:</para>
+    <screen>
+      org.apache.qpid=DEBUG
+    </screen>
+    <para>If you are using another logging framework, or you are using Log4j but configuring in
+      another manner, refer to the documentation accompanying the logging framework for details of
+      how to proceed.</para>
+  </section>
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
index acef140192..44c2591bff 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
@@ -359,7 +359,7 @@
 							specify an alternative transport mechanism that implements the interface
 								<varname>org.apache.qpid.transport.network.OutgoingNetworkTransport</varname>.</para></entry>
 				</row>
-				<row>
+				<row id="JMS-Client-0-8-System-Properties-SyncOpTimeout">
 					<entry>qpid.sync_op_timeout</entry>
 					<entry>long</entry>
 					<entry>60000</entry>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Turning-On-Logging.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Turning-On-Logging.xml
deleted file mode 100644
index 0ec9f731ec..0000000000
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Turning-On-Logging.xml
+++ /dev/null
@@ -1,33 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
-[
-<!ENTITY %  entities SYSTEM  "commonEntities.xml">
-%entities;
-]>
-<!--
-
- 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.
-
--->
-
-<chapter id="JMS-Client-0-8-Turning-On-Logging">
-  <title>Turning On Logging</title>
-
-  <para>TODO</para>
-</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
index d22b6b8a48..bfb71ea73e 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
@@ -60,12 +60,11 @@
     <para>The Qpid JMS client provides a single implementation of the InitialContextFactory in class
         <literal>org.apache.qpid.jndi.PropertiesFileInitialContextFactory</literal>. This
       implementation is backed by a <ulink url="&oracleJdkDocUrl;java/util/Properties.html"
-        >Properties</ulink> object which can of course be loaded from an external properties file, or
-      created programatically.</para>
-    <para>The examples in the previous chapter illustrated the Java code required to
-      <link linkend="JMS-Client-0-8-Examples-PTP">create the InitialContext</link> and an <link
-        linkend="JMS-Client-0-8-Examples-PTP-PropertiesFile">example properties
-      file</link>.</para>
+        >Properties</ulink> object which can of course be loaded from an external properties file,
+      or created programatically.</para>
+    <para>The examples in the previous chapter illustrated the Java code required to <link
+        linkend="JMS-Client-0-8-Examples-PTP">create the InitialContext</link> and an <link
+        linkend="JMS-Client-0-8-Examples-PTP-PropertiesFile">example properties file</link>.</para>
     <para>Note that the Qpid Broker does not present a JNDI interface to the application.</para>
     <figure>
       <title>JNDI overview</title>
@@ -113,9 +112,10 @@
         originating system.</para>
       <para>If, after all retries are exhausted, failover has failed to reconnect the application,
         the Connection's <ulink url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html"
-          >ExceptionListener</ulink> will receive a JMSException with a linked exception of
-        AMQDisconnectedException. Any further use of the JMS objects (Connection, Session etc), will
-        results in a <ulink url="&oracleJeeDocUrl;javax/jms/IllegalStateException.html"
+          >ExceptionListener</ulink> will receive a JMSException with a linked exception of <ulink
+          url="JMS-Client-0-8-Appendix-Exceptions-AMQDisconnectedException"
+          >AMQDisconnectedException</ulink>. Any further use of the JMS objects (Connection, Session
+        etc), will results in a <ulink url="&oracleJeeDocUrl;javax/jms/IllegalStateException.html"
           >IllegalStateException</ulink>.</para>
       <para>Configure failover using the Connection URL. Here's an example Connection URL utilising
         failover between two brokers. Note the use of the broker options <link
@@ -346,9 +346,11 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/ap
       <para>The Message is returned to the application in an asynchronous fashion via the
         Connection's <ulink url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html"
           >ExceptionListener</ulink>. When a message is returned, it will be invoked with a
-        JMSException whose linked exception is an AMQNoRouteException. The returned message is
-        available to the application by calling AMQNoRouteException#getUndeliveredMessage(). The
-        ExceptionListener will be invoked exactly once for each returned message.</para>
+        JMSException whose linked exception is an <ulink
+          url="JMS-Client-0-8-Appendix-Exceptions-AMQNoRouteException">AMQNoRouteException</ulink>.
+        The returned message is available to the application by calling
+        AMQNoRouteException#getUndeliveredMessage(). The ExceptionListener will be invoked exactly
+        once for each returned message.</para>
       <para>The mandatory message feature is turned <emphasis>on</emphasis> by default for Queue
         destinations and <emphasis>off</emphasis> for Topic destinations. This can be overridden
         using system properties <link linkend="JMS-Client-0-8-System-Properties-DefaultMandatory"
@@ -377,9 +379,10 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/ap
         asynchronous fashion using the Connection's <ulink
           url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html">ExceptionListener</ulink>.</para>
       <para>The ExceptionListener will be invoked with a JMSException whose linked exception is an
-        AMQNoConsumersException. The returned message is available to the application by calling
-        AMQNoConsumersException#getUndeliveredMessage(). The ExceptionListener will be invoked
-        exactly once for each returned message.</para>
+          <ulink url="JMS-Client-0-8-Appendix-Exceptions-AMQNoConsumersException"
+          >AMQNoConsumersException</ulink>. The returned message is available to the application by
+        calling AMQNoConsumersException#getUndeliveredMessage(). The ExceptionListener will be
+        invoked exactly once for each returned message.</para>
       <para>The immediate message feature is turned <emphasis>off</emphasis> by default. It can be
         enabled with system property <link
           linkend="JMS-Client-0-8-System-Properties-DefaultImmediate"