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 2012/08/12 21:19:53 UTC
svn commit: r1372183 [10/19] - in /qpid/site/docs/books/trunk_new: ./
AMQP-Messaging-Broker-CPP-Book/ AMQP-Messaging-Broker-CPP-Book/html/
AMQP-Messaging-Broker-CPP-Book/html/css/
AMQP-Messaging-Broker-CPP-Book/html/images/ AMQP-Messaging-Broker-CPP-Bo...
Added: qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/OtherQueueTypes.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/OtherQueueTypes.html?rev=1372183&view=auto
==============================================================================
--- qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/OtherQueueTypes.html (added)
+++ qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/OtherQueueTypes.html Sun Aug 12 19:19:49 2012
@@ -0,0 +1,115 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>2.10. Other Queue Types</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="prev" href="Qpid-Java-Build-HowTo.html" title="2.9. Qpid Java Build How To"><link rel="next" href="Java-Broker-Slow-Consumer-Disconnect.html" title="2.11. Slow Consumer Disconnect - User Guide"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpidâ¢</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.
org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">0.14 Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><
LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><
LI><A href="http://www.apache.org">Home</A></LI><LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Implemented in Java)</a></span> > <span class="breadcrumb-link"><a href="Qpid-Java-Broker-HowTos.html">How Tos</a></span> > <span class="breadcrumb-node">Other Queue Types</span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="OtherQueueTypes"></a>2.10. Other Queue Types</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="OtherQueueTypes-Introduction
"></a>2.10.1. Introduction</h3></div></div></div><p> In addition to the standard queue type where messages are delivered in the same order
+ that they were sent, the Java Broker supports three additional queue types which allows for
+ alternative delivery behaviours. These are <a class="link" href="OtherQueueTypes.html#OtherQueueTypes-Priority" title="2.10.2. Priority Queues">priority-queues</a>, <a class="link" href="OtherQueueTypes.html#OtherQueueTypes-Sorted" title="2.10.3. Sorted Queues">sorted-queues</a>-, and
+ <a class="link" href="OtherQueueTypes.html#OtherQueueTypes-LVQ" title="2.10.4. Last Value Queues (LVQ)">last-value-queues</a> (LVQs). </p><p> In the following sections, the semantics of each queue type is described, followed by a
+ description of how instances of these queue can be created via <a class="link" href="OtherQueueTypes.html#OtherQueueTypes-CreateUsingConfig" title="2.10.5.1. Using configuration">configuration</a> or <a class="link" href="OtherQueueTypes.html#OtherQueueTypes-CreateUsingJmsOrJmx" title="2.10.5.2. Using JMS or AMQP">programmatically</a>. </p><p>The final section discusses the importance of using a <a class="link" href="OtherQueueTypes.html#OtherQueueTypes-SetLowPrefetch" title="2.10.6. Low pre-fetch">low client pre-fetch</a> with these queued.
+ </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="OtherQueueTypes-Priority"></a>2.10.2. Priority Queues</h3></div></div></div><p>In a priority queue, messages on the queue are delivered in an order determined by the
+ <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getJMSPriority()" target="_top">JMS priority message
+ header</a> within the message. By default Qpid supports the 10 priority levels mandated
+ by JMS, with priority value 0 as the lowest priority and 9 as the highest. </p><p>It is possible to reduce the effective number of priorities if desired.</p><p>JMS defines the <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#DEFAULT_PRIORITY" target="_top">
+ default message priority</a> as 4. Messages sent without a specified priority use this
+ default. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="OtherQueueTypes-Sorted"></a>2.10.3. Sorted Queues</h3></div></div></div><p>Sorted queues allow the message delivery order to be determined by value of an arbitrary
+ <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getStringProperty()" target="_top">JMS message
+ property</a>. Sort order is alpha-numeric and the property value must have a type
+ java.lang.String.</p><p>Messages sent to a sorted queue without the specified JMS message property will be
+ inserted into the 'last' position in the queue.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="OtherQueueTypes-LVQ"></a>2.10.4. Last Value Queues (LVQ)</h3></div></div></div><p>LVQs (or conflation queues) are special queues that automatically discard any message when
+ a newer message arrives with the same key value. The key is specified by arbitrary <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Message.html#getPropertyNames()" target="_top">JMS message
+ property</a>.</p><p>An example of an LVQ might be where a queue represents prices on a stock exchange: when
+ you first consume from the queue you get the latest quote for each stock, and then as new
+ prices come in you are sent only these updates. </p><p>Like other queues, LVQs can either be browsed or consumed from. When browsing an
+ individual subscriber does not remove the message from the queue when receiving it. This
+ allows for many subscriptions to browse the same LVQ (i.e. you do not need to create and bind
+ a separate LVQ for each subscriber who wishes to receive the contents of the LVQ).</p><p>Messages sent to an LVQ without the specified property will be delivered as normal and
+ will never be "replaced".</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="OtherQueueTypes-Create"></a>2.10.5. Creating a Priority, Sorted or LVQ Queue</h3></div></div></div><p>To create a priority, sorted or LVQ queue, it can be defined in the virtualhost
+ configuration file, or the queue can be created programmtically from a client via AMQP (using
+ an extension to JMS), or using JMX. These methods are described below. </p><p>Once a queue is created you cannot change its type (without deleting it and re-creating).
+ Also note you cannot currently mix the natures of these queue types, for instance, you cannot
+ define a queue which it both an LVQ and a priority-queue.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="OtherQueueTypes-CreateUsingConfig"></a>2.10.5.1. Using configuration</h4></div></div></div><p>To create a priority, sorted or LVQ queue within configuration, add the appropriate xml
+ to the virtualhost.xml configuration file within the <code class="varname">queues</code>
+ element.</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="OtherQueueTypes-CreateUsingConfig-Priority"></a>Priority</h5></div></div></div><p> To defining a priority queue, add a <priority>true</priority> element. By
+ default the queue will have 10 distinct priorities. </p><div class="example"><a name="id2502411"></a><p class="title"><b>Example 2.1. Configuring a priority queue</b></p><div class="example-contents"><pre class="programlisting"><queue>
+ <name>myqueue</name>
+ <myqueue>
+ <exchange>amq.direct</exchange>
+ <priority>true</priority>
+ </myqueue>
+</queue></pre></div></div><br class="example-break"><p> If you require fewer priorities, it is possible to specify a
+ <code class="varname">priorities</code> element (whose value is a integer value between 2 and 10
+ inclusive) which will give the queue that number of distinct priorities. When messages are
+ sent to that queue, their effective priority will be calculated by partitioning the
+ priority space. If the number of effective priorities is 2, then messages with priority
+ 0-4 are treated the same as "lower priority" and messages with priority 5-9 are treated
+ equivalently as "higher priority". </p><div class="example"><a name="id2502442"></a><p class="title"><b>Example 2.2. Configuring a priority queue with fewer priorities</b></p><div class="example-contents"><pre class="programlisting"><queue>
+ <name>myqueue</name>
+ <myqueue>
+ <exchange>amq.direct</exchange>
+ <priority>true</priority>
+ <priorities>4</priorities>
+ </myqueue>
+</queue></pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="OtherQueueTypes-CreateUsingConfig-Sorted"></a>Sorted</h5></div></div></div><p> To define a sorted queue, add a <code class="varname">sortKey</code> element. The value of the
+ <code class="varname">sortKey</code> element defines the message property to use the value of when
+ sorting the messages put onto the queue. </p><div class="example"><a name="id2502483"></a><p class="title"><b>Example 2.3. Configuring a sorted queue</b></p><div class="example-contents"><pre class="programlisting"><queue>
+ <name>myqueue</name>
+ <myqueue>
+ <exchange>amq.direct</exchange>
+ <sortKey>message-property-to-sort-by</sortKey>
+ </myqueue>
+</queue></pre></div></div><br class="example-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="OtherQueueTypes-CreateUsingConfig-LVQ"></a>LVQ</h5></div></div></div><p> To define a LVQ, add a <code class="varname">lvq</code> element with the value
+ <code class="constant">true</code>. Without any further configuration this will define an LVQ
+ which uses the JMS message property <code class="constant">qpid.LVQ_key</code> as the key for
+ replacement. </p><div class="example"><a name="id2502527"></a><p class="title"><b>Example 2.4. Configuring a LVQ queue</b></p><div class="example-contents"><pre class="programlisting"><queue>
+ <name>myqueue</name>
+ <myqueue>
+ <exchange>amq.direct</exchange>
+ <lvq>true</lvq>
+ </myqueue>
+</queue></pre></div></div><br class="example-break"><p> If you wish to define your own property then you can do so using the
+ <code class="varname">lvqKey</code> element.</p><div class="example"><a name="id2502550"></a><p class="title"><b>Example 2.5. Configuring a LVQ queue with custom message property name</b></p><div class="example-contents"><pre class="programlisting"><queue>
+ <name>myqueue</name>
+ <myqueue>
+ <exchange>amq.direct</exchange>
+ <lvq>true</lvq>
+ <lvqKey>ISIN</lvqKey>
+ </myqueue>
+</queue></pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="OtherQueueTypes-CreateUsingJmsOrJmx"></a>2.10.5.2. Using JMS or AMQP</h4></div></div></div><p>To create a priority, sorted or LVQ queue programmatically from JMX or using a Qpid
+ extension to JMS, pass the appropriate queue-declare arguments.</p><div class="table"><a name="id2502584"></a><p class="title"><b>Table 2.11. </b></p><div class="table-contents"><table border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Queue type</th><th>Argument name</th><th>Argument name</th><th>Argument Description</th></tr></thead><tbody><tr><td>priority</td><td>priorities</td><td>java.lang.Integer</td><td>Specifies a priority queue with given number priorities</td></tr><tr><td>sorted</td><td>qpid.queue_sort_key</td><td>java.lang.String</td><td>Specifies sorted queue with given message property used to sort the
+ entries</td></tr><tr><td>lvq</td><td>qpid.last_value_queue_key</td><td>java.lang.String</td><td>Specifies lvq queue with given message property used to conflate the
+ entries</td></tr></tbody></table></div></div><br class="table-break"><p>The following example illustrates the creation of the a LVQ queue from a
+ javax.jms.Session object. Note that this utilises a Qpid specific extension to JMS and
+ involves casting the session object back to its Qpid base-class.</p><div class="example"><a name="id2503422"></a><p class="title"><b>Example 2.6. Creation of an LVQ using the Qpid extension to JMS</b></p><div class="example-contents"><pre class="programlisting">Map<String,Object> arguments = new HashMap<String, Object>();
+arguments.put("qpid.last_value_queue_key","ISIN");
+((AMQSession<?,?>) session).createQueue(queueName, autoDelete, durable, exclusive, arguments);</pre></div></div><br class="example-break"><p> The following example illustrates the creation of the sorted queue from a the JMX
+ interface using the ManagedBroker interface. </p><div class="example"><a name="id2503443"></a><p class="title"><b>Example 2.7. Creation of a sorted queue using JMX</b></p><div class="example-contents"><pre class="programlisting">Map<String, Object> environment = new HashMap<String, Object>();
+environment.put(JMXConnector.CREDENTIALS, new String[] {"admin","password"});
+// Connect to service
+JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi");
+JMXConnector jmxConnector = JMXConnectorFactory.connect(url, environment);
+MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection();
+// Object name for ManagedBroker for virtualhost myvhost
+ObjectName objectName = new ObjectName("org.apache.qpid:type=VirtualHost.VirtualHostManager,VirtualHost=myvhost");
+// Get the ManagedBroker object
+ManagedBroker managedBroker = JMX.newMBeanProxy(mbsc, objectName, ManagedBroker.class);;
+
+// Create the queue passing arguments
+Map<String,Object> arguments = new HashMap<String, Object>();
+arguments.put("qpid.queue_sort_key","myheader");
+managedBroker.createNewQueue("myqueue", null, true, arguments);</pre></div></div><br class="example-break"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="OtherQueueTypes-SetLowPrefetch"></a>2.10.6. Low pre-fetch</h3></div></div></div><p>Qpid clients receive buffered messages in batches, sized according to the pre-fetch value.
+ The current default is 500. </p><p>However, if you use the default value you will probably <span class="emphasis"><em>not</em></span> see
+ desirable behaviour when using priority, sorted or lvq queues. Once the broker has sent a
+ message to the client its delivery order is then fixed, regardless of the special behaviour of
+ the queue. </p><p>For example, if using a priority queue and a prefetch of 100, and 100 messages arrive with
+ priority 2, the broker will send these messages to the client. If then a new message arrives
+ will priority 1, the broker cannot leap frog messages of lower priority. The priority 1 will
+ be delivered at the front of the next batch of messages to be sent to the client.</p><p> So, you need to set the prefetch values for your client (consumer) to make this sensible.
+ To do this set the Java system property <code class="varname">max_prefetch</code> on the client
+ environment (using -D) before creating your consumer. </p><p>A default for all client connections can be set via a system property: </p><pre class="programlisting">
+-Dmax_prefetch=1
+</pre><p> The prefetch can be also be adjusted on a per connection basis by adding a
+ <code class="varname">maxprefetch</code> value to the <a class="ulink" href="../../Programming-In-Apache-Qpid/html/QpidJNDI.html#section-jms-connection-url" target="_top">Connection URLs</a>
+ </p><pre class="programlisting">
+amqp://guest:guest@client1/development?maxprefetch='1'&brokerlist='tcp://localhost:5672'
+</pre><p>Setting the Qpid pre-fetch to 1 will give exact queue-type semantics as perceived by the
+ client however, this brings a performance cost. You could test with a slightly higher
+ pre-fetch to trade-off between throughput and exact semantics.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Qpid-Java-Build-HowTo.html">Prev</a>Â </td><td width="20%" align="center"><a accesskey="u" href="Qpid-Java-Broker-HowTos.html">Up</a></td><td width="40%" align="right">Â <a accesskey="n" href="Java-Broker-Slow-Consumer-Disconnect.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.9.Â
+ Qpid Java Build How To
+  </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.11. Slow Consumer Disconnect - User Guide</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org