<?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>