Author: kgiusti
Date: Wed Nov 30 14:39:14 2011
New Revision: 1208450
URL: http://svn.apache.org/viewvc?rev=1208450&view=rev
Log:
QPID-3417: add documentation for this feature.
Modified:
qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
qpid/trunk/qpid/doc/book/src/Running-CPP-Broker.xml
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=1208450&r1=1208449&r2=1208450&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 Wed Nov 30
14:39:14 2011
@@ -2628,7 +2628,7 @@ enable("qpid.messaging.io", DEBUG)
<row>
<entry>msg.redelivered</entry><entry>msg.{get,set}Redelivered()</entry><entry>dp.redelivered</entry>
</row>
-
<row><entry>msg.properties</entry><entry>msg.{get,set}Properties()</entry><entry>mp.application_headers</entry>
+
<row><entry>msg.properties</entry><entry>msg.getProperties()/msg.setProperty()</entry><entry>mp.application_headers</entry>
</row>
<row>
<entry>msg.content_type</entry><entry>msg.{get,set}ContentType()</entry><entry>mp.content_type</entry>
@@ -2637,17 +2637,85 @@ enable("qpid.messaging.io", DEBUG)
</tgroup>
</table>
- <para>The 0-10 mapping also recognises certain special property
- keys. If the properties contain entries for
<literal>x-amqp-0-10.app-id</literal>
- or <literal>x-amqp-0-10.content-encoding</literal>, the values will be
used to
- set <literal>message-properties.app-id</literal> and
- <literal>message-properties.content-encoding</literal> on the
- resulting 0-10 message transfer. Likewise if an incoming
- transfer has those properties set, they will be exposed in the
- same manner. In addition the routing key on incoming transfers
- will be exposed directly via the custom property with key
- <literal>x-amqp-0-10.routing-key</literal>.</para>
-
+ <section role="h3" id="section-amqp0-10-message-props">
+ <title>0-10 Message Property Keys</title>
+ <para>
+ The QPID Messaging API also recognises special message property keys
and
+ automatically provides a mapping to their corresponding AMQP 0-10
definitions.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ When sending a message, if the properties contain an entry for
+ <literal>x-amqp-0-10.app-id</literal>, its value will be used to
set the
+ <literal>message-properties.app-id</literal> property in the
outgoing
+ message. Likewise, if an incoming message has
+ <literal>message-properties.app-id</literal> set, its value can
be accessed
+ via the <literal>x-amqp-0-10.app-id</literal> message property
key.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When sending a message, if the properties contain an entry for
+ <literal>x-amqp-0-10.content-encoding</literal>, its value will
be used to
+ set the <literal>message-properties.content-encoding</literal>
property in
+ the outgoing message. Likewise, if an incoming message has
+ <literal>message-properties.content-encoding</literal> set, its
value can be
+ accessed via the <literal>x-amqp-0-10.content-encoding</literal>
message
+ property key.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The routing key
(<literal>delivery-properties.routing-key</literal>) in an
+ incoming messages can be accessed via the
+ <literal>x-amqp-0-10.routing-key</literal> message property.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the timestamp delivery property is set in an incoming message
+ (<literal>delivery-properties.timestamp</literal>), the
timestamp value will
+ be made available via the
<literal>x-amqp-0-10.timestamp</literal> message
+ property.
+ <footnote>
+ <para>
+ This special property is currently not supported by the Qpid
JMS client.
+ </para>
+ </footnote>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <example>
+ <title>Accessing the AMQP 0-10 Message Timestamp in Python</title>
+ <para>
+ The following code fragment checks for and extracts the message
timestamp from
+ a received message.
+ </para>
+ <programlisting lang="python">
+try:
+ msg = receiver.fetch(timeout=1)
+ if "x-amqp-0-10.timestamp" in msg.properties:
+ print("Timestamp=%s" % str(msg.properties["x-amqp-0-10.timestamp"]))
+except Empty:
+ pass
+ </programlisting>
+ </example>
+ <example>
+ <title>Accessing the AMQP 0-10 Message Timestamp in C++</title>
+ <para>
+ The same example, except in C++.
+ </para>
+ <programlisting lang="c++">
+messaging::Message msg;
+if (receiver.fetch(msg, messaging::Duration::SECOND*1)) {
+ if (msg.getProperties().find("x-amqp-0-10.timestamp") !=
msg.getProperties().end()) {
+ <![CDATA[std::cout << "Timestamp=" <<
msg.getProperties()["x-amqp-0-10.timestamp"].asString() << std::endl;]]>
+ }
+}
+ </programlisting>
+ </example>
+ </section>
</section>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="Message-Groups-Guide.xml"/>
Modified: qpid/trunk/qpid/doc/book/src/Running-CPP-Broker.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Running-CPP-Broker.xml?rev=1208450&r1=1208449&r2=1208450&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Running-CPP-Broker.xml (original)
+++ qpid/trunk/qpid/doc/book/src/Running-CPP-Broker.xml Wed Nov 30 14:39:14 2011
@@ -314,4 +314,72 @@ Store Options:
pages (1 read page = 64kiB)
</programlisting>
<!--h2--></section>
+<section role="h2" id="RASC-message-timestamps">
+ <title>Timestamping Received Messages</title>
+ <para>
+ The AMQP 0-10 specification defines a <emphasis>timestamp</emphasis>
message delivery
+ property. The timestamp delivery property is a
<emphasis>datetime</emphasis> value
+ that is written to each message that arrives at the broker. See the
description of
+ "message.delivery-properties" in the "Command Classes" section of the AMQP
0-10
+ specification for more detail.
+ </para>
+ <para>
+ See the <emphasis>Programming in Apache Qpid</emphasis> documentation for
+ information regarding how clients may access the timestamp value in
received
+ messages.
+ </para>
+ <para>
+ By default, this timestamping feature is disabled. To enable
timestamping, use the
+ <emphasis>enable-timestamp</emphasis> broker configuration option.
Setting the
+ enable-timestamp option to 'yes' will enable message timestamping:
+ </para>
+ <programlisting>
+./qpidd --enable-timestamp yes
+ </programlisting>
+ <para>
+ Message timestamping can also be enabled (and disabled) without restarting
the broker.
+ The QMF Broker management object defines two methods for accessing the
timestamp
+ configuration:
+ </para>
+ <table>
+ <title>QMF Management - Broker Methods for Managing the Timestamp
Configuration</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Method</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>getTimestampConfig</entry>
+ <entry>Get the message timestamping configuration. Returns True if
received messages are timestamped.</entry>
+ </row>
+ <row>
+ <entry>setTimestampConfig</entry>
+ <entry>Set the message timestamping configuration. Set True to
enable timestamping received messages, False to disable timestamping.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <example>
+ <title>Enabling Message Timestamping via QMF - Python</title>
+ <para>
+ The following code fragment uses these QMF method calls to enable
message timestamping.
+ </para>
+ <programlisting lang="python">
+# get the state of the timestamp configuration
+broker = self.qmf.getObjects(_class="broker")[0]
+rc = broker.getTimestampConfig()
+self.assertEqual(rc.status, 0)
+self.assertEqual(rc.text, "OK")
+print("The timestamp setting is %s" % str(rc.receive))
+
+# try to enable it
+rc = broker.setTimestampConfig(True)
+self.assertEqual(rc.status, 0)
+self.assertEqual(rc.text, "OK")
+ </programlisting>
+ </example>
+<!--h2--></section>
</section>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscr...@qpid.apache.org
