QPID-4943: Introduce a feature for 0-8/0-9/0-9-1 protocols to close a connection on receiving a mandatory unroutable message in a transacted session

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

2 files changed, 55 insertions, 0 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Close-On-No-Route.xml b/qpid/doc/book/src/java-broker/Java-Broker-Close-On-No-Route.xml
new file mode 100644
index 0000000000..d2d8fefbc8
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Close-On-No-Route.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section id="Java-Broker-Close-Connection-When-No-Route">
+  <title>Closing client connections on unroutable mandatory messages</title>
+
+  <section id="Java-Broker-Close-Connection-When-No-Route-Summary">
+  <title>Summary</title>
+    <para>
+        Due to asynchronous nature of AMQP 0-8/0-9/0-9-1 protocols sending a message with a routing key for which no queue binding exist results
+        in either message being bounced back (if it is mandatory or immediate) or discarded on broker side otherwise.
+    </para>
+    <para>
+        When a 'mandatory' message is returned back, the Qpid JMS client conveys this by delivering
+        an <emphasis>AMQNoRouteException</emphasis> through the configured ExceptionListener on the Connection.
+        This does not cause channel or connection closure, however it requires a special exception handling
+        on client side in order to deal with <emphasis>AMQNoRouteExceptions</emphasis>.
+        This could potentially be a problem when using various messaging frameworks (e.g Mule)
+        as they usually close the connection on receiving any JMSException.
+    </para>
+    <para>
+        In order to simplify application handling of scenarios where 'mandatory' messages
+        are being sent to queues which do not actually exist, the Java Broker can be configured such that
+        it will respond to this situation by closing the connection
+        rather than returning the unroutable message to the client as it normally should.
+        From the application perspective, this will result in failure of synchronous operations in progress such as a session commit() call.
+    </para>
+    <note>
+        <para>This feature affects only transacted sessions.</para>
+        <para>
+            Qpid JMS client sends 'mandatory' messages when using Queue destinations
+            and 'non-mandatory' messages when using Topic destinations.
+        </para>
+    </note>
+  </section>
+  <section id="Java-Broker-Close-Connection-When-No-Route-Configuration">
+    <title>Configuring <emphasis>closeWhenNoRoute</emphasis></title>
+    <para>
+        The Broker attribute <emphasis>closeWhenNoRoute</emphasis> can be set to specify this feature on broker side.
+        By default, it is turned on. Setting <emphasis>closeWhenNoRoute</emphasis> to <emphasis>false</emphasis> switches it off.
+    </para>
+    <para>
+        Setting the <emphasis>closeWhenNoRoute</emphasis> in the JMS client connection URL can override the broker configuration
+        on a connection specific basis, for example :
+    </para>
+    <example>
+        <title>Disable feature to close connection on unroutable messages with client URL</title>
+        <screen><![CDATA[
+amqp://guest:guest@clientid/?brokerlist='tcp://localhost:5672'&closeWhenNoRoute='false']]></screen>
+    </example>
+    <para>
+       If no value is specified on the client the broker setting will be used. If client setting is specified then it will take precedence
+       over the broker-wide configuration. If the client specifies and broker does not support this feature the warning will be logged.
+    </para>
+    </section>
+</section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
index 2af775d2fc..3c2b9b8dcc 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
@@ -27,4 +27,5 @@
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Disk-Space-Management.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Producer-Transaction-Timeout.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Handling-Undeliverable-Messages.xml"/>
+        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Close-On-No-Route.xml"/>
 </chapter>