NO-JIRA: add message group examples to programming guide.

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

3 files changed, 159 insertions, 1 deletions

diff --git a/doc/book/src/Message-Groups-Guide.xml b/doc/book/src/Message-Groups-Guide.xml
new file mode 100644
index 0000000000..2824816ba0
--- /dev/null
+++ b/doc/book/src/Message-Groups-Guide.xml
@@ -0,0 +1,155 @@
+<?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="Message-Groups-Guide">
+  <title>Using Message Groups</title>
+  <para>
+    This section describes how messaging applications can use the Message Group feature
+    provided by the C++ 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
+    examples given in this section.
+  </note>
+  <section role="h2" id="messagegroups-setup">
+    <title>Creating Message Group Queues</title>
+    <para>
+      The following examples show how to create a message group queue that enforces
+      ordered group consumption across multiple consumers.
+    </para>
+    <example>
+      <title>Message Group Queue Creation - Python</title>
+      <programlisting lang="python">
+      sender = connection.session().sender("msg-group-q; {create:always, delete:receiver," +
+                                           " node: {x-declare: {arguments:" +
+                                           " {'qpid.group_header_key':'THE-GROUP'," +
+                                           "'qpid.shared_msg_group':1}}}}")
+      </programlisting>
+    </example>
+    <example>
+      <title>Message Group Queue Creation - C++</title>
+      <programlisting lang="c++">
+      std::string addr("msg-group-q; {create:always, delete:receiver, node: {x-declare: {arguments: {qpid.group_header_key:'THE-GROUP',qpid.shared_msg_group:1}}}}");
+      Sender sender = session.createSender(addr);
+      </programlisting>
+    </example>
+    <example>
+      <title>Message Group Queue Creation - Java</title>
+      <programlisting lang="java">
+      Session s = c.createSession(false, Session.CLIENT_ACKNOWLEDGE);
+      Destination d = (Destination) new AMQAnyDestination("msg-group-q; {create:always, delete:receiver, node: {x-declare: {arguments: {'qpid.group_header_key':'THE-GROUP','qpid.shared_msg_group':1}}}}");
+      MessageProducer sender = s.createProducer(d);
+      </programlisting>
+    </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
+      for a detailed description of these arguments.  Note that the
+      qpid.group_header_key's value MUST be a string type.
+    </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
+      'qpid.group_header_key' configuration argument.
+    </para>
+    <example>
+      <title>Sending Grouped Messages - Python</title>
+      <programlisting lang="python">
+      group = "A"
+      m = Message(content="some data", properties={"THE-GROUP": group})
+      sender.send(m)
+
+      group = "B"
+      m = Message(content="some other group's data", properties={"THE-GROUP": group})
+      sender.send(m)
+
+      group = "A"
+      m = Message(content="more data for group 'A'", properties={"THE-GROUP": group})
+      sender.send(m)
+      </programlisting>
+    </example>
+    <example>
+      <title>Sending Grouped Messages - C++</title>
+      <programlisting lang="C++">
+
+      const std::string groupKey("THE-GROUP");
+      {
+          Message msg("some data");
+          msg.getProperties()[groupKey] = std::string("A");
+          sender.send(msg);
+      }
+      {
+          Message msg("some other group's data");
+          msg.getProperties()[groupKey] = std::string("B");
+          sender.send(msg);
+      }
+      {
+          Message msg("more data for group 'A'");
+          msg.getProperties()[groupKey] = std::string("A");
+          sender.send(msg);
+      }
+      </programlisting>
+    </example>
+    <example>
+      <title>Sending Grouped Messages - Java</title>
+      <programlisting lang="java">
+      String groupKey = "THE-GROUP";
+
+      TextMessage tmsg1 = s.createTextMessage("some data");
+      tmsg1.setStringProperty(groupKey, "A");
+      sender.send(tmsg1);
+
+      TextMessage tmsg2 = s.createTextMessage("some other group's data");
+      tmsg2.setStringProperty(groupKey, "B");
+      sender.send(tmsg2);
+
+      TextMessage tmsg3 = s.createTextMessage("more data for group 'A'");
+      tmsg3.setStringProperty(groupKey, "A");
+      sender.send(tmsg3);
+      </programlisting>
+    </example>
+    <para>
+      The examples above send two groups worth of messages to the queue created in the
+      previous example.  Two messages belong to group "A", and one belongs to group
+      "B". Note that it is not necessary to complete sending one group's messages before
+      starting another.  Also note that there is no need to indicate to the broker when a
+      new group is created or an existing group retired - the broker tracks group state
+      automatically.
+    </para>
+  </section>
+  <section role="h2" id="messagegroups-receiving">
+    <title>Receiving Grouped Messages</title>
+    <para>
+      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.
+    </para>
+  </section>
+</section>
diff --git a/doc/book/src/Programming-In-Apache-Qpid.xml b/doc/book/src/Programming-In-Apache-Qpid.xml
index 4d72864cb1..e68fd4d21a 100644
--- a/doc/book/src/Programming-In-Apache-Qpid.xml
+++ b/doc/book/src/Programming-In-Apache-Qpid.xml
@@ -2649,6 +2649,9 @@ enable("qpid.messaging.io", DEBUG)
       <literal>x-amqp-0-10.routing-key</literal>.</para>
 
     </section>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Message-Groups-Guide.xml"/>
+
   </chapter>
 
 
diff --git a/doc/book/src/Using-message-groups.xml b/doc/book/src/Using-message-groups.xml
index 079b0bfb28..13d3f40a0b 100644
--- a/doc/book/src/Using-message-groups.xml
+++ b/doc/book/src/Using-message-groups.xml
@@ -199,7 +199,7 @@
         provided in the arguments map to enable message group support on a queue:
       </para>
       <table>
-        <title>Queue Declare/Addres Syntax Message Group Configuration Arguments</title>
+        <title>Queue Declare/Address Syntax Message Group Configuration Arguments</title>
         <tgroup cols="2">
           <thead>
             <row>