qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kgiu...@apache.org
Subject svn commit: r1208450 - in /qpid/trunk/qpid/doc/book/src: Programming-In-Apache-Qpid.xml Running-CPP-Broker.xml
Date Wed, 30 Nov 2011 14:39:15 GMT
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-subscribe@qpid.apache.org


Mime
View raw message