qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From g...@apache.org
Subject svn commit: r961664 - /qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
Date Thu, 08 Jul 2010 09:30:11 GMT
Author: gsim
Date: Thu Jul  8 09:30:11 2010
New Revision: 961664

URL: http://svn.apache.org/viewvc?rev=961664&view=rev
Log:
Enabled prefetch for next receiver snippets, removed some confusion text on maps, minor clarifications
on prefetch.

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=961664&r1=961663&r2=961664&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 Thu Jul  8 09:30:11 2010
@@ -1475,7 +1475,13 @@ enable("qpid.messaging.io", DEBUG)
       Messaging API, a program can ask a session for the <quote>next
       receiver</quote>; that is, the receiver that is responsible for
       the next available message. The following example shows how this
-      is done in C++, Python, and .NET C#.</para>
+      is done in C++, Python, and .NET C#.
+      </para>
+
+      <para>Note that to use this pattern you must enable prefetching
+      for each receiver of interest so that thebroker will send
+      messages before a fetch call is made. See
+      <xref linkend="prefetch"/> for more on this.</para>
 
       <example>
 	<title>Receiving Messages from Multiple Sources</title>
@@ -1484,7 +1490,9 @@ enable("qpid.messaging.io", DEBUG)
 
 	<programlisting><![CDATA[
 Receiver receiver1 = session.createReceiver(address1);
+receiver1.setCapacity(10);
 Receiver receiver2 = session.createReceiver(address2);
+receiver2.setCapacity(10);
 
 Message message =  session.nextReceiver().fetch();
 std::cout << message.getContent() << std::endl;
@@ -1494,7 +1502,9 @@ session.acknowledge(); // acknowledge me
 	<para>Python:</para>
 	<programlisting><![CDATA[
 receiver1 = session.receiver(address1)
+receiver1.capacity = 10
 receiver2 = session.receiver(address)
+receiver2.capacity = 10
 message = session.next_receiver().fetch()
 print message.content
 session.acknowledge()
@@ -1503,7 +1513,9 @@ session.acknowledge()
 	<para>.NET C#:</para>
 	<programlisting><![CDATA[
 Receiver receiver1 = session.CreateReceiver(address1);
+receiver1.SetCapacity(10);
 Receiver receiver2 = session.CreateReceiver(address2);
+receiver2.SetCapacity(10);
 
 Message message = new Message();
 message =  session.NextReceiver().Fetch();
@@ -1587,17 +1599,23 @@ std::cout << request.getContent() << " -
       
       <para>Many messaging applications need to exchange data across
       languages and platforms, using the native datatypes of each
-      programming language. AMQP provides a set of portable datatypes,
-      but does not directly support a set of named type/value
-      pairs. Java JMS provides the <classname>MapMessage</classname>
-      interface, which allows sets of named type/value pairs, but does
-      not provide a set of portable datatypes.</para> 
+      programming language.</para> 
 
       <para>The Qpid Messaging API supports maps in message
-      content. Unlike JMS, any message can contain maps. These maps
-      are supported in each language using the conventions of the
-      language. In Java, we implement the
-      <classname>MapMessage</classname> interface; in Python, we
+      content. 
+
+      <footnote><para>Unlike JMS, there is not a specific message type for
+      map messages.</para></footnote>
+
+      These maps are supported in each language using
+      the conventions of the language. In Java, we implement the
+      <classname>MapMessage</classname> interface
+  
+      <footnote><para>Note that the Qpid JMS client supports
+      MapMessages whose values can be nested maps or lists. This is
+      not standard JMS behaviour.</para></footnote>
+
+      ; in Python, we
       support <classname>dict</classname> and
       <classname>list</classname> in message content; in C++, we
       provide the <classname>Variant::Map</classname> and
@@ -1773,14 +1791,14 @@ sender.send(message, true);
       <section>
 	<title>Batching Acknowledgements</title>
 
-	<para>Many of the simple examples we have shown retrieve a message and immediately
acknowledge it. Because each acknowledgement results in network traffic, you can dramatically
increase performance by acknowledging messages in batches. For instance, an application can
read a number of related messages, then acknowledge the entire batch, or an application can
acknowledge after a certain number of messages have been received or a certain time period
has elapsed. Messages are not removed from the broker until they are acknowledged, so guaranteed
delivery is still available when batching acknowledgements.</para>
+	<para>Many of the simple examples we have shown retrieve a message and immediately
acknowledge it. Because each acknowledgement results in network traffic, you can imporve efficiency
and increase performance by acknowledging messages in batches. For instance, an application
can receive and process a number of related messages, then acknowledge the entire batch, or
an application can acknowledge after a certain number of messages have been received or a
certain time period has elapsed.</para>
       </section>
 
 
-      <section>
+      <section id="prefetch">
 	<title>Prefetch</title>   
 
-	<para>By default, a receiver retrieves the next message from the server, one message
at a time, which provides intuitive results when writing and debugging programs, but does
not provide optimum performance. To create an input buffer, set the capacity of the receiver
to the size of the desired input buffer; for many applications, a capacity of 100 performs
well. </para>
+	<para>By default, a receiver retrieves the next message from the server, one message
at a time, in response to each fetch() call. This provides intuitive results when writing
and debugging programs, but does not provide optimum performance. By allowing the client to
prefetch messages in anticipation of fetch() calls, round-trips to the broker can be avoided
and the throughput for a receiver can be increased. To enable prefetching, set the capacity
of the receiver to the size of the desired input buffer; for many applications, a capacity
of 100 performs well.</para>
 
 <!--
 ###	sender: capacity of replay buffer (not yet acknowledged messages), these are resent with
failover



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


Mime
View raw message