QPID-6108: [Java Broker Documentation] Document message compression client/broker side. Also fixed up statements around ADDR support.

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

8 files changed, 194 insertions, 68 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Message-Compression.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Message-Compression.xml
new file mode 100644
index 0000000000..f4d42b051d
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Message-Compression.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+
+ 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.
+
+-->
+
+<section id="Java-Broker-Runtime-Message-Compression">
+ <title>Message Compression</title>
+ <para>The Java Broker supports message compression. This feature works in co-operation with
+  Qpid Clients implementing the same feature.</para>
+ <para>Once the feature is enabled (using Broker context variable
+   <emphasis>broker.messageCompressionEnabled</emphasis>), the Broker will advertise support for the
+  message compression feature to the client at connection time. This allows clients to opt to turn
+  on message compression, allowing message payload sizes to be reduced.</para>
+ <para>If the Broker has connections from client who have message compression enabled and other who
+  do not, it will internally, on-tyhe-fly, decompress compressed messages when sending to clients
+  without support and conversely, compress uncomressed messages when sending to clients who support
+  it.</para>
+ <para>The Broker has a threshold below which it will not consider compressing a message, this is
+  controlled by Broker content variable
+   (<literal>connection.messageCompressionThresholdSize</literal>).</para>
+ <para>This feature <emphasis>may</emphasis> have a beneficial effect on performance by:</para>
+ <itemizedlist>
+  <listitem>
+   <para>Reducing the number of bytes transmitted over the wire, both between Client and Broker, and
+    in the HA case, Broker to Broker, for replication purposes.</para>
+  </listitem>
+  <listitem>
+   <para>Reducing storage space when data is at rest within the Broker,  both on disk and in memory.</para>
+  </listitem>
+ </itemizedlist>
+ <para>Of course, compression and decompression is computationally expensive. Turning on the feature
+  may have a negative impact on CPU utilization on Broker and/or Client. Also for small messages
+  payloads, message compression may increase the message size. It is recommended to test the feature
+  with representative data.</para>
+</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 6394ad4d2b..cd214de26d 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
@@ -32,4 +32,5 @@
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Close-On-No-Route.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Flow-To-Disk.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Background-Recovery.xml"/>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime-Message-Compression.xml"/>
 </chapter>
diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
index f73dd5e648..b5c231046e 100644
--- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
+++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
@@ -28,7 +28,8 @@
   <para>The Broker can only be managed via the HTTP management channel.</para>
   <section id="Java-Broker-Management-Managing-Broker-Attributes">
     <title>Attributes</title>
-    <para><itemizedlist>
+    <para>
+      <itemizedlist>
         <listitem>
           <para><emphasis>Name the Broker</emphasis>. This helps distinguish between Brokers in
             environments that have many.</para>
@@ -42,27 +43,38 @@
           <para><emphasis>Heartbeating</emphasis>. Enables heartbeats between Broker and Clients.
             Heartbeats help discover severed TCP/IP connections in a timely manner.</para>
         </listitem>
-      </itemizedlist></para>
+      </itemizedlist>
+    </para>
   </section>
   <section id="Java-Broker-Management-Managing-Broker-Context">
     <title>Context</title>
     <para>
       <itemizedlist>
-        <listitem><para><emphasis>broker.flowToDiskThreshold</emphasis> Controls the <link linkend="Java-Broker-Runtime-Flow-To-Disk">flow to disk</link> feature.</para></listitem>
-        <listitem><para><emphasis>broker.messageCompressionEnabled</emphasis> Controls the message compression feature (co-operative feature with some Qpid clients).</para></listitem>
+        <listitem>
+          <para><emphasis>broker.flowToDiskThreshold</emphasis> Controls the <link
+              linkend="Java-Broker-Runtime-Flow-To-Disk">flow to disk</link> feature.</para>
+        </listitem>
+        <listitem>
+          <para><emphasis>broker.messageCompressionEnabled</emphasis> Controls the <link
+              linkend="Java-Broker-Runtime-Message-Compression">message compression</link> .</para>
+        </listitem>
       </itemizedlist>
-      
     </para>
   </section>
   <section id="Java-Broker-Management-Managing-Broker-Children">
     <title>Children</title>
-    <para><itemizedlist>
+    <para>
+      <itemizedlist>
         <listitem>
-          <para><link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes">Virtualhost
-              nodes</link></para>
+          <para>
+            <link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes">Virtualhost
+              nodes</link>
+          </para>
         </listitem>
         <listitem>
-          <para><link linkend="Java-Broker-Management-Managing-Ports">Ports</link></para>
+          <para>
+            <link linkend="Java-Broker-Management-Managing-Ports">Ports</link>
+          </para>
         </listitem>
         <listitem>
           <para>Authentication Providers</para>
@@ -76,7 +88,8 @@
         <listitem>
           <para>Access Control Providers</para>
         </listitem>
-      </itemizedlist></para>
+      </itemizedlist>
+    </para>
   </section>
   <section id="Java-Broker-Management-Managing-Broker-Lifecycle">
     <title>Lifecycle</title>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Binding-URL.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Binding-URL.xml
index 2f6bafbb76..dd1c86c846 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Binding-URL.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Binding-URL.xml
@@ -29,10 +29,11 @@
 <chapter id="JMS-Client-0-8-Binding-URL">
   <title>Binding URL</title>
 
-  <para> The <emphasis>Binding URL</emphasis> syntax is the only addressing syntax supported by the
-    Qpid JMS client for AMQP 0-8, 0-9 and 0-9-1. It allows to specify the bindings that define the
-    relationship between a queue and an exchange, queue and exchange creation arguments and client
-    behaviour. </para>
+  <para> The <emphasis>Binding URL</emphasis> syntax for addressing<footnote>
+      <para>The client also supports the ADDR format. This is documented in <ulink
+          url="&qpidProgrammingBook;">Programming in Apache Qpid</ulink>.</para>
+    </footnote>. It allows the specification of the bindings between a queue and an exchange, queue
+    and exchange creation arguments and some ancillary options.</para>
 
   <para> The format for a <emphasis>Binding URL</emphasis> is provided below <screen><![CDATA[
 <Exchange Class>://<Exchange Name>/[<Destination>]/[<Queue>][?<option>='<value>'[&<option>='<value>']]
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 9480d38c74..5bc27fce23 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
@@ -146,6 +146,18 @@
 						<para> Introduced in version 0.22. </para>
 					</entry>
 				</row>
+				<row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-CompressMessages">
+					<entry>compressMessages</entry>
+					<entry>Boolean</entry>
+					<entry>false</entry>
+					<entry><para>Controls whether the client will compress messages before they they are sent.</para></entry>
+				</row>
+				<row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-MessageCompressionThresholdSize">
+					<entry>messageCompressionThresholdSize</entry>
+					<entry>Integer</entry>
+					<entry>102400</entry>
+					<entry><para>The payload size beyond which the client will start to compress message payloads.</para></entry>
+				</row>
 			</tbody>
 		</tgroup>
 	</table>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml
index 2b78407897..537a1075fe 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml
@@ -28,11 +28,14 @@
 
 <appendix id="JMS-Client-0-8-Appendix-JMS-Extensions">
   <title>JMS Extensions</title>
-  <para>This section illustrates using Qpid specific JMX extentions for the managament of queues,
-    exchanges and bindings.</para>
-  <para>
-    <important>It is not recommended that these extensions are normally used. Instead, the reader is
-      directed towards the Managment interfaces of the Broker.</important></para>
+  <para>This section illustrates using Qpid specific extentions to JMX for the managament of queues,
+  exchanges and bindings.</para>
+  <!-- TODO perhaps mention ConnectionListener?-->
+  <important>
+    <para>It is not recommended that these extensions are generally used. These interfaces are
+      subject to change and will not be supported in this form for AMQP 1.0. Instead, the reader is
+      directed towards the Managment interfaces of the Broker.</para>
+  </important>
   <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Queue">
     <title>Queue Management</title>
     <para>These extensions allow queues to be created or removed.</para>
@@ -55,17 +58,19 @@ AMQDestination amqQueue = (AMQDestination) context.lookup("myqueue");
 ]]></programlisting>
       </example>
     </section>
-    <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding">
-      <title>Binding Management</title>
-      <para>These extensions allow bindings to be created or removed.</para>
+  </section>
+
+  <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding">
+    <title>Binding Management</title>
+    <para>These extensions allow bindings to be created or removed.</para>
 
-      <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding-Creation">
-        <title>Binding creation</title>
-        <para>The following example illustrates the creation of queue binding to topic exchange with
-          JMS client.</para>
-        <example>
-          <title>Binding a queue using JMS</title>
-          <programlisting><![CDATA[ConnectionFactory connectionFactory = ...
+    <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding-Creation">
+      <title>Binding creation</title>
+      <para>The following example illustrates the creation of queue binding to topic exchange with
+        JMS client.</para>
+      <example>
+        <title>Binding a queue using JMS</title>
+        <programlisting><![CDATA[ConnectionFactory connectionFactory = ...
 Connection connection = connectionFactory.createConnection();
 AMQSession<?, ?> session = (AMQSession<?,?>)connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
 
@@ -84,8 +89,7 @@ arguments.put("x-filter-jms-selector", "application='app1'");
 // create binding
 session.bindQueue(queueName, routingKey, FieldTable.convertToFieldTable(arguments),
     new AMQShortString("amq.topic"), destination);]]></programlisting>
-        </example>
-      </section>
+      </example>
     </section>
   </section>
 </appendix>
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 a1ffafec76..dafb1eb267 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
@@ -87,6 +87,18 @@
                         <para>Setting this property to 'false' will disable that check and
                             allow you to ignore host name errors.</para></entry>
                 </row>
+				<row id="JMS-Client-0-8-System-Properties-ConnectionCompressMessages">
+					<entry>qpid.connection_compress_messages</entry>
+					<entry>Boolean</entry>
+					<entry>false</entry>
+					<entry><para>Controls whether the client will compress messages before they they are sent.</para></entry>
+				</row>
+				<row id="JMS-Client-0-8-System-Properties-MessageCompressionThresholdSize">
+					<entry>qpid.message_compression_threshold_size</entry>
+					<entry>Integer</entry>
+					<entry>102400</entry>
+					<entry><para>The payload size beyond which the client will start to compress message payloads.</para></entry>
+				</row>
 			</tbody>
 		</tgroup>
 	</table>
@@ -108,8 +120,7 @@
 					<entry>qpid.dest_syntax</entry>
 					<entry>String</entry>
 					<entry>ADDR</entry>
-					<entry><para>The default addressing syntax.  The Address (ADDR) syntax is supported when using AMQP 0-10.  Binding URL (BURL)
-					  is supported by AMQP protocols 0-8 through to 0-10.</para></entry>
+					<entry><para>Addressing syntax: ADDR (Address format) or BURL (Binding URL)</para></entry>
 				</row>
 				<row id="JMS-Client-0-8-System-Properties-Maxprefetch">
 					<entry>max_prefetch</entry>
@@ -121,8 +132,6 @@
 								linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Maxprefetch"
 								>Connection URL</link> options.</para></entry>
 				</row>
-
-
 				<!-- 0-10
 				<row>
 					<entry>qpid.session.command_limit</entry>
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 9a75c16111..edd498af80 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
@@ -90,8 +90,9 @@
       is closed when the application calls <ulink
         url="&oracleJeeDocUrl;javax/jms/Connection.html#close()">Connection#close()</ulink>, but it
       can also be closed if the connection is closed from the Broker side (via a Management
-      operation or broker shutdown or running into coditions which AMQP specifications treats as errors and mandates closing the connection).
-      The JMS connection will also be closed if the underlying TCP/IP connection is broken.</para>
+      operation or broker shutdown or running into conditions which AMQP specifications treats as
+      errors and mandates closing the connection). The JMS connection will also be closed if the
+      underlying TCP/IP connection is broken.</para>
     <para>Qpid connections have failover and heartbeating capabilities. They support SSL and
       client-auth. These are described in the sub-sections that follow.</para>
     <section id="JMS-Client-0-8-Client-Understanding-Connection-Failover">
@@ -136,17 +137,18 @@ amqp://username:password@clientid/test
         </screen>
       </example>
       <para>For full details see <xref linkend="JMS-Client-0-8-Connection-URL"/></para>
-      <note><para>Note, that a single broker failover is enabled by default. If the failover behaviour is not desired it can be switched off
-       by setting a failover option to <emphasis>nofailover</emphasis> as in the example below
-       <example>
-        <title>Connection URL configured with nofailover</title>
-        <screen><![CDATA[
+      <note>
+        <para>Note, that a single broker failover is enabled by default. If the failover behaviour
+          is not desired it can be switched off by setting a failover option to
+            <literal>nofailover</literal> as in the example below <example>
+            <title>Connection URL configured with nofailover</title>
+            <screen><![CDATA[
 amqp://username:password@clientid/test
             ?brokerlist='tcp://localhost:15672?failover='nofailover']]>
         </screen>
-      </example>
-      </para></note>
-      <!-- TODO perhaps mention ConnectionListener?-->
+          </example>
+        </para>
+      </note>
     </section>
     <section id="JMS-Client-0-8-Client-Understanding-Connection-Heartbeating">
       <title>Heartbeating</title>
@@ -228,6 +230,31 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1
         </listitem>
       </itemizedlist>
     </section>
+    <section id="JMS-Client-0-8-Client-Understanding-Connection-MessageCompression">
+      <title>Message Compression</title>
+      <para>The client has the ability to transparently compress message payloads on outgoing
+        messages and decompress them on incoming messages. In some environments and with some
+        payloads this feature might offer performance improvements by reducing the number of bytes
+        transmitted over the connection.</para>
+      <para>In order to make use of message compression, the Broker must enable the feature too,
+        otherwise the compression options will be ignored.</para>
+      <para> To enable message compression on the client use the connection url property <link
+          linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-CompressMessages"
+            ><literal>compressMessages</literal></link> (or JVM wide using the system property <link
+          linkend="JMS-Client-0-8-System-Properties-ConnectionCompressMessages"
+            ><literal>qpid.connection_compress_messages</literal></link>)</para>
+      <para>It is also possible to control the threshold at which the client will begin to compress
+        message payloads. See connection url property <link
+          linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-MessageCompressionThresholdSize"
+            ><literal>messageCompressionThresholdSize</literal></link> (or JVM wide using the system
+        property <link linkend="JMS-Client-0-8-System-Properties-MessageCompressionThresholdSize"
+            ><literal>qpid.message_compression_threshold_size</literal></link>)</para>
+      <note>
+        <para>The Broker, where necessary, takes care of compressing/decompressing messages of the
+          fly so that clients using message compression can exchange messages with clients not
+          supporting message compression transparently, without application intervention.</para>
+      </note>
+    </section>
   </section>
   <section id="JMS-Client-0-8-Client-Understanding-Session">
     <title>Session</title>
@@ -284,17 +311,21 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1
           >MessageConsumer#receive()</ulink> for Consumer B on the same Session, the application
         will hang indefinitely as even if messages suitable for B arrive at the Broker. Those
         messages can never be sent to the Session as no space is available in prefetch. </para>
-      <note><para>Please note, when the acknowlegement mode <emphasis>Session#SESSION_TRANSACTED</emphasis>
-       or <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis> is set on a consuming session,
-       the prefetched messages are released from the prefetch buffer on transaction commit/rollback
-       (in case of acknowledgement mode <emphasis>Session#SESSION_TRANSACTED</emphasis> )
-       or acknowledgement of the messages receipt (in case of acknowledgement mode
-       <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis> ). If the consuming application does not commit/rollback
-       the receiving transaction (for example, due to mistakes in application exception handling logic),
-       the prefetched messages continue to remain in the prefetch buffer preventing the delivery of the following messages.
-       As result, the application might stop the receiving of the messages
-       until the transaction is committed/rolled back (for <emphasis>Session#SESSION_TRANSACTED</emphasis> )
-        or received messages are acknowledged (for <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis>).</para></note>
+      <note>
+        <para>Please note, when the acknowledgement mode
+            <emphasis>Session#SESSION_TRANSACTED</emphasis> or
+            <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis> is set on a consuming session, the
+          prefetched messages are released from the prefetch buffer on transaction commit/rollback
+          (in case of acknowledgement mode <emphasis>Session#SESSION_TRANSACTED</emphasis> ) or
+          acknowledgement of the messages receipt (in case of acknowledgement mode
+            <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis> ). If the consuming application does not
+          commit/rollback the receiving transaction (for example, due to mistakes in application
+          exception handling logic), the prefetched messages continue to remain in the prefetch
+          buffer preventing the delivery of the following messages. As result, the application might
+          stop the receiving of the messages until the transaction is committed/rolled back (for
+            <emphasis>Session#SESSION_TRANSACTED</emphasis> ) or received messages are acknowledged
+          (for <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis>).</para>
+      </note>
     </section>
     <section id="JMS-Client-0-8-Client-Understanding-Session-TemporaryQueues">
       <title>TemporaryQueues</title>
@@ -379,10 +410,11 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1
           linkend="JMS-Client-0-8-System-Properties-DefaultMandatoryTopic"
             ><literal>qpid.default_mandatory_topic</literal></link> for Queues and Topics
         respectively.</para>
-      <note><para>Please note, according to AMQP specifications the mandatory flag on a message tells the server
-       how to react if the message cannot be routed to a  queue. If this flag is set, the server will return an unroutable message with a
-       Return method. If this flag is zero, the server silently drops the message. Please, refer <ulink url="&amqpSrc;">AMQP specifications</ulink>
-        for more details.</para></note>
+      <note>
+        <para>If this the mandatory flag is not set, the Broker will treat <ulink
+            url="&qpidJavaBrokerBook;Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-UnroutableMessage"
+            >the messages as unroutable</ulink>.</para>
+      </note>
     </section>
     <section id="JMS-Client-0-8-Client-Understanding-MessageProducer-CloseWhenNoRoute">
       <title>Close When No Route</title>
@@ -457,13 +489,13 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1
             by the Binding URL associated with the Destination.</para>
         </listitem>
       </orderedlist>
-      <para>The exchange declare, queue declare and bind side effects can be suppressed using system properties
-          <link linkend="JMS-Client-0-8-System-Properties-DeclareExchanges"
+      <para>The exchange declare, queue declare and bind side effects can be suppressed using system
+        properties <link linkend="JMS-Client-0-8-System-Properties-DeclareExchanges"
             ><literal>qpid.declare_exchanges</literal></link>, <link
           linkend="JMS-Client-0-8-System-Properties-DeclareQueues"
-            ><literal>qpid.declare_queues</literal></link> and
-          <link linkend="JMS-Client-0-8-System-Properties-BindQueues"
-            ><literal>qpid.bind_queues</literal></link>.</para>
+            ><literal>qpid.declare_queues</literal></link> and <link
+          linkend="JMS-Client-0-8-System-Properties-BindQueues"
+          ><literal>qpid.bind_queues</literal></link>.</para>
     </section>
     <section id="JMS-Client-0-8-Client-Understanding-MessageConsumer-TopicSubscriptions">
       <title>Topic Subscriptions</title>
@@ -509,9 +541,11 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1
       <para>See <ulink
           url="&qpidJavaBrokerBook;Java-Broker-Runtime-Handling-Undeliverable-Messages.html#Java-Broker-Runtime-Handling-Undeliverable-Messages-Maximum-Delivery-Count"
           > Handling Undeliverable Messages</ulink> within the Java Broker book for full details of
-          the functioning of this feature.</para>
-      <note><para>The optional JMS message header <literal>JMSXDeliveryCount</literal> is <emphasis>not</emphasis>
-          supported.</para></note>
+        the functioning of this feature.</para>
+      <note>
+        <para>The optional JMS message header <literal>JMSXDeliveryCount</literal> is
+            <emphasis>not</emphasis> supported.</para>
+      </note>
     </section>
   </section>
   <section id="JMS-Client-0-8-Client-Understanding-Destinations">