qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jonat...@apache.org
Subject svn commit: r942181 - /qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
Date Fri, 07 May 2010 19:00:51 GMT
Author: jonathan
Date: Fri May  7 19:00:51 2010
New Revision: 942181

URL: http://svn.apache.org/viewvc?rev=942181&view=rev
Log:
Changes from today's discussion on map type tables.

Modified:
    qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.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=942181&r1=942180&r2=942181&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 Fri May  7 19:00:51 2010
@@ -1424,6 +1424,13 @@ std::cout << request.getContent() << " -
       portable datatypes.
       </para>
 
+      <tip>
+      <para>Because of the differences in type systems among
+      languages, the simplest way to provide portable messages is to
+      rely on maps, lists, strings, 64 bit signed integers, and
+      doubles for messages that need to be exchanged across languages
+      and platforms.</para>
+      </tip>
 
       <section id="section-Python-Maps">
 	<title>Qpid Maps in Python</title>
@@ -1465,12 +1472,10 @@ sender.send(message)
 	  </thead>
 	  <tbody>
    	    <row><entry>bool</entry><entry>bool</entry><entry>boolean</entry></row>
-	    <row><entry>integer</entry><entry>integer</entry><entry>long</entry></row>
-	    <row><entry>short</entry><entry>integer</entry><entry>short</entry></row>
+	    <row><entry>integer</entry><entry>long</entry><entry>long</entry></row>
 	    <row><entry>long</entry><entry>long</entry><entry>long</entry></row>
-	    <row><entry>float</entry><entry>float</entry><entry>float</entry></row>
 	    <row><entry>float</entry><entry>double</entry><entry>double</entry></row>
-	    <row><entry>string</entry><entry>unicode</entry><entry>java.lang.String</entry></row>
+	    <row><entry>unicode</entry><entry>string</entry><entry>java.lang.String</entry></row>
 	    <row><entry>uuid</entry><entry>qpid::types::Uuid</entry><entry>java.util.UUID</entry></row>
 	    <row><entry>dict</entry><entry>Variant::Map</entry><entry>java.util.Map</entry></row>
 	    <row><entry>list</entry><entry>Variant::List</entry><entry>java.util.List</entry></row>
@@ -1559,16 +1564,16 @@ sender.send(message, true);
 	  </thead>
 	  <tbody>
    	    <row><entry>bool</entry><entry>bool</entry><entry>boolean</entry></row>
-  	    <row><entry>unsigned char</entry><entry>string</entry><entry>char</entry></row>
-	    <row><entry>unsigned short int</entry><entry>integer</entry><entry>short</entry></row>
-	    <row><entry>unsigned int</entry><entry>integer</entry><entry>integer</entry></row>
-	    <row><entry>unsigned long</entry><entry>integer</entry><entry>long</entry></row>
-	    <row><entry>char</entry><entry>string</entry><entry>char</entry></row>
-	    <row><entry>short</entry><entry>integer</entry><entry>short</entry></row>
-	    <row><entry>int</entry><entry>integer</entry><entry>integer</entry></row>
-	    <row><entry>long</entry><entry>long</entry><entry>long</entry></row>
+  	    <row><entry>unsigned char</entry><entry>unicode</entry><entry>char</entry></row>
+	    <row><entry>unsigned short int</entry><entry>integer | long</entry><entry>short</entry></row>
+	    <row><entry>unsigned int</entry><entry>integer | long</entry><entry>integer</entry></row>
+	    <row><entry>unsigned long</entry><entry>integer | long</entry><entry>long</entry></row>
+	    <row><entry>char</entry><entry>unicode</entry><entry>char</entry></row>
+	    <row><entry>short</entry><entry>integer | long</entry><entry>short</entry></row>
+	    <row><entry>int</entry><entry>integer | long</entry><entry>integer</entry></row>
+	    <row><entry>long</entry><entry>integer | long</entry><entry>long</entry></row>
 	    <row><entry>float</entry><entry>float</entry><entry>float</entry></row>
-	    <row><entry>double, long double</entry><entry>float</entry><entry>double</entry></row>
+	    <row><entry>double</entry><entry>float</entry><entry>double</entry></row>
 	    <row><entry>string</entry><entry>unicode</entry><entry>java.lang.String</entry></row>
 	    <row><entry>qpid::types::Uuid</entry><entry>uuid</entry><entry>java.util.UUID</entry></row>
 	    <row><entry>Variant::Map</entry><entry>dict</entry><entry>java.util.Map</entry></row>
@@ -1579,130 +1584,8 @@ sender.send(message, true);
       </section>
 
       
-    </section>
-    <section>
-      <title>XML Exchange</title>
-
-      <para>The XML Exchange is an AMQP 0-10 custom exchange provided by the Apache
Qpid C++ broker. It allows messages to be filtered using XQuery; queries can address either
message properties or XML content in the body of the message.</para>
-
-      <para>An instance of the XML Exchange must be added before it can be used:</para>
-
-      <programlisting>
-$ qpid-config add exchange xml xml
-      </programlisting>
-
-      <para>When using the XML exchange, a sender's address string must provide a subject,
e.g. <literal>xml/weather</literal>.</para>
-
-      <para>If a receiver that is using the XML exchange also provides a subject, it
receives messages if the subject exactly matches a message's subject.</para>
-
-
-      <para>When using the XML Exchange, a receiver normally provides an XQuery as
an x-binding argument. If the query contains a context item (a path starting with <quote>.</quote>),
then it is applied to the content of the message, which must be well-formed XML. For instance,
<literal>./weather</literal> is a valid XQuery, which matches any message in which
the root element is named <literal>weather</literal>. Here is an address string
that contains this query:</para>
-
-      <programlisting><![CDATA[
-xml; {
- link: { 
-  x-bindings: [{ exchange:xml, key:weather, arguments:{xquery:"./weather"} }] 
- } 
-}
-  ]]></programlisting>
-
-      <para>Note that each x-binding is created in addition to any other bindings that
may exist, and each x-binding must include the exchange name, the key, and the xquery. If
you specify the subject in the address string (e.g. <literal>xml/weather; link ...</literal>),
it creates a binding that is used in addition to the x-bindings; the binding created for the
subject matches any message whose subject is <literal>weather</literal>, the binding
created for the x-binding matches any message that satisfies the query, i.e. any message with
a root element named <literal>weather</literal>.
-      </para>
-
-
-      <para>The XML Exchange can also be used to query message properties by declaring
an external variable with the same name as each property that is to be queried. The following
XQuery queries the <literal>control</literal> property, as well as the content
of the message:</para>
-
-      <programlisting><![CDATA[
-declare variable $control external;
-./message/id mod 2 = 1 or $control = 'end'
-]]></programlisting>
-
-      <para>If the XQuery addresses message content, and the message is not well-formed
XML, the message will not be received. If the XQuery does not query message content, the message
need not contain XML.</para>
-
-
-      <example>
-	<title>Using the XML Exchange with <command>drain</command></title>
-
-	<para>The following shows the arguments used with <command>drain</command>
to retrieve messages whose root element is named <literal>weather</literal>:</para>
-
-	<programlisting><![CDATA[
-$ ./drain -f "xml; {link:{x-bindings: [{exchange: xml, key:"weather", 
-arguments:{xquery:\"./weather\"}}]}}"
- ]]></programlisting> 
-      </example>
-
-      <example>
-	<title>Using the XML Exchange with C++</title>
-
-	<para>In C++, it is convenient to place an XQuery in a string, and use a <classname>stringstream</classname>
to add the query to the template for an address string that specifies an x-binding.</para>
-
-	<programlisting><![CDATA[
-std::string query = 
-  "let $w := ./weather "
-  "return $w/station = 'Raleigh-Durham International Airport (KRDU)' "
-  "   and $w/temperature_f > 50"
-  "   and $w/temperature_f - $w/dewpoint > 5"
-  "   and $w/wind_speed_mph > 7"
-  "   and $w/wind_speed_mph < 20";
-
-stringstream address;
-
-address << "xml; {"
-  " link: { "
-  "  x-bindings: [{ exchange: xml, key: weather, arguments: { xquery:\"" 
-     << query 
-     << "\"} }] "
-  " } "
-  "}";
-
-
-Receiver receiver = session.createReceiver(address.str());
-Message response = receiver.fetch();
-session.acknowledge();
-std::cout << response.getContent() << std::endl;
-
-      ]]></programlisting>
-      </example>
-
-
-      <example>
-	<title>Using the XML Exchange with Python</title>
-
-	<para>In Python, it is often convenient to place the query in
-	a separate string, and use the repr() value of the query
-	string in an address template string.</para>
-
-	<programlisting><![CDATA[
-# Set up the receiver
-  query = """
-   let $w := ./weather
-   return $w/station = 'Raleigh-Durham International Airport (KRDU)'
-      and $w/temperature_f > 50
-      and $w/temperature_f - $w/dewpoint > 5
-      and $w/wind_speed_mph > 7
-      and $w/wind_speed_mph < 20   """
-
-  address = """
-    xml; {
-       link: { 
-         x-bindings: [{ exchange: xml, key: weather, arguments: { xquery: %r} }] 
-       } 
-    }
-    """ % query
-
-  receiver = session.receiver(address)
-
-# Retrieve matching message from the receiver and print it
-
-  message = receiver.fetch(timeout=1)
-  print message.content
-  session.acknowledge()
-	]]></programlisting>
-      </example>
-
-    </section>
-
-    <section>
+</section> 
+        <section>
       <title>Performance</title>
       <para>
          Clients can often be made significantly faster by batching acknowledgements and
setting the capacity of receivers to allow prefetch. 	
@@ -1835,7 +1718,129 @@ else 
 
 
 
-  <section id="section-amqp0-10-mapping">
+  <section>
+      <title>XML Exchange</title>
+
+      <para>The XML Exchange is an AMQP 0-10 custom exchange provided by the Apache
Qpid C++ broker. It allows messages to be filtered using XQuery; queries can address either
message properties or XML content in the body of the message.</para>
+
+      <para>An instance of the XML Exchange must be added before it can be used:</para>
+
+      <programlisting>
+$ qpid-config add exchange xml xml
+      </programlisting>
+
+      <para>When using the XML exchange, a sender's address string must provide a subject,
e.g. <literal>xml/weather</literal>.</para>
+
+      <para>If a receiver that is using the XML exchange also provides a subject, it
receives messages if the subject exactly matches a message's subject.</para>
+
+
+      <para>When using the XML Exchange, a receiver normally provides an XQuery as
an x-binding argument. If the query contains a context item (a path starting with <quote>.</quote>),
then it is applied to the content of the message, which must be well-formed XML. For instance,
<literal>./weather</literal> is a valid XQuery, which matches any message in which
the root element is named <literal>weather</literal>. Here is an address string
that contains this query:</para>
+
+      <programlisting><![CDATA[
+xml; {
+ link: { 
+  x-bindings: [{ exchange:xml, key:weather, arguments:{xquery:"./weather"} }] 
+ } 
+}
+  ]]></programlisting>
+
+      <para>Note that each x-binding is created in addition to any other bindings that
may exist, and each x-binding must include the exchange name, the key, and the xquery. If
you specify the subject in the address string (e.g. <literal>xml/weather; link ...</literal>),
it creates a binding that is used in addition to the x-bindings; the binding created for the
subject matches any message whose subject is <literal>weather</literal>, the binding
created for the x-binding matches any message that satisfies the query, i.e. any message with
a root element named <literal>weather</literal>.
+      </para>
+
+
+      <para>The XML Exchange can also be used to query message properties by declaring
an external variable with the same name as each property that is to be queried. The following
XQuery queries the <literal>control</literal> property, as well as the content
of the message:</para>
+
+      <programlisting><![CDATA[
+declare variable $control external;
+./message/id mod 2 = 1 or $control = 'end'
+]]></programlisting>
+
+      <para>If the XQuery addresses message content, and the message is not well-formed
XML, the message will not be received. If the XQuery does not query message content, the message
need not contain XML.</para>
+
+
+      <example>
+	<title>Using the XML Exchange with <command>drain</command></title>
+
+	<para>The following shows the arguments used with <command>drain</command>
to retrieve messages whose root element is named <literal>weather</literal>:</para>
+
+	<programlisting><![CDATA[
+$ ./drain -f "xml; {link:{x-bindings: [{exchange: xml, key:"weather", 
+arguments:{xquery:\"./weather\"}}]}}"
+ ]]></programlisting> 
+      </example>
+
+      <example>
+	<title>Using the XML Exchange with C++</title>
+
+	<para>In C++, it is convenient to place an XQuery in a string, and use a <classname>stringstream</classname>
to add the query to the template for an address string that specifies an x-binding.</para>
+
+	<programlisting><![CDATA[
+std::string query = 
+  "let $w := ./weather "
+  "return $w/station = 'Raleigh-Durham International Airport (KRDU)' "
+  "   and $w/temperature_f > 50"
+  "   and $w/temperature_f - $w/dewpoint > 5"
+  "   and $w/wind_speed_mph > 7"
+  "   and $w/wind_speed_mph < 20";
+
+stringstream address;
+
+address << "xml; {"
+  " link: { "
+  "  x-bindings: [{ exchange: xml, key: weather, arguments: { xquery:\"" 
+     << query 
+     << "\"} }] "
+  " } "
+  "}";
+
+
+Receiver receiver = session.createReceiver(address.str());
+Message response = receiver.fetch();
+session.acknowledge();
+std::cout << response.getContent() << std::endl;
+
+      ]]></programlisting>
+      </example>
+
+
+      <example>
+	<title>Using the XML Exchange with Python</title>
+
+	<para>In Python, it is often convenient to place the query in
+	a separate string, and use the repr() value of the query
+	string in an address template string.</para>
+
+	<programlisting><![CDATA[
+# Set up the receiver
+  query = """
+   let $w := ./weather
+   return $w/station = 'Raleigh-Durham International Airport (KRDU)'
+      and $w/temperature_f > 50
+      and $w/temperature_f - $w/dewpoint > 5
+      and $w/wind_speed_mph > 7
+      and $w/wind_speed_mph < 20   """
+
+  address = """
+    xml; {
+       link: { 
+         x-bindings: [{ exchange: xml, key: weather, arguments: { xquery: %r} }] 
+       } 
+    }
+    """ % query
+
+  receiver = session.receiver(address)
+
+# Retrieve matching message from the receiver and print it
+
+  message = receiver.fetch(timeout=1)
+  print message.content
+  session.acknowledge()
+	]]></programlisting>
+      </example>
+
+    </section>
+
+<section id="section-amqp0-10-mapping">
     <title>The AMQP 0-10 mapping</title>
 
     <para>
@@ -2389,11 +2394,12 @@ amqp://guest:guest@test/test?sync_ack='t
 		  For secure applications, we suggest CRAM-MD5,
 		  DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not
 		  secure. The PLAIN method is secure only when used
-		  together with SSL. 
-		  For Kerberos, sasl_mechs must be set to GSSAPI,
-		  sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/, and 
-		  sasl_server must be set to the host for the SASL server, e.g. sasl.com. 
-		  SASL External is supported using SSL certification, e.g.
+		  together with SSL. For Kerberos, sasl_mechs must be
+		  set to GSSAPI, sasl_protocol must be set to the
+		  principal for the qpidd broker, e.g. qpidd/, and
+		  sasl_server must be set to the host for the SASL
+		  server, e.g. sasl.com.  SASL External is supported
+		  using SSL certification, e.g.
 		  <literal>ssl='true'&amp;sasl_mechs='EXTERNAL'</literal>
 	        </entry>
 	      </row>
@@ -2666,12 +2672,12 @@ producer.send(m);
 	  </thead>
 	  <tbody>
    	    <row><entry>boolean</entry><entry>bool</entry><entry>bool</entry></row>
-	    <row><entry>char</entry><entry>string<footnote><para>The
Python string will contain one Unicode character</para></footnote></entry><entry>int???
Java char is 16-bit</entry></row>
+	    <row><entry>char</entry><entry>unicode<footnote><para>The
Python string will contain one Unicode character</para></footnote></entry><entry>int</entry></row>
 	    <row><entry>short</entry><entry>integer</entry><entry>short</entry></row>
 	    <row><entry>integer</entry><entry>integer</entry><entry>int</entry></row>
-	    <row><entry>long</entry><entry>long integer</entry><entry>long</entry></row>
+	    <row><entry>long</entry><entry>integer</entry><entry>long</entry></row>
 	    <row><entry>float</entry><entry>float</entry><entry>float</entry></row>
-	    <row><entry>double</entry><entry>float</entry><entry>double,
long double</entry></row>
+	    <row><entry>double</entry><entry>float</entry><entry>double</entry></row>
 	    <row><entry>java.lang.String</entry><entry>unicode</entry><entry>std::string</entry></row>
 	    <row><entry>java.util.UUID</entry><entry>uuid</entry><entry>qpid::types::Uuid</entry></row>
 	    <row><entry>java.util.Map</entry><entry>dict</entry><entry>Variant::Map</entry></row>



---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org


Mime
View raw message