content/releases/qpid-broker-j-7.1.9/book/Java-Broker-Runtime-Consumers.html - qpid-site - Git at Google

 <!DOCTYPE html>
 <!--
  -
  - Licensed to the Apache Software Foundation (ASF) under one
  - or more contributor license agreements.  See the NOTICE file
  - distributed with this work for additional information
  - regarding copyright ownership.  The ASF licenses this file
  - to you under the Apache License, Version 2.0 (the
  - "License"); you may not use this file except in compliance
  - with the License.  You may obtain a copy of the License at
  -
  -   http://www.apache.org/licenses/LICENSE-2.0
  -
  - Unless required by applicable law or agreed to in writing,
  - software distributed under the License is distributed on an
  - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  - KIND, either express or implied.  See the License for the
  - specific language governing permissions and limitations
  - under the License.
  -
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   <head>
     <title>9.7.&#160;Consumers - Apache Qpid&#8482;</title>
     <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
     <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
     <link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
     <link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
     <script type="text/javascript">var _deferredFunctions = [];</script>
     <script type="text/javascript" src="/deferred.js" defer="defer"></script>
     <!--[if lte IE 8]>
       <link rel="stylesheet" href="/ie.css" type="text/css"/>
       <script type="text/javascript" src="/html5shiv.js"></script>
     <![endif]-->

     <!-- Redirects for `go get` and godoc.org -->
     <meta name="go-import"
           content="qpid.apache.org git https://gitbox.apache.org/repos/asf/qpid-proton.git"/>
     <meta name="go-source"
           content="qpid.apache.org
 https://github.com/apache/qpid-proton/blob/go1/README.md
 https://github.com/apache/qpid-proton/tree/go1{/dir}
 https://github.com/apache/qpid-proton/blob/go1{/dir}/{file}#L{line}"/>
   </head>
   <body>
     <div id="-content">
       <div id="-top" class="panel">
         <a id="-menu-link"><img width="16" height="16" src="" alt="Menu"/></a>

         <a id="-search-link"><img width="22" height="16" src="" alt="Search"/></a>

         <ul id="-global-navigation">
           <li><a id="-logotype" href="/index.html">Apache Qpid<sup>&#8482;</sup></a></li>
           <li><a href="/documentation.html">Documentation</a></li>
           <li><a href="/download.html">Download</a></li>
           <li><a href="/discussion.html">Discussion</a></li>
         </ul>
       </div>

       <div id="-menu" class="panel" style="display: none;">
         <div class="flex">
           <section>
             <h3>Project</h3>

             <ul>
               <li><a href="/overview.html">Overview</a></li>
               <li><a href="/components/index.html">Components</a></li>
               <li><a href="/releases/index.html">Releases</a></li>
             </ul>
           </section>

           <section>
             <h3>Messaging APIs</h3>

             <ul>
               <li><a href="/proton/index.html">Qpid Proton</a></li>
               <li><a href="/components/jms/index.html">Qpid JMS</a></li>
               <li><a href="/components/messaging-api/index.html">Qpid Messaging API</a></li>
             </ul>
           </section>

           <section>
             <h3>Servers and tools</h3>

             <ul>
               <li><a href="/components/broker-j/index.html">Broker-J</a></li>
               <li><a href="/components/cpp-broker/index.html">C++ broker</a></li>
               <li><a href="/components/dispatch-router/index.html">Dispatch router</a></li>
             </ul>
           </section>

           <section>
             <h3>Resources</h3>

             <ul>
               <li><a href="/dashboard.html">Dashboard</a></li>
               <li><a href="https://cwiki.apache.org/confluence/display/qpid/Index">Wiki</a></li>
               <li><a href="/resources.html">More resources</a></li>
             </ul>
           </section>
         </div>
       </div>

       <div id="-search" class="panel" style="display: none;">
         <form action="http://www.google.com/search" method="get">
           <input type="hidden" name="sitesearch" value="qpid.apache.org"/>
           <input type="text" name="q" maxlength="255" autofocus="autofocus" tabindex="1"/>
           <button type="submit">Search</button>
           <a href="/search.html">More ways to search</a>
         </form>
       </div>

       <div id="-middle" class="panel">
         <ul id="-path-navigation"><li><a href="/index.html">Home</a></li><li><a href="/releases/index.html">Releases</a></li><li><a href="/releases/qpid-broker-j-7.1.9/index.html">Qpid Broker-J 7.1.9</a></li><li><a href="/releases/qpid-broker-j-7.1.9/book/index.html">Apache Qpid Broker-J</a></li><li>9.7.&#160;Consumers</li></ul>

         <div id="-middle-content">
           <div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">9.7.&#160;Consumers</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="Java-Broker-Runtime-Flow-To-Disk.html">Prev</a>&#160;</td><th align="center" width="60%">Chapter&#160;9.&#160;Runtime</th><td align="right" width="20%">&#160;<a accesskey="n" href="Java-Broker-Runtime-Background-Recovery.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Java-Broker-Runtime-Consumers"></a>9.7.&#160;Consumers</h2></div></div></div><p>A Consumer is created when an AMQP connection wishes to receive messages from a message source (such as a
     Queue).  The standard behaviours of consumers are defined by the respective AMQP specification, however in addition
     to the standard behaviours a number of Qpid specific enhancements are available</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Runtime-Consumers-Prioirty"></a>9.7.1.&#160;Priority</h3></div></div></div><p>By default, when there are multiple competing consumers attached to the same message source, the Broker
       attempts to distribute messages from the queue in a "fair" manner. Some use cases require allocation of messages
       to consumers to be based on the "priority" of the consumer. Where there are multiple consumers having differing
       priorities, the Broker will always attempt to deliver a message to a higher priority consumer before attempting
       delivery to a lower priority consumer. That is, a lower priority consumer will only receive a message if no
       higher priority consumers currently have credit available to consume the message, or those consumers have declined
       to accept the message (for instance because it does not meet the criteria of any selectors associated with the
       consumer).</p><p>Where a consumer is created with no explicit priority provided, the consumer is given the highest possible
       priority.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e6102"></a>9.7.1.1.&#160;Creating a Consumer with a non-standard priority</h4></div></div></div><p>
         In AMQP 0-9 and 0-9-1 the priority of the consumer can be set by adding an entry into the table provided as the
         <code class="literal">arguments</code> field (known as the <code class="literal">filter</code> field on AMQP 0-9) of the
         <code class="literal">basic.consume</code> method. The key for the entry must be the literal short string
         <code class="literal">x-priority</code>, and the value of the entry must be an integral number in the range
         -2<sup>31</sup> to 2<sup>31</sup>-1.
       </p><p>
         In AMQP 0-10 the priority of the consumer can be set in the map provided as the <code class="literal">arguments</code>
         field of the <code class="literal">message.subscribe</code> method. The key for the entry must be the literal string
         <code class="literal">x-priority</code>, and the value of the entry must be an integral number in the range
         -2<sup>31</sup> to 2<sup>31</sup>-1.
       </p><p>
         In AMQP 1.0 the priority of the consumer is set in the <code class="literal">properties</code> map of the
         <code class="literal">attach</code> frame where the broker side of the link represents the sending side of the link.
         The key for the entry must be the literal string <code class="literal">priority</code>, and the value of the entry must
         be an integral number in the range -2<sup>31</sup> to 2<sup>31</sup>-1.
       </p><p>
         When using the Qpid JMS client for AMQP 0-9/0-9-1/0-10 the consumer priority can be set in the address being
         used for the Destination object.

         </p><div class="table"><a id="d0e6161"></a><p class="title"><strong>Table&#160;9.1.&#160;Setting the consumer priority</strong></p><div class="table-contents"><table border="1" summary="Setting the consumer priority"><colgroup><col /><col /></colgroup><thead><tr><th>Syntax</th><th>Example</th></tr></thead><tbody><tr><td>Addressing</td><td>myqueue : { link : { x-subscribe: { arguments : { x-priority : '10' } } } }</td></tr><tr><td>Binding URL</td><td>direct://amq.direct/myqueue/myqueue?x-qpid-replay-priority='10'</td></tr></tbody></table></div></div><p><br class="table-break" />
       </p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="Java-Broker-Runtime-Flow-To-Disk.html">Prev</a>&#160;</td><td align="center" width="20%"><a accesskey="u" href="Java-Broker-Runtime.html">Up</a></td><td align="right" width="40%">&#160;<a accesskey="n" href="Java-Broker-Runtime-Background-Recovery.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">9.6.&#160;Flow to Disk&#160;</td><td align="center" width="20%"><a accesskey="h" href="Apache-Qpid-Broker-J-Book.html">Home</a></td><td align="right" valign="top" width="40%">&#160;9.8.&#160;Background Recovery</td></tr></table></div></div>

           <hr/>

           <ul id="-apache-navigation">
             <li><a href="http://www.apache.org/">Apache</a></li>
             <li><a href="http://www.apache.org/licenses/">License</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="/security.html">Security</a></li>
             <li><a href="http://www.apache.org/"><img id="-apache-feather" width="48" height="14" src="" alt="Apache"/></a></li>
           </ul>

           <p id="-legal">
             Apache Qpid, Messaging built on AMQP; Copyright &#169; 2015
             The Apache Software Foundation; Licensed under
             the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache
             License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton,
             Proton, Apache, the Apache feather logo, and the Apache Qpid
             project logo are trademarks of The Apache Software
             Foundation; All other marks mentioned may be trademarks or
             registered trademarks of their respective owners
           </p>
         </div>
       </div>
     </div>
   </body>
 </html>
	<!DOCTYPE html>
	<!--
	-
	- Licensed to the Apache Software Foundation (ASF) under one
	- or more contributor license agreements. See the NOTICE file
	- distributed with this work for additional information
	- regarding copyright ownership. The ASF licenses this file
	- to you under the Apache License, Version 2.0 (the
	- "License"); you may not use this file except in compliance
	- with the License. You may obtain a copy of the License at
	-
	- http://www.apache.org/licenses/LICENSE-2.0
	-
	- Unless required by applicable law or agreed to in writing,
	- software distributed under the License is distributed on an
	- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	- KIND, either express or implied. See the License for the
	- specific language governing permissions and limitations
	- under the License.
	-
	-->
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<title>9.7. Consumers - Apache Qpid™</title>
	<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
	<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
	<link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
	<link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
	<script type="text/javascript">var _deferredFunctions = [];</script>
	<script type="text/javascript" src="/deferred.js" defer="defer"></script>
	<!--[if lte IE 8]>
	<link rel="stylesheet" href="/ie.css" type="text/css"/>
	<script type="text/javascript" src="/html5shiv.js"></script>
	<![endif]-->

	<!-- Redirects for `go get` and godoc.org -->
	<meta name="go-import"
	content="qpid.apache.org git https://gitbox.apache.org/repos/asf/qpid-proton.git"/>
	<meta name="go-source"
	content="qpid.apache.org
	https://github.com/apache/qpid-proton/blob/go1/README.md
	https://github.com/apache/qpid-proton/tree/go1{/dir}
	https://github.com/apache/qpid-proton/blob/go1{/dir}/{file}#L{line}"/>
	</head>
	<body>
	<div id="-content">
	<div id="-top" class="panel">
	<a id="-menu-link"><img width="16" height="16" src="" alt="Menu"/></a>

	<a id="-search-link"><img width="22" height="16" src="" alt="Search"/></a>

	<ul id="-global-navigation">
	<li><a id="-logotype" href="/index.html">Apache Qpid<sup>™</sup></a></li>
	<li><a href="/documentation.html">Documentation</a></li>
	<li><a href="/download.html">Download</a></li>
	<li><a href="/discussion.html">Discussion</a></li>
	</ul>
	</div>

	<div id="-menu" class="panel" style="display: none;">
	<div class="flex">
	<section>
	<h3>Project</h3>

	<ul>
	<li><a href="/overview.html">Overview</a></li>
	<li><a href="/components/index.html">Components</a></li>
	<li><a href="/releases/index.html">Releases</a></li>
	</ul>
	</section>

	<section>
	<h3>Messaging APIs</h3>

	<ul>
	<li><a href="/proton/index.html">Qpid Proton</a></li>
	<li><a href="/components/jms/index.html">Qpid JMS</a></li>
	<li><a href="/components/messaging-api/index.html">Qpid Messaging API</a></li>
	</ul>
	</section>

	<section>
	<h3>Servers and tools</h3>

	<ul>
	<li><a href="/components/broker-j/index.html">Broker-J</a></li>
	<li><a href="/components/cpp-broker/index.html">C++ broker</a></li>
	<li><a href="/components/dispatch-router/index.html">Dispatch router</a></li>
	</ul>
	</section>

	<section>
	<h3>Resources</h3>

	<ul>
	<li><a href="/dashboard.html">Dashboard</a></li>
	<li><a href="https://cwiki.apache.org/confluence/display/qpid/Index">Wiki</a></li>
	<li><a href="/resources.html">More resources</a></li>
	</ul>
	</section>
	</div>
	</div>

	<div id="-search" class="panel" style="display: none;">
	<form action="http://www.google.com/search" method="get">
	<input type="hidden" name="sitesearch" value="qpid.apache.org"/>
	<input type="text" name="q" maxlength="255" autofocus="autofocus" tabindex="1"/>
	<button type="submit">Search</button>
	<a href="/search.html">More ways to search</a>
	</form>
	</div>

	<div id="-middle" class="panel">
	<ul id="-path-navigation"><li><a href="/index.html">Home</a></li><li><a href="/releases/index.html">Releases</a></li><li><a href="/releases/qpid-broker-j-7.1.9/index.html">Qpid Broker-J 7.1.9</a></li><li><a href="/releases/qpid-broker-j-7.1.9/book/index.html">Apache Qpid Broker-J</a></li><li>9.7. Consumers</li></ul>

	<div id="-middle-content">
	<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">9.7. Consumers</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="Java-Broker-Runtime-Flow-To-Disk.html">Prev</a> </td><th align="center" width="60%">Chapter 9. Runtime</th><td align="right" width="20%"> <a accesskey="n" href="Java-Broker-Runtime-Background-Recovery.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Java-Broker-Runtime-Consumers"></a>9.7. Consumers</h2></div></div></div><p>A Consumer is created when an AMQP connection wishes to receive messages from a message source (such as a
	Queue). The standard behaviours of consumers are defined by the respective AMQP specification, however in addition
	to the standard behaviours a number of Qpid specific enhancements are available</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Runtime-Consumers-Prioirty"></a>9.7.1. Priority</h3></div></div></div><p>By default, when there are multiple competing consumers attached to the same message source, the Broker
	attempts to distribute messages from the queue in a "fair" manner. Some use cases require allocation of messages
	to consumers to be based on the "priority" of the consumer. Where there are multiple consumers having differing
	priorities, the Broker will always attempt to deliver a message to a higher priority consumer before attempting
	delivery to a lower priority consumer. That is, a lower priority consumer will only receive a message if no
	higher priority consumers currently have credit available to consume the message, or those consumers have declined
	to accept the message (for instance because it does not meet the criteria of any selectors associated with the
	consumer).</p><p>Where a consumer is created with no explicit priority provided, the consumer is given the highest possible
	priority.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e6102"></a>9.7.1.1. Creating a Consumer with a non-standard priority</h4></div></div></div><p>
	In AMQP 0-9 and 0-9-1 the priority of the consumer can be set by adding an entry into the table provided as the
	<code class="literal">arguments</code> field (known as the <code class="literal">filter</code> field on AMQP 0-9) of the
	<code class="literal">basic.consume</code> method. The key for the entry must be the literal short string
	<code class="literal">x-priority</code>, and the value of the entry must be an integral number in the range
	-2<sup>31</sup> to 2<sup>31</sup>-1.
	</p><p>
	In AMQP 0-10 the priority of the consumer can be set in the map provided as the <code class="literal">arguments</code>
	field of the <code class="literal">message.subscribe</code> method. The key for the entry must be the literal string
	<code class="literal">x-priority</code>, and the value of the entry must be an integral number in the range
	-2<sup>31</sup> to 2<sup>31</sup>-1.
	</p><p>
	In AMQP 1.0 the priority of the consumer is set in the <code class="literal">properties</code> map of the
	<code class="literal">attach</code> frame where the broker side of the link represents the sending side of the link.
	The key for the entry must be the literal string <code class="literal">priority</code>, and the value of the entry must
	be an integral number in the range -2<sup>31</sup> to 2<sup>31</sup>-1.
	</p><p>
	When using the Qpid JMS client for AMQP 0-9/0-9-1/0-10 the consumer priority can be set in the address being
	used for the Destination object.

	</p><div class="table"><a id="d0e6161"></a><p class="title"><strong>Table 9.1. Setting the consumer priority</strong></p><div class="table-contents"><table border="1" summary="Setting the consumer priority"><colgroup><col /><col /></colgroup><thead><tr><th>Syntax</th><th>Example</th></tr></thead><tbody><tr><td>Addressing</td><td>myqueue : { link : { x-subscribe: { arguments : { x-priority : '10' } } } }</td></tr><tr><td>Binding URL</td><td>direct://amq.direct/myqueue/myqueue?x-qpid-replay-priority='10'</td></tr></tbody></table></div></div><p><br class="table-break" />
	</p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="Java-Broker-Runtime-Flow-To-Disk.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="Java-Broker-Runtime.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="Java-Broker-Runtime-Background-Recovery.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">9.6. Flow to Disk </td><td align="center" width="20%"><a accesskey="h" href="Apache-Qpid-Broker-J-Book.html">Home</a></td><td align="right" valign="top" width="40%"> 9.8. Background Recovery</td></tr></table></div></div>

	<hr/>

	<ul id="-apache-navigation">
	<li><a href="http://www.apache.org/">Apache</a></li>
	<li><a href="http://www.apache.org/licenses/">License</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="/security.html">Security</a></li>
	<li><a href="http://www.apache.org/"><img id="-apache-feather" width="48" height="14" src="" alt="Apache"/></a></li>
	</ul>

	<p id="-legal">
	Apache Qpid, Messaging built on AMQP; Copyright © 2015
	The Apache Software Foundation; Licensed under
	the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache
	License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton,
	Proton, Apache, the Apache feather logo, and the Apache Qpid
	project logo are trademarks of The Apache Software
	Foundation; All other marks mentioned may be trademarks or
	registered trademarks of their respective owners
	</p>
	</div>
	</div>
	</div>
	</body>
	</html>