| <div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">5.5. MessageProducer</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding-Session.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-MessageConsumer.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-MessageProducer"></a>5.5. MessageProducer</h2></div></div></div><p>A MessageProducer sends a message an <span class="emphasis"><em>Exchange</em></span>. It is the Exchange | |
| (within the Broker) that routes the message to zero or more queue(s). Routing is performed | |
| according to rules expressed as <span class="emphasis"><em>bindings</em></span> between the exchange and queues | |
| and a <span class="emphasis"><em>routing key</em></span> included with each message.</p><p>To understand how this mechanism is used to deliver messages to queues and topics, see | |
| <a class="link" href="../../java-broker/book/Java-Broker-Concepts-Exchanges.html" target="_top">Exchanges</a> | |
| within the Apache Qpid Broker-J book.</p><p>It is important to understand that when synchronous publish is not exlicitly enabled, | |
| <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/MessageProducer.html#send(javax.jms.Message)" target="_top">MessageProducer#send()</a> is <span class="emphasis"><em>asynchronous</em></span> in nature. When #send() | |
| returns to the application, the application cannot be certain if the Broker has received the | |
| message. The Client may not have yet started to send the message, the message could | |
| residing in a TCP/IP buffer, or the messages could be in some intermediate buffer within the | |
| Broker. If the application requires certainty the message has been received by the Broker, a | |
| <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/Session.html#SESSION_TRANSACTED" target="_top">transactional | |
| session</a> | |
| <span class="emphasis"><em>must</em></span> be used, or synchronous publishing must be enabled using either the | |
| <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-SyncPublish">system property</a> or the | |
| <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-ConnectionOptions-SyncPublish">connection URL | |
| option</a>.</p><p>Qpid JMS MessageProducers 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-MessageProducer-MandatoryMessage"></a>5.5.1. Mandatory Messages</h3></div></div></div><p>With this feature, publishing a message with a routing key for which no binding exists | |
| on the exchange will result in the message being returned to the publisher's | |
| connection.</p><p>The Message is returned to the application in an asynchronous fashion via the | |
| Connection's <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/ExceptionListener.html" target="_top">ExceptionListener</a>. When a message is returned, it will be invoked with a | |
| JMSException whose linked exception is an <a class="link" href="JMS-Client-0-8-Appendix-Exceptions-AMQNoRouteException" target="_top">AMQNoRouteException</a>. | |
| The returned message is available to the application by calling | |
| AMQNoRouteException#getUndeliveredMessage(). The ExceptionListener will be invoked exactly | |
| once for each returned message.</p><p>If synchronous publishing has been enabled, and a mandatory message is returned, the | |
| <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/MessageProducer.html#send(javax.jms.Message)" target="_top">MessageProducer#send()</a> method will throw a JMSException. | |
| </p><p>The mandatory message feature is turned <span class="emphasis"><em>on</em></span> by default for Queue | |
| destinations and <span class="emphasis"><em>off</em></span> for Topic destinations. This can be overridden | |
| using system properties <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-DefaultMandatory"><code class="literal">qpid.default_mandatory</code></a> and <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-DefaultMandatoryTopic"><code class="literal">qpid.default_mandatory_topic</code></a> for Queues and Topics | |
| respectively.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If this the mandatory flag is not set, the Broker will treat <a class="link" href="../../java-broker/book/Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-UnroutableMessage" target="_top">the messages as unroutable</a>.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-MessageProducer-CloseWhenNoRoute"></a>5.5.2. Close When No Route</h3></div></div></div><p>With this feature, if a mandatory message is published with a routing key for which no | |
| binding exists on the exchange the Broker will close the connection. This client feature | |
| requires support for the corresponding feature by the Broker.</p><p>To enable or disable from the client, use the Connection URL option <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-ConnectionOptions-CloseWhenNoRoute"><code class="literal">closeWhenNoRoute</code></a>.</p><p>See <a class="link" href="../../java-broker/book/Java-Broker-Runtime-Close-Connection-When-No-Route.html" target="_top"> | |
| Closing client connections on unroutable mandatory messages</a> within the Apache Qpid Broker-J | |
| book for full details of the functioning of this feature.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-MessageProducer-ImmediateMessage"></a>5.5.3. Immediate Messages</h3></div></div></div><p>This feature is defined in <a class="link" href="http://www.amqp.org" target="_top">AMQP specifications</a>.</p><p>When this feature is enabled, when publishing a message the Broker ensures that a | |
| Consumer is attached to queue. If there is no Consumer attached to the queue, the message is | |
| returned to the publisher's connection. The Message is returned to the application in an | |
| asynchronous fashion using the Connection's <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/ExceptionListener.html" target="_top">ExceptionListener</a>.</p><p>The ExceptionListener will be invoked with a JMSException whose linked exception is an | |
| <a class="link" href="JMS-Client-0-8-Appendix-Exceptions-AMQNoConsumersException" target="_top">AMQNoConsumersException</a>. The returned message is available to the application by | |
| calling AMQNoConsumersException#getUndeliveredMessage(). The ExceptionListener will be | |
| invoked exactly once for each returned message.</p><p>If synchronous publishing has been enabled, and an immediate message is returned, the | |
| <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/MessageProducer.html#send(javax.jms.Message)" target="_top">MessageProducer#send()</a> method will throw a JMSException. | |
| </p><p>The immediate message feature is turned <span class="emphasis"><em>off</em></span> by default. It can be | |
| enabled with system property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-DefaultImmediate"><code class="literal">qpid.default_immediate</code></a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-MessageProducer-FlowControl"></a>5.5.4. Flow Control</h3></div></div></div><p>With this feature, if a message is sent to a queue that is overflow, the producer's | |
| session is blocked until the queue becomes underfull, or a timeout expires. This client | |
| feature requires support for the corresponding feature by the Broker.</p><p>To control the timeout use System property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-FlowControlWaitFailure"><code class="literal">qpid.flow_control_wait_failure</code></a>. To control the frequency with | |
| which warnings are logged whilst a Session is blocked, use System property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-FlowControlWaitNotifyPeriod"><code class="literal">qpid.flow_control_wait_notify_period</code></a></p><p>See <a class="link" href="../../java-broker/book/Java-Broker-Runtime-Disk-Space-Management.html#Qpid-Producer-Flow-Control" target="_top"> Producer Flow Control</a> within the Apache Qpid Broker-Java book for full details of the | |
| functioning of this feature.</p></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-Session.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-MessageConsumer.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">5.4. Session </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.6. MessageConsumer</td></tr></table></div></div> |