diff options
Diffstat (limited to 'qpid/doc/book/src/programming/Message-Groups-Guide.xml')
| -rw-r--r-- | qpid/doc/book/src/programming/Message-Groups-Guide.xml | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/qpid/doc/book/src/programming/Message-Groups-Guide.xml b/qpid/doc/book/src/programming/Message-Groups-Guide.xml new file mode 100644 index 0000000000..0ec6982bac --- /dev/null +++ b/qpid/doc/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> |