You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ro...@apache.org on 2017/05/24 14:58:46 UTC
[7/8] qpid-cpp git commit: QPID-7756: rename the book to better
reflect its content
QPID-7756: rename the book to better reflect its content
Project: http://git-wip-us.apache.org/repos/asf/qpid-cpp/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-cpp/commit/99dd7d38
Tree: http://git-wip-us.apache.org/repos/asf/qpid-cpp/tree/99dd7d38
Diff: http://git-wip-us.apache.org/repos/asf/qpid-cpp/diff/99dd7d38
Branch: refs/heads/master
Commit: 99dd7d3874fdad4a853cdea5a8535a0d2e6491b3
Parents: 6ef38e8
Author: Robert Gemmell <ro...@apache.org>
Authored: Wed May 24 15:46:00 2017 +0100
Committer: Robert Gemmell <ro...@apache.org>
Committed: Wed May 24 15:57:54 2017 +0100
----------------------------------------------------------------------
docs/book/Makefile | 2 +-
docs/book/src/Makefile.inc | 2 +-
docs/book/src/messaging-api/Makefile | 20 +
.../src/messaging-api/Message-Groups-Guide.xml | 163 +
.../src/messaging-api/Qpid-Messaging-API.xml | 4850 ++++++++++++++++++
docs/book/src/programming/Makefile | 20 -
.../src/programming/Message-Groups-Guide.xml | 163 -
.../programming/Programming-In-Apache-Qpid.xml | 4850 ------------------
8 files changed, 5035 insertions(+), 5035 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-cpp/blob/99dd7d38/docs/book/Makefile
----------------------------------------------------------------------
diff --git a/docs/book/Makefile b/docs/book/Makefile
index 6e97a0c..1fece83 100644
--- a/docs/book/Makefile
+++ b/docs/book/Makefile
@@ -17,7 +17,7 @@
# under the License.
#
-DIRS = src/cpp-broker src/programming
+DIRS = src/cpp-broker src/messaging-api
.PHONY: all $(DIRS)
http://git-wip-us.apache.org/repos/asf/qpid-cpp/blob/99dd7d38/docs/book/src/Makefile.inc
----------------------------------------------------------------------
diff --git a/docs/book/src/Makefile.inc b/docs/book/src/Makefile.inc
index 4de5733..071e183 100644
--- a/docs/book/src/Makefile.inc
+++ b/docs/book/src/Makefile.inc
@@ -17,7 +17,7 @@
# under the License.
#
-BOOK=$(wildcard *Book.xml Programming-In-Apache-Qpid.xml )
+BOOK=$(wildcard *Book.xml Qpid-Messaging-API.xml )
XML=$(wildcard *.xml) $(wildcard ../common/*.xml)
IMAGES=$(wildcard images/*.png)
CSS=$(wilcard ../common/css/*.css)
http://git-wip-us.apache.org/repos/asf/qpid-cpp/blob/99dd7d38/docs/book/src/messaging-api/Makefile
----------------------------------------------------------------------
diff --git a/docs/book/src/messaging-api/Makefile b/docs/book/src/messaging-api/Makefile
new file mode 100644
index 0000000..0266a0f
--- /dev/null
+++ b/docs/book/src/messaging-api/Makefile
@@ -0,0 +1,20 @@
+#
+# 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.
+#
+
+include ../Makefile.inc
http://git-wip-us.apache.org/repos/asf/qpid-cpp/blob/99dd7d38/docs/book/src/messaging-api/Message-Groups-Guide.xml
----------------------------------------------------------------------
diff --git a/docs/book/src/messaging-api/Message-Groups-Guide.xml b/docs/book/src/messaging-api/Message-Groups-Guide.xml
new file mode 100644
index 0000000..0ec6982
--- /dev/null
+++ b/docs/book/src/messaging-api/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>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org