Author: kgiusti
Date: Tue Nov 22 22:11:23 2011
New Revision: 1205191
URL: http://svn.apache.org/viewvc?rev=1205191&view=rev
Log:
NO-JIRA: add message group examples to programming guide.
Added:
qpid/trunk/qpid/doc/book/src/Message-Groups-Guide.xml
Modified:
qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
qpid/trunk/qpid/doc/book/src/Using-message-groups.xml
Added: qpid/trunk/qpid/doc/book/src/Message-Groups-Guide.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Message-Groups-Guide.xml?rev=1205191&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Message-Groups-Guide.xml (added)
+++ qpid/trunk/qpid/doc/book/src/Message-Groups-Guide.xml Tue Nov 22 22:11:23
2011
@@ -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>
Modified: qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml?rev=1205191&r1=1205190&r2=1205191&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml (original)
+++ qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml Tue Nov 22
22:11:23 2011
@@ -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>
Modified: qpid/trunk/qpid/doc/book/src/Using-message-groups.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Using-message-groups.xml?rev=1205191&r1=1205190&r2=1205191&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Using-message-groups.xml (original)
+++ qpid/trunk/qpid/doc/book/src/Using-message-groups.xml Tue Nov 22 22:11:23
2011
@@ -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>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscr...@qpid.apache.org
