QPID-4141: Add Java Broker docbook documentation for lvq and sorted queues. Rework

priority queue documentation.

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

3 files changed, 277 insertions, 141 deletions

diff --git a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
index d4eb71da2b..54c2984d0a 100644
--- a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
+++ b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
@@ -1,6 +1,6 @@
 <?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
@@ -59,8 +59,8 @@
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Debug-using-log4j.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="How-to-Tune-M3-Java-Broker-Performance.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Java-Build-How-To.xml"/>
-        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Use-Priority-Queues.xml"/>
-        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="How-to-Use-SlowConsumerDisconnect.xml"/> 
+        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="OtherQueueTypes.xml"/>
+        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="How-to-Use-SlowConsumerDisconnect.xml"/>
 </chapter>
 
 
diff --git a/qpid/doc/book/src/java-broker/OtherQueueTypes.xml b/qpid/doc/book/src/java-broker/OtherQueueTypes.xml
new file mode 100644
index 0000000000..d42e4e62cb
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/OtherQueueTypes.xml
@@ -0,0 +1,274 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE urls [
+<!ENTITY oracleJeeDocUrl "http://docs.oracle.com/javaee/6/api/">
+]>
+<!--
+
+ 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="OtherQueueTypes">
+  <title>Other Queue Types</title>
+
+  <section role="h2" id="OtherQueueTypes-Introduction">
+    <title>Introduction</title>
+    <para> In addition to the standard queue type where messages are delivered in the same order
+      that they were sent, the Java Broker supports three additional queue types which allows for
+      alternative delivery behaviours. These are <link linkend="OtherQueueTypes-Priority"
+        >priority-queues</link>, <link linkend="OtherQueueTypes-Sorted">sorted-queues</link>-, and
+        <link linkend="OtherQueueTypes-LVQ">last-value-queues</link> (LVQs). </para>
+    <para> In the following sections, the semantics of each queue type is described, followed by a
+      description of how instances of these queue can be created via <link
+        linkend="OtherQueueTypes-CreateUsingConfig">configuration</link> or <link
+        linkend="OtherQueueTypes-CreateUsingJmsOrJmx">programmatically</link>. </para>
+    <para>The final section discusses the importance of using a <link
+        linkend="OtherQueueTypes-SetLowPrefetch">low client pre-fetch</link> with these queued.
+    </para>
+  </section>
+
+  <section role="h2" id="OtherQueueTypes-Priority">
+    <title>Priority Queues</title>
+    <para>In a priority queue, messages on the queue are delivered in an order determined by the
+        <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getJMSPriority()">JMS priority message
+        header</ulink> within the message. By default Qpid supports the 10 priority levels mandated
+      by JMS, with priority value 0 as the lowest priority and 9 as the highest. </para>
+    <para>It is possible to reduce the effective number of priorities if desired.</para>
+    <para>JMS defines the <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#DEFAULT_PRIORITY">
+        default message priority</ulink> as 4. Messages sent without a specified priority use this
+      default. </para>
+  </section>
+  <section role="h2" id="OtherQueueTypes-Sorted">
+    <title>Sorted Queues</title>
+    <para>Sorted queues allow the message delivery order to be determined by value of an arbitrary
+        <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getStringProperty()">JMS message
+        property</ulink>. Sort order is alpha-numeric and the property value must have a type
+      java.lang.String.</para>
+    <para>Messages sent to a sorted queue without the specified JMS message property will be
+      inserted into the 'last' position in the queue.</para>
+  </section>
+  <section role="h2" id="OtherQueueTypes-LVQ">
+    <title>Last Value Queues (LVQ)</title>
+    <para>LVQs (or conflation queues) are special queues that automatically discard any message when
+      a newer message arrives with the same key value. The key is specified by arbitrary <ulink
+        url="&oracleJeeDocUrl;javax/jms/Message.html#getPropertyNames()">JMS message
+        property</ulink>.</para>
+    <para>An example of an LVQ might be where a queue represents prices on a stock exchange: when
+      you first consume from the queue you get the latest quote for each stock, and then as new
+      prices come in you are sent only these updates. </para>
+    <para>Like other queues, LVQs can either be browsed or consumed from. When browsing an
+      individual subscriber does not remove the message from the queue when receiving it. This
+      allows for many subscriptions to browse the same LVQ (i.e. you do not need to create and bind
+      a separate LVQ for each subscriber who wishes to receive the contents of the LVQ).</para>
+    <para>Messages sent to an LVQ without the specified property will be delivered as normal and
+      will never be "replaced".</para>
+  </section>
+  <section role="h2" id="OtherQueueTypes-Create">
+    <title>Creating a Priority, Sorted or LVQ Queue</title>
+    <para>To create a priority, sorted or LVQ queue, it can be defined in the virtualhost
+      configuration file, or the queue can be created programmtically from a client via AMQP (using
+      an extension to JMS), or using JMX. These methods are described below. </para>
+    <para>Once a queue is created you cannot change its type (without deleting it and re-creating).
+      Also note you cannot currently mix the natures of these queue types, for instance, you cannot
+      define a queue which it both an LVQ and a priority-queue.</para>
+    <section role="h2" id="OtherQueueTypes-CreateUsingConfig">
+      <title>Using configuration</title>
+      <para>To create a priority, sorted or LVQ queue within configuration, add the appropriate xml
+        to the virtualhost.xml configuration file within the <varname>queues</varname>
+        element.</para>
+      <section role="h3" id="OtherQueueTypes-CreateUsingConfig-Priority">
+        <title>Priority</title>
+        <para> To defining a priority queue, add a &lt;priority&gt;true&lt;/priority&gt; element. By
+          default the queue will have 10 distinct priorities. </para>
+        <example>
+          <title>Configuring a priority queue</title>
+          <programlisting><![CDATA[<queue>
+    <name>myqueue</name>
+    <myqueue>
+        <exchange>amq.direct</exchange>
+        <priority>true</priority>
+    </myqueue>
+</queue>]]></programlisting>
+        </example>
+        <para> If you require fewer priorities, it is possible to specify a
+            <varname>priorities</varname> element (whose value is a integer value between 2 and 10
+          inclusive) which will give the queue that number of distinct priorities. When messages are
+          sent to that queue, their effective priority will be calculated by partitioning the
+          priority space. If the number of effective priorities is 2, then messages with priority
+          0-4 are treated the same as "lower priority" and messages with priority 5-9 are treated
+          equivalently as "higher priority". </para>
+        <example>
+          <title>Configuring a priority queue with fewer priorities</title>
+          <programlisting><![CDATA[<queue>
+    <name>myqueue</name>
+    <myqueue>
+        <exchange>amq.direct</exchange>
+        <priority>true</priority>
+        <priorities>4</priorities>
+    </myqueue>
+</queue>]]></programlisting>
+        </example>
+      </section>
+      <section role="h3" id="OtherQueueTypes-CreateUsingConfig-Sorted">
+        <title>Sorted</title>
+        <para> To define a sorted queue, add a <varname>sortKey</varname> element. The value of the
+            <varname>sortKey</varname> element defines the message property to use the value of when
+          sorting the messages put onto the queue. </para>
+        <example>
+          <title>Configuring a sorted queue</title>
+          <programlisting><![CDATA[<queue>
+    <name>myqueue</name>
+    <myqueue>
+        <exchange>amq.direct</exchange>
+        <sortKey>message-property-to-sort-by</sortKey>
+    </myqueue>
+</queue>]]></programlisting>
+        </example>
+      </section>
+      <section role="h3" id="OtherQueueTypes-CreateUsingConfig-LVQ">
+        <title>LVQ</title>
+        <para> To define a LVQ, add a <varname>lvq</varname> element with the value
+            <constant>true</constant>. Without any further configuration this will define an LVQ
+          which uses the JMS message property <constant>qpid.LVQ_key</constant> as the key for
+          replacement. </para>
+        <example>
+          <title>Configuring a LVQ queue</title>
+          <programlisting><![CDATA[<queue>
+    <name>myqueue</name>
+    <myqueue>
+        <exchange>amq.direct</exchange>
+        <lvq>true</lvq>
+    </myqueue>
+</queue>]]></programlisting>
+        </example>
+        <para> If you wish to define your own property then you can do so using the
+            <varname>lvqKey</varname> element.</para>
+        <example>
+          <title>Configuring a LVQ queue with custom message property name</title>
+          <programlisting><![CDATA[<queue>
+    <name>myqueue</name>
+    <myqueue>
+        <exchange>amq.direct</exchange>
+        <lvq>true</lvq>
+        <lvqKey>ISIN</lvqKey>
+    </myqueue>
+</queue>]]></programlisting>
+        </example>
+      </section>
+    </section>
+    <section role="h2" id="OtherQueueTypes-CreateUsingJmsOrJmx">
+      <title>Using JMS or AMQP</title>
+      <para>To create a priority, sorted or LVQ queue programmatically from JMX or using a Qpid
+        extension to JMS, pass the appropriate queue-declare arguments.</para>
+      <table>
+        <tgroup cols="4">
+          <thead>
+            <row>
+              <entry>Queue type</entry>
+              <entry>Argument name</entry>
+              <entry>Argument name</entry>
+              <entry>Argument Description</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>priority</entry>
+              <entry>priorities</entry>
+              <entry>java.lang.Integer</entry>
+              <entry>Specifies a priority queue with given number priorities</entry>
+            </row>
+            <row>
+              <entry>sorted</entry>
+              <entry>qpid.queue_sort_key</entry>
+              <entry>java.lang.String</entry>
+              <entry>Specifies sorted queue with given message property used to sort the
+                entries</entry>
+            </row>
+            <row>
+              <entry>lvq</entry>
+              <entry>qpid.last_value_queue_key</entry>
+              <entry>java.lang.String</entry>
+              <entry>Specifies lvq queue with given message property used to conflate the
+                entries</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+      <para>The following example illustrates the creation of the a LVQ queue from a
+        javax.jms.Session object. Note that this utilises a Qpid specific extension to JMS and
+        involves casting the session object back to its Qpid base-class.</para>
+      <example>
+        <title>Creation of an LVQ using the Qpid extension to JMS</title>
+        <programlisting><![CDATA[Map<String,Object> arguments = new HashMap<String, Object>();
+arguments.put("qpid.last_value_queue_key","ISIN");
+((AMQSession<?,?>) session).createQueue(queueName, autoDelete, durable, exclusive, arguments);]]></programlisting>
+
+      </example>
+      <para> The following example illustrates the creation of the sorted queue from a the JMX
+        interface using the ManagedBroker interface. </para>
+      <example>
+        <title>Creation of a sorted queue using JMX</title>
+        <programlisting><![CDATA[Map<String, Object> environment = new HashMap<String, Object>();
+environment.put(JMXConnector.CREDENTIALS, new String[] {"admin","password"});
+// Connect to service
+JMXServiceURL url =  new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi");
+JMXConnector jmxConnector = JMXConnectorFactory.connect(url, environment);
+MBeanServerConnection mbsc =  jmxConnector.getMBeanServerConnection();
+// Object name for ManagedBroker for virtualhost myvhost
+ObjectName objectName = new ObjectName("org.apache.qpid:type=VirtualHost.VirtualHostManager,VirtualHost=myvhost");
+// Get the ManagedBroker object
+ManagedBroker managedBroker = JMX.newMBeanProxy(mbsc, objectName, ManagedBroker.class);;
+
+// Create the queue passing arguments
+Map<String,Object> arguments = new HashMap<String, Object>();
+arguments.put("qpid.queue_sort_key","myheader");
+managedBroker.createNewQueue("myqueue", null, true, arguments);]]></programlisting>
+      </example>
+    </section>
+  </section>
+
+  <section role="h2" id="OtherQueueTypes-SetLowPrefetch">
+    <title>Low pre-fetch</title>
+    <para>Qpid clients receive buffered messages in batches, sized according to the pre-fetch value.
+      The current default is 500. </para>
+    <para>However, if you use the default value you will probably <emphasis>not</emphasis> see
+      desirable behaviour when using priority, sorted or lvq queues. Once the broker has sent a
+      message to the client its delivery order is then fixed, regardless of the special behaviour of
+      the queue. </para>
+    <para>For example, if using a priority queue and a prefetch of 100, and 100 messages arrive with
+      priority 2, the broker will send these messages to the client. If then a new message arrives
+      will priority 1, the broker cannot leap frog messages of lower priority. The priority 1 will
+      be delivered at the front of the next batch of messages to be sent to the client.</para>
+    <para> So, you need to set the prefetch values for your client (consumer) to make this sensible.
+      To do this set the Java system property <varname>max_prefetch</varname> on the client
+      environment (using -D) before creating your consumer. </para>
+    <para>A default for all client connections can be set via a system property: </para>
+    <programlisting>
+-Dmax_prefetch=1
+</programlisting>
+    <para> The prefetch can be also be adjusted on a per connection basis by adding a
+      <varname>maxprefetch</varname> value to the <ulink url="../../Programming-In-Apache-Qpid/html/QpidJNDI.html#section-jms-connection-url">Connection URLs</ulink>
+    </para>
+    <programlisting>
+amqp://guest:guest@client1/development?maxprefetch='1'&amp;brokerlist='tcp://localhost:5672'
+</programlisting>
+    <para>Setting the Qpid pre-fetch to 1 will give exact queue-type semantics as perceived by the
+      client however, this brings a performance cost. You could test with a slightly higher
+      pre-fetch to trade-off between throughput and exact semantics.</para>
+  </section>
+</section>
diff --git a/qpid/doc/book/src/java-broker/Use-Priority-Queues.xml b/qpid/doc/book/src/java-broker/Use-Priority-Queues.xml
deleted file mode 100644
index 466d958d43..0000000000
--- a/qpid/doc/book/src/java-broker/Use-Priority-Queues.xml
+++ /dev/null
@@ -1,138 +0,0 @@
-<?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="Priority-Queues"><title>
-      Use Priority Queues
-    </title>
-
-    
-    <section role="h2" id="UsePriorityQueues-GeneralInformation"><title>
-            General
-            Information
-          </title>
-	  <para>
-            The Qpid M3 release introduces priority queues into the Java
-            Messaging Broker, supporting JMS clients who wish to make use of
-            priorities in their messaging implementation.
-          </para><para>
-            There are some key points around the use of priority queues in
-            Qpid, discussed in the sections below.
-          </para>
-<!--h2--></section>
-    <section role="h2" id="UsePriorityQueues-DefiningPriorityQueues"><title>
-            Defining
-            Priority Queues
-          </title>
-	  <para>
-            You must define a priority queue specifically before you start to
-            use it. You cannot subsequently change a queue to/from a priority
-            queue (without deleting it and re-creating).
-          </para><para>
-            You define a queue as a priority queue in the virtualhost
-            configuration file, which the broker loads at startup. When
-            defining the queue, add a &lt;priority&gt;true&lt;/priority&gt;
-            element. This will ensure that the queue has 10 distinct
-            priorities, which is the number supported by JMS.
-          </para><para>
-            If you require fewer priorities, it is possible to specify a
-            &lt;priorities&gt;int&lt;/priorities&gt; element (where int is a
-            valid integer value between 2 and 10 inclusive) which will give
-            the queue that number of distinct priorities. When messages are
-            sent to that queue, their effective priority will be calculated
-            by partitioning the priority space. If the number of effective
-            priorities is 2, then messages with priority 0-4 are treated the
-            same as "lower priority" and messages with priority 5-9 are
-            treated equivalently as "higher priority".
-          </para>
-            <programlisting>
-&lt;queue&gt;
-    &lt;name&gt;test&lt;/name&gt;
-    &lt;test&gt;
-        &lt;exchange&gt;amq.direct&lt;/exchange&gt;
-        &lt;priority&gt;true&lt;/priority&gt;
-    &lt;/test&gt;
-&lt;/queue&gt;
-</programlisting>
-<!--h2--></section>
-          
-    <section role="h2" id="UsePriorityQueues-Clientconfiguration-2Fmessagingmodelforpriorityqueues"><title>
-            Client configuration/messaging model for priority queues
-          </title>
-	  <para>
-            There are some other configuration &amp; paradigm changes which
-            are required in order that priority queues work as expected.
-          </para>
-    <section role="h3" id="UsePriorityQueues-Setlowprefetch"><title>
-            Set low pre-fetch
-          </title>
-	  <para>
-            Qpid clients receive buffered messages in batches, sized
-            according to the pre-fetch value. The current default is 5000.
-          </para><para>
-            However, if you use the default value you will probably
-            <emphasis>not</emphasis> see desirable behaviour with messages of different
-            priority. This is because a message arriving after the pre-fetch
-            buffer has filled will not leap frog messages of lower priority.
-            It will be delivered at the front of the next batch of buffered
-            messages (if that is appropriate), but this is most likely NOT
-            what you need.
-          </para><para>
-            So, you need to set the prefetch values for your client
-            (consumer) to make this sensible. To do this set the java system
-            property max_prefetch on the client environment (using -D) before
-            creating your consumer.
-          </para><para>
-            Setting the Qpid pre-fetch to 1 for your client means that
-            message priority will be honoured by the Qpid broker as it
-            dispatches messages to your client. A default for all client
-            connections can be set via a system property:
-          </para>
-            <programlisting>
--Dmax_prefetch=1
-</programlisting>
-          <para>
-            The prefetch can be also be adjusted on a per connection basis by
-            adding a 'maxprefetch' value to the <xref linkend="Connection-URL-Format"/>
-          </para>
-            <programlisting>
-amqp://guest:guest@client1/development?maxprefetch='1'&amp;brokerlist='tcp://localhost:5672'
-</programlisting>
-          <para>
-            There is a slight performance cost here if using the receive()
-            method and you could test with a slightly higher pre-fetch (up to
-            10) if the trade-off between throughput and prioritisation is
-            weighted towards the former for your application. (If you're
-            using OnMessage() then this is not a concern.)
-          </para>
-<!--h3--></section>
-    <section role="h3" id="UsePriorityQueues-Singleconsumerpersession"><title>
-            Single
-            consumer per session
-          </title>
-	  <para>
-            If you are using the receive() method to consume messages then
-            you should also only use one consumer per session with priority
-            queues. If you're using OnMessage() then this is not a concern.
-          </para>
-<!--h3--></section>
-<!--h2--></section>
-</section>