| <div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">5.6. MessageConsumer</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding-MessageProducer.html">Prev</a> </td><th align="center" width="60%">Chapter 5. Understanding the Client</th><td align="right" width="20%"> <a accesskey="n" href="JMS-Client-0-8-Client-Understanding-Destinations.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="JMS-Client-0-8-Client-Understanding-MessageConsumer"></a>5.6. MessageConsumer</h2></div></div></div><p>A MessageConsumer receives messages from a Queue or Topic.</p><p>MessageConsumer objects are created from the Session.</p><p>Qpid JMS MessageConsumers have a number of features above that required by JMS. These are | |
| described in the sub-sections that follow.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-MessageConsumer-ConsumerSideEffect"></a>5.6.1. Consumers have Exchange/Queue Declaration and Binding Side Effect</h3></div></div></div><p>By default, calling <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/Session.html#createConsumer(javax.jms.Destination)" target="_top">Session#createConsumer()</a> will cause:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>If the exchange does not exist on the Broker, it will be created. The exchange is | |
| specified by the Binding URL associated with the Destination.</p></li><li class="listitem"><p>If the queue does not exist on the Broker, it will be created. The queue is | |
| specified by the Binding URL associated with the Destination.</p></li><li class="listitem"><p>If there is no binding between the exchange and queue, a binding will be created | |
| using the routingkey as a bindingkey. The exchange, queue and routing key are specified | |
| by the Binding URL associated with the Destination.</p></li></ol></div><p>The exchange declare, queue declare and bind side effects can be suppressed using system | |
| properties <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-DeclareExchanges"><code class="literal">qpid.declare_exchanges</code></a>, <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-DeclareQueues"><code class="literal">qpid.declare_queues</code></a> and <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-BindQueues"><code class="literal">qpid.bind_queues</code></a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-MessageConsumer-TopicSubscriptions"></a>5.6.2. Topic Subscriptions</h3></div></div></div><p>The Client implements each subscription to a Topic as separate queue on the | |
| Broker. From the perspective of the JMS application this implementational detail is | |
| irrelevant: the application never needs to directly address these queues. However, these | |
| details are important when considering Management and Operational concerns.</p><p>Durable topic subscriptions use a <span class="emphasis"><em>durable</em></span> and | |
| <span class="emphasis"><em>exclusive</em></span> queue named as follows:</p><pre class="programlisting"> | |
| clientid: + subscriptionId | |
| </pre><p>where <code class="literal">subscriptionId</code> is that passed to the <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/Session.html#createDurableSubscriber(javax.jms.Topic,%20java.lang.String)" target="_top">Session#createDurableSubscriber(javax.jms.Topic,java.lang.String)</a></p><p>Calling <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/Session.html#unsubscribe(java.lang.String)" target="_top">Session#unsubscribe(java.lang.String)</a> deletes the underlying queue.</p><p>Non-durable topic subscriptions use a <span class="emphasis"><em>non-durable</em></span>, | |
| <span class="emphasis"><em>exclusive</em></span> and <span class="emphasis"><em>auto-delete</em></span> queue named as | |
| follows:</p><pre class="programlisting"> | |
| tmp + _ + ip + _ + port + _ + sequence | |
| </pre><p>where <code class="literal">ip</code> is the ip address of the client with dots replaced by | |
| underscores, <code class="literal">port</code> is the ephemeral port number assigned to the client's | |
| connection, and <code class="literal">sequence</code> is a sequence number.</p><p>Closing the consumer (or closing the connection) will delete the underlying | |
| queue.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-MessageConsumer-MaximumDeliveryCount"></a>5.6.3. Maximum Delivery Count</h3></div></div></div><p>With this feature, the Broker keeps track of a number of times a message has been | |
| delivered to a consumer. If the count ever exceeds a threshold value, the Broker moves the | |
| message to a dead letter queue (DLQ). This is used to prevent poison messages preventing a | |
| system's operation. This client feature requires support for the corresponding feature by | |
| the Broker.</p><p>When using this feature, the application must either set system property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-RejectBehaviour">qpid.reject.behaviour</a> or | |
| the Binding URL option <a class="link" href="JMS-Client-0-8-Binding-URL.html#JMS-Client-0-8-Binding-URL-Options-RejectBehaviour"><code class="literal">rejectbehaviour</code></a> to the value | |
| <code class="literal">server</code>.</p><p>See <a class="link" href="../../java-broker/book/Java-Broker-Runtime-Handling-Undeliverable-Messages.html#Java-Broker-Runtime-Handling-Undeliverable-Messages-Maximum-Delivery-Count" target="_top"> Handling Undeliverable Messages</a> within the Apache Qpid Broker-J book for full details of | |
| the functioning of this feature.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The optional JMS message header <code class="literal">JMSXDeliveryCount</code> is | |
| <span class="emphasis"><em>not</em></span> supported.</p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding-MessageProducer.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="JMS-Client-0-8-Client-Understanding.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="JMS-Client-0-8-Client-Understanding-Destinations.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">5.5. MessageProducer </td><td align="center" width="20%"><a accesskey="h" href="JMS-Client-Book.html">Home</a></td><td align="right" valign="top" width="40%"> 5.7. Destinations</td></tr></table></div></div> |