QPID-4817: merged message grouping documentation from trunk to 0.22 branch.

The merge command was:
  svn merge -c 1480196 https://svn.apache.org/repos/asf/qpid/trunk/


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

2 files changed, 167 insertions, 15 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml b/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml
index 471d73f283..55f477e338 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml
@@ -30,10 +30,13 @@
   <section role="h2" id="Java-Broker-Queues-OtherTypes-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="Java-Broker-Queues-OtherTypes-Priority"
-        >priority-queues</link>, <link linkend="Java-Broker-Queues-OtherTypes-Sorted">sorted-queues</link>-, and
-        <link linkend="Java-Broker-Queues-OtherTypes-LVQ">last-value-queues</link> (LVQs). </para>
+      that they were sent, the Java Broker supports four additional queue types which allows for
+      alternative delivery behaviours. These are
+      <link linkend="Java-Broker-Queues-OtherTypes-Priority">priority-queues</link>,
+      <link linkend="Java-Broker-Queues-OtherTypes-Sorted">sorted-queues</link>-,
+      <link linkend="Java-Broker-Queues-OtherTypes-LVQ">last-value-queues</link> (LVQs), and
+      <link linkend="Java-Broker-Queues-OtherTypes-Message-Grouping">grouped queues</link>.
+    </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="Java-Broker-Queues-OtherTypes-CreateUsingConfig">configuration</link> or <link
@@ -244,12 +247,162 @@ managedBroker.createNewQueue("myqueue", null, true, arguments);]]></programlisti
     </section>
   </section>
 
+  <section role="h2" id="Java-Broker-Queues-OtherTypes-Message-Grouping">
+    <title>
+      Messaging Grouping
+    </title>
+    <para>
+      The broker allows messaging applications to classify a set of related messages as
+      belonging to a group.  This allows a message producer to indicate to the consumer
+      that a group of messages should be considered a single logical operation with
+      respect to the application.
+    </para>
+    <para>
+      The broker can use this group identification to enforce policies controlling how
+      messages from a given group can be distributed to consumers.  For instance, the
+      broker can be configured to guarantee all the messages from a particular group are
+      processed in order across multiple consumers.
+    </para>
+    <para>
+      For example, assume we have a shopping application that manages items in a virtual
+      shopping cart.  A user may add an item to their shopping cart, then change their
+      mind and remove it.  If the application sends an <emphasis>add</emphasis> message to the broker,
+      immediately followed by a <emphasis>remove</emphasis> message, they will be queued in the proper
+      order - <emphasis>add</emphasis>, followed by <emphasis>remove</emphasis>.
+    </para>
+    <para>
+      However, if there are multiple consumers, it is possible that once a consumer
+      acquires the <emphasis>add</emphasis> message, a different consumer may acquire the
+      <emphasis>remove</emphasis> message.  This allows both messages to be processed in parallel,
+      which could result in a "race" where the <emphasis>remove</emphasis> operation is incorrectly
+      performed before the <emphasis>add</emphasis> operation.
+    </para>
+    <section role="h3" id="Java-Broker-Queues-OtherTypes-GroupingMessages">
+      <title>
+        Grouping Messages
+      </title>
+      <para>
+        In order to group messages, the application would designate a particular
+        message header as containing a message's <emphasis>group identifier</emphasis>.  The group
+        identifier stored in that header field would be a string value set by the message
+        producer.  Messages from the same group would have the same group identifier
+        value. The key that identifies the header must also be known to the message
+        consumers.  This allows the consumers to determine a message's assigned group.
+      </para>
+      <para>
+        The header that is used to hold the group identifier, as well as the values used
+        as group identifiers, are totally under control of the application.
+      </para>
+    </section>
+    <section role="h3" id="Java-Broker-Queues-OtherTypes-BrokerRole">
+      <title>
+        The Role of the Broker in Message Grouping
+      </title>
+      <para>
+        The broker will apply the following processing on each grouped message:
+        <itemizedlist>
+          <listitem>Enqueue a received message on the destination queue.</listitem>
+          <listitem>Determine the message's group by examining the message's group identifier header.</listitem>
+          <listitem>Enforce <emphasis>consumption ordering</emphasis> among messages belonging
+          to the same group. <emphasis>Consumption ordering</emphasis> means one of two things
+          depending on how the queue has been configured.
+            <itemizedlist>
+              <listitem>In default mode, each group is assigned to a consumer for
+              the lifetime of the consumer.</listitem>
+              <listitem>In C++ compatibility mode (which gives the same behaviour
+              as the C++ Qpid Broker), the Broker enforces a looser guarantee, nameley that all the
+              <emphasis>currently unacknowledged messages</emphasis> in a group will be sent to the
+              same consumer.  This means that only one consumer can be processing messages from a particular
+              group at a given time.  When the consumer acknowledges all of its acquired
+              messages, then the broker <emphasis>may</emphasis> pass the next pending message
+              from that group to a different consumer.</listitem>
+            </itemizedlist>
+          </listitem>
+        </itemizedlist>
+      </para>
+      <para>
+        The absence of a value in the designated header field for grouping as treated as indicative
+        of a lack of desire for the message to be grouped. Messages with such a lack of a value will
+        be distributed to any available consumer.
+      </para>
+      <para>
+        Note that message grouping has no effect on queue browsers.
+      </para>
+      <para>
+        Note well that distinct message groups would not block each other from delivery.
+        For example, assume a queue contains messages from two different message groups -
+        say group "A" and group "B" - and they are enqueued such that "A"'s messages are
+        in front of "B". If the first message of group "A" is in the process of being
+        consumed by a client, then the remaining "A" messages are blocked, but the
+        messages of the "B" group are available for consumption by other consumers - even
+        though it is "behind" group "A" in the queue.
+      </para>
+    </section>
+    <section role="h3" id="Java-Broker-Queues-OtherTypes-BrokerConfig">
+      <title>
+        Broker Message Grouping Configuration
+      </title>
+      <para>
+        In order for the broker to determine a message's group, the key for the header
+        that contains the group identifier must be provided to the broker via
+        configuration.  This is done on a per-queue basis, when the queue is first
+        configured.
+      </para>
+      <para>
+        This means that message group classification is determined by the message's destination
+        queue.
+      </para>
+      <para>
+        Specifically, the queue "holds" the header key that is used to find the message's
+        group identifier.  All messages arriving at the queue are expected to use the same
+        header key for holding the identifer.  Once the message is enqueued, the broker
+        looks up the group identifier in the message's header, and classifies the message
+        by its group.
+      </para>
+      <para>
+        Message group support is specified by providing one or more of the following settings
+        in the arguments map that is used when declaring the queue (e.g. when calling
+        <code>AMQSession.createQueue()</code>).
+          <table>
+            <title>Queue Declare Message Group Configuration Arguments</title>
+            <tgroup cols="2">
+              <thead>
+                <row>
+                  <entry>Key</entry>
+                  <entry>Value</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>qpid.group_header_key</entry>
+                  <entry>The name of the message header that holds the group identifier value.
+                  The values in this header may be of any supported type (i.e. not just strings).
+                  </entry>
+                </row>
+                <row>
+                  <entry>qpid.shared_msg_group</entry>
+                  <entry>Provide a value of "1" to switch on
+                  <link linkend="Java-Broker-Queues-OtherTypes-BrokerRole">C++ compatibility mode</link></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+      </para>
+      <para>
+        It is important to note that there is no need to provide the actual group
+        identifer values that will be used. The broker learns these values as messages are
+        recieved.  Also, there is no practical limit - aside from resource limitations -
+        to the number of different groups that the broker can track at run time.
+      </para>
+    </section>
+  </section>
+
   <section role="h2" id="Java-Broker-Queues-OtherTypes-SetLowPrefetch">
-    <title>Low pre-fetch</title>
+    <title>Using low pre-fetch with special queue types</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
+      desirable behaviour when using priority, sorted, lvq or grouped 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
diff --git a/qpid/doc/book/src/programming/Message-Groups-Guide.xml b/qpid/doc/book/src/programming/Message-Groups-Guide.xml
index 3e5c549ff9..0ec6982bac 100644
--- a/qpid/doc/book/src/programming/Message-Groups-Guide.xml
+++ b/qpid/doc/book/src/programming/Message-Groups-Guide.xml
@@ -24,12 +24,12 @@
   <title>Using Message Groups</title>
   <para>
     This section describes how messaging applications can use the Message Group feature
-    provided by the C++ Broker.
+    provided by the Broker.
   </para>
   <note>
     The content of this section assumes the reader is familiar with the Message Group
-    feature as described in the AMQP Messaging Broker (C++) user's guide.  Please read the
-    section <emphasis>Using Message Groups</emphasis> in the user's guide before using the
+    feature as described in the AMQP Messaging Broker user's guide.  Please read the
+    message grouping section in the Broker user's guide before using the
     examples given in this section.
   </note>
   <section role="h2" id="messagegroups-setup">
@@ -73,17 +73,17 @@ MessageProducer sender = s.createProducer(d);
     </example>
     <para>
       The example code uses the x-declare map to specify the message group configuration
-      that should be used for the queue.  See the AMQP Messaging Broker (C++) user's guide
+      that should be used for the queue.  See the AMQP Messaging Broker user's guide
       for a detailed description of these arguments.  Note that the
-      qpid.group_header_key's value MUST be a string type.
+      qpid.group_header_key's value MUST be a string type if using the C++ broker.
     </para>
   </section>
   <section role="h2" id="messagegroups-sending">
     <title>Sending Grouped Messages</title>
     <para>
       When sending grouped messages, the client must add a message property containing the
-      group identifier to the outgoing message.  The group identifier must be a string
-      type.  The key used for the property must exactly match the value passed in the
+      group identifier to the outgoing message.  If using the C++ broker, the group identifier
+      must be a string type.  The key used for the property must exactly match the value passed in the
       'qpid.group_header_key' configuration argument.
     </para>
     <example>
@@ -157,8 +157,7 @@ sender.send(tmsg3);
       Since the broker enforces group policy when delivering messages, no special actions
       are necessary for receiving grouped messages from the broker.  However, applications
       must adhere to the rules for message group consumption as described in the AMQP
-      Messaging Broker (C++) user's guide.  Refer to the section <emphasis>Well Behaved
-      Consumers</emphasis> for details.
+      Messaging Broker user's guide.
     </para>
   </section>
 </section>