From da7718ef463775acc7d6fbecf2d64c1bbfc39fd8 Mon Sep 17 00:00:00 2001
From: Justin Ross <jross@apache.org>
Date: Tue, 19 Apr 2016 23:11:13 +0000
Subject: QPID-7207: Remove files and components that are obsolete or no longer
 in use; move doc and packaging pieces to the cpp subtree

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1740032 13f79535-47bb-0310-9956-ffa450edef68
---
 .../book/src/programming/Message-Groups-Guide.xml  | 163 +++++++++++++++++++++
 1 file changed, 163 insertions(+)
 create mode 100644 qpid/cpp/docs/book/src/programming/Message-Groups-Guide.xml

(limited to 'qpid/cpp/docs/book/src/programming/Message-Groups-Guide.xml')

diff --git a/qpid/cpp/docs/book/src/programming/Message-Groups-Guide.xml b/qpid/cpp/docs/book/src/programming/Message-Groups-Guide.xml
new file mode 100644
index 0000000000..0ec6982bac
--- /dev/null
+++ b/qpid/cpp/docs/book/src/programming/Message-Groups-Guide.xml
@@ -0,0 +1,163 @@
+<?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 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 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">
+    <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);
+String addr = "msg-group-q; {create:always, delete:receiver," +
+                             " node: {x-declare: {arguments:" +
+                             " {'qpid.group_header_key':'THE-GROUP'," +
+                             " 'qpid.shared_msg_group':1}}}}";
+Destination d = (Destination) new AMQAnyDestination(addr);
+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 user's guide
+      for a detailed description of these arguments.  Note that the
+      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.  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>
+      <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 user's guide.
+    </para>
+  </section>
+</section>
-- 
cgit v1.2.1