You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by or...@apache.org on 2016/05/27 15:07:10 UTC
[25/49] qpid-site git commit: Update site for Qpid Java release 6.0.3
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/2069e43d/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Destinations.html
----------------------------------------------------------------------
diff --git a/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Destinations.html b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Destinations.html
new file mode 100644
index 0000000..b7bbbd5
--- /dev/null
+++ b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Destinations.html
@@ -0,0 +1,149 @@
+<!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>5.7. Destinations - 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://git-wip-us.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/java-broker/index.html">Java broker</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-java-6.0.3/index.html">Qpid Java 6.0.3</a></li><li><a href="/releases/qpid-java-6.0.3/jms-client-0-8/book/index.html">Qpid JMS Client for AMQP protocols 0-8, 0-9 and 0-9-1</a></li><li>5.7. Destinations</li></ul>
+
+ <div id="-middle-content">
+ <div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">5.7. Destinations</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding-MessageConsumer.html">Prev</a> </td><th align="center" width="60%">Chapter 5. Understanding the Qpid JMS client</th><td align="right" width="20%"> <a accesskey="n" href="JMS-Client-0-8-JNDI-Properties-Format.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-Destinations"></a>5.7. Destinations</h2></div></div></div><p>A Destination is either a Queue or Topic. In the Qpid JMS client a Destination
+ encapsulates a Binding URL. In simple terms, the Binding URL comprises of an exchange, queue
+ and a routing key. Binding URLs are described fully by <a class="xref" href="JMS-Client-0-8-Binding-URL.html" title="Chapter 8. Binding URL">Chapter 8, <em>Binding URL</em></a>. </p><p>In many cases, applications do not need to deal directly with Binding URLs, instead they
+ can refer to JMS administered objects declared in the JNDI properties file with the
+ <code class="literal">queue.</code> and <code class="literal">topic.</code> prefix to create Queues and Topics
+ objects respectively. </p></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-MessageConsumer.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-JNDI-Properties-Format.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">5.6. MessageConsumer </td><td align="center" width="20%"><a accesskey="h" href="JMS-Client-Book.html">Home</a></td><td align="right" valign="top" width="40%"> Chapter 6. JNDI Properties Format</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="http://www.apache.org/security/">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>
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/2069e43d/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageConsumer.html
----------------------------------------------------------------------
diff --git a/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageConsumer.html b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageConsumer.html
new file mode 100644
index 0000000..747f926
--- /dev/null
+++ b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageConsumer.html
@@ -0,0 +1,171 @@
+<!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>5.6. MessageConsumer - 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://git-wip-us.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/java-broker/index.html">Java broker</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-java-6.0.3/index.html">Qpid Java 6.0.3</a></li><li><a href="/releases/qpid-java-6.0.3/jms-client-0-8/book/index.html">Qpid JMS Client for AMQP protocols 0-8, 0-9 and 0-9-1</a></li><li>5.6. MessageConsumer</li></ul>
+
+ <div id="-middle-content">
+ <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 Qpid JMS 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 Qpid JMS 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 Java Broker 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>
+
+ <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="http://www.apache.org/security/">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>
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/2069e43d/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageProducer.html
----------------------------------------------------------------------
diff --git a/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageProducer.html b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageProducer.html
new file mode 100644
index 0000000..9f8a9d7
--- /dev/null
+++ b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageProducer.html
@@ -0,0 +1,190 @@
+<!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>5.5. MessageProducer - 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://git-wip-us.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/java-broker/index.html">Java broker</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-java-6.0.3/index.html">Qpid Java 6.0.3</a></li><li><a href="/releases/qpid-java-6.0.3/jms-client-0-8/book/index.html">Qpid JMS Client for AMQP protocols 0-8, 0-9 and 0-9-1</a></li><li>5.5. MessageProducer</li></ul>
+
+ <div id="-middle-content">
+ <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 Qpid JMS 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 Java Broker 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 Qpid JMS 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 Java Broker
+ 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 Java Broker 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>
+
+ <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="http://www.apache.org/security/">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>
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/2069e43d/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Session.html
----------------------------------------------------------------------
diff --git a/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Session.html b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Session.html
new file mode 100644
index 0000000..c967a0d
--- /dev/null
+++ b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Session.html
@@ -0,0 +1,215 @@
+<!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>5.4. Session - 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://git-wip-us.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/java-broker/index.html">Java broker</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-java-6.0.3/index.html">Qpid Java 6.0.3</a></li><li><a href="/releases/qpid-java-6.0.3/jms-client-0-8/book/index.html">Qpid JMS Client for AMQP protocols 0-8, 0-9 and 0-9-1</a></li><li>5.4. Session</li></ul>
+
+ <div id="-middle-content">
+ <div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">5.4. Session</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding-Connection.html">Prev</a> </td><th align="center" width="60%">Chapter 5. Understanding the Qpid JMS client</th><td align="right" width="20%"> <a accesskey="n" href="JMS-Client-0-8-Client-Understanding-MessageProducer.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-Session"></a>5.4. Session</h2></div></div></div><p>A Session object is a single-threaded context for producing and consuming messages.</p><p>Session objects are created from the Connection. Whilst Session objects are relatively
+ lightweight, patterns utilising a single Session per message are not recommended.</p><p>The number of sessions open per connection at any one time is limited. This value is
+ negotiated when the connection is made. It defaults to 256.</p><p>Qpid JMS Sessions have the ability to prefetch messages to improve consumer performance.
+ This feature is described next.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Session-Prefecth"></a>5.4.1. Prefetch</h3></div></div></div><p>Prefetch specifies how many messages the client will optimistically cache for delivery
+ to a consumer. This is a useful parameter to tune that can improve the throughput of an
+ application. The prefetch buffer is scoped per <span class="emphasis"><em>Session</em></span>.</p><p>The size of the prefetch buffer can be tuned per Connection using the connection url
+ option <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-ConnectionOptions-Maxprefetch"><code class="literal">maxprefetch</code></a> (or JVM wide using the system property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-Maxprefetch"><code class="literal">max_prefetch</code></a>). By default, prefetch defaults to 500.</p><p>There are situations when you may wish to consider reducing the size of prefetch:</p><p>
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>When using a <a class="link" href="http://www.eaipatterns.com/CompetingConsumers.html" target="_top">Competing Consumers</a> pattern, prefetch can give the appearance of unequal
+ division of work. This will be apparent on startup when the queue has messages. The
+ first consumer started will cache prefetch size number of messages, possibly leaving
+ the other consumers with no initial work.</p></li><li class="listitem"><p>When using special queue types (such as LVQs, Sorted Queue and Priority Queues).
+ For these queue types the special delivery rules apply whilst the message resides on
+ the Broker. As soon as the message is sent to the client it delivery order is then
+ fixed. For example, if using a priority queue, and a prefetch of 100, and 100 messages
+ arrive with priority 2, the broker will send these to the client. If then a new
+ message arrives with priority 1, the broker cannot leap frog messages of the lower
+ priority. The priority 1 message will be delivered at the front of the next
+ batch.</p></li><li class="listitem"><p>When message size is large and you do not wish the memory footprint of the
+ application to grow (or suffer an OutOfMemoryError).</p></li></ol></div><p>
+ </p><p>Finally, if using multiple MessageConsumers on a single Session, keep in mind that
+ unless you keep polling <span class="emphasis"><em>all</em></span> consumers, it is possible for some traffic
+ patterns to result in consumer starvation and an application level deadlock. For example, if
+ prefetch is 100, and 100 hundred messages arrive suitable for consumer A, those messages
+ will be prefetched by the session, entirely filling the prefetch buffer. Now if the
+ application performs a blocking <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/MessageConsumer.html#receive()" target="_top">MessageConsumer#receive()</a> for Consumer B on the same Session, the application
+ will hang indefinitely as even if messages suitable for B arrive at the Broker. Those
+ messages can never be sent to the Session as no space is available in prefetch. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please note, when the acknowledgement mode
+ <span class="emphasis"><em>Session#SESSION_TRANSACTED</em></span> or
+ <span class="emphasis"><em>Session#CLIENT_ACKNOWLEDGE</em></span> is set on a consuming session, the
+ prefetched messages are released from the prefetch buffer on transaction commit/rollback
+ (in case of acknowledgement mode <span class="emphasis"><em>Session#SESSION_TRANSACTED</em></span> ) or
+ acknowledgement of the messages receipt (in case of acknowledgement mode
+ <span class="emphasis"><em>Session#CLIENT_ACKNOWLEDGE</em></span> ). If the consuming application does not
+ commit/rollback the receiving transaction (for example, due to mistakes in application
+ exception handling logic), the prefetched messages continue to remain in the prefetch
+ buffer preventing the delivery of the following messages. As result, the application might
+ stop the receiving of the messages until the transaction is committed/rolled back (for
+ <span class="emphasis"><em>Session#SESSION_TRANSACTED</em></span> ) or received messages are acknowledged
+ (for <span class="emphasis"><em>Session#CLIENT_ACKNOWLEDGE</em></span>).</p></div><p>
+ Settings maxprefetch to 0 ( either globally via JVM system property
+ <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-Maxprefetch"><code class="literal">max_prefetch</code></a>
+ or on a connection level as a connection option
+ <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-ConnectionOptions-Maxprefetch"><code class="literal">maxprefetch</code></a> )
+ switches off the pre-fetching functionality. With maxprefetch=0 messages are fetched one by one without caching on the client.
+ </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> Setting maxprefetch to 0 is recommended in Spring-JMS based applications whenever
+ <span class="emphasis"><em>DefaultMassgeListenerContainer</em></span> is configured with a
+ <span class="emphasis"><em>CachingConnectionFactory</em></span> that has <span class="emphasis"><em>cacheLevel</em></span>
+ set to either <span class="emphasis"><em>CACHE_CONSUMER</em></span> or <span class="emphasis"><em>CACHE_SESSION</em></span>.
+ In these configurations the Qpid JMS <span class="emphasis"><em>Session</em></span> objects remain open in
+ Spring's dynamically scaled pools. If maxprefetch is not 0, any prefetched messages held
+ by the <span class="emphasis"><em>Session</em></span> and any new ones subsequently sent to it (in the
+ background until prefetch is reached) will be effectively by 'stuck' (unavailable to the
+ application) until Spring decides to utilise the cached Session again. This can give the
+ impression that message delivery has stopped even though messages remain of the queue.
+ Setting maxprefetch to 0 prevents this problem from occurring.</p><p> If using maxprefetch > 0 <span class="emphasis"><em>SingleConnectionFactory</em></span> must be
+ used. SingleConnectionFactory does not have the same session/consumer caching behaviour so
+ does not exhibit the same problem. </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Session-TemporaryQueues"></a>5.4.2. TemporaryQueues</h3></div></div></div><p>Qpid implements JMS temporary queues as AMQP auto-delete queues. The life cycle of these
+ queues deviates from the JMS specification.</p><p>AMQP auto-delete queues are deleted either when the <span class="emphasis"><em>last</em></span> Consumer
+ closes, or the Connection is closed. If no Consumer is ever attached to the queue, the queue
+ will remain until the Connection is closed.</p><p>This deviation has no practical impact on the implementation of the <a class="link" href="http://www.eaipatterns.com/RequestReply.html" target="_top">request/reply messaging pattern</a>
+ utilising a per-request temporary reply queue. The reply to queue is deleted as the
+ application closes the Consumer awaiting the response. </p><p>Temporary queues are exposed to Management in the same way as normal queues. Temporary
+ queue names take the form string <code class="literal">TempQueue</code> followed by a random
+ UUID.</p><p>Note that <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/TemporaryQueue.html#delete()" target="_top">TemporaryQueue#delete()</a> merely marks the queue as deleted on within the JMS
+ client (and prevents further use of the queue from the application), however, the Queue will
+ remain on the Broker until the Consumer (or Connection) is closed.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Session-CreateQueue"></a>5.4.3. CreateQueue</h3></div></div></div><p>In the Qpid JMS client, <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/Session.html#createQueue(java.lang.String)" target="_top">Session#createQueue()</a> accepts either a queue name, or a Binding URL. If only name
+ is specified the destination will be resolved into binding URL:
+ direct://amq.direct//<queue name>?routingkey='<queue name>'&durable='true'. </p><p>Calling Session#createQueue() has no effect on the Broker.</p><p>Reiterating the advice from the JMS javadoc, it is suggested that this method is not
+ generally used. Instead, application should lookup Destinations declared within JNDI.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Session-CreateTopic"></a>5.4.4. CreateTopic</h3></div></div></div><p>In the Qpid JMS client, <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/jms/Session.html#createTopic(java.lang.String)" target="_top">Session#createTopic()</a> accepts either a topic name, or a Binding URL. If only name
+ is specified the destination will be resolved into binding URL: topic://amq.topic//<topic
+ name>?routingkey='<topic name>'.</p><p>Calling Session#createTopic() has no effect on the Broker.</p><p>Reiterating the advice from the JMS javadoc, it is suggested that this method is not
+ generally used. Instead, application should lookup Destinations declared within JNDI.</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-Connection.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-MessageProducer.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">5.3. Connection </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.5. MessageProducer</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="http://www.apache.org/security/">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>
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/2069e43d/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding.html
----------------------------------------------------------------------
diff --git a/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding.html b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding.html
new file mode 100644
index 0000000..79050a8
--- /dev/null
+++ b/content/releases/qpid-java-6.0.3/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding.html
@@ -0,0 +1,150 @@
+<!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>Chapter 5. Understanding the Qpid JMS client - 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://git-wip-us.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/java-broker/index.html">Java broker</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-java-6.0.3/index.html">Qpid Java 6.0.3</a></li><li><a href="/releases/qpid-java-6.0.3/jms-client-0-8/book/index.html">Qpid JMS Client for AMQP protocols 0-8, 0-9 and 0-9-1</a></li><li>Chapter 5. Understanding the Qpid JMS client</li></ul>
+
+ <div id="-middle-content">
+ <div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter 5. Understanding the Qpid JMS client</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Examples-PubSub.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="JMS-Client-0-8-Client-Understanding-ConnectionFactory.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="JMS-Client-0-8-Client-Understanding"></a>Chapter 5. Understanding the Qpid JMS client</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding.html#JMS-Client-0-8-Client-Understanding-Overview">5.1. Overview</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Unders
tanding-ConnectionFactory.html">5.2. ConnectionFactory</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Connection.html">5.3. Connection</a></span></dt><dd><dl><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Connection.html#JMS-Client-0-8-Client-Understanding-Connection-Failover">5.3.1. Failover</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Connection.html#JMS-Client-0-8-Client-Understanding-Connection-Heartbeating">5.3.2. Heartbeating</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Connection.html#JMS-Client-0-8-Client-Understanding-Connection-SSL">5.3.3. SSL</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Connection.html#JMS-Client-0-8-Client-Understanding-Connection-MessageCompression">5.3.4. Message Compression</a></span></dt></dl></dd><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-
Session.html">5.4. Session</a></span></dt><dd><dl><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Session.html#JMS-Client-0-8-Client-Understanding-Session-Prefecth">5.4.1. Prefetch</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Session.html#JMS-Client-0-8-Client-Understanding-Session-TemporaryQueues">5.4.2. TemporaryQueues</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Session.html#JMS-Client-0-8-Client-Understanding-Session-CreateQueue">5.4.3. CreateQueue</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Session.html#JMS-Client-0-8-Client-Understanding-Session-CreateTopic">5.4.4. CreateTopic</a></span></dt></dl></dd><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageProducer.html">5.5. MessageProducer</a></span></dt><dd><dl><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageProducer.html#JMS-Cl
ient-0-8-Client-Understanding-MessageProducer-MandatoryMessage">5.5.1. Mandatory Messages</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageProducer.html#JMS-Client-0-8-Client-Understanding-MessageProducer-CloseWhenNoRoute">5.5.2. Close When No Route</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageProducer.html#JMS-Client-0-8-Client-Understanding-MessageProducer-ImmediateMessage">5.5.3. Immediate Messages</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageProducer.html#JMS-Client-0-8-Client-Understanding-MessageProducer-FlowControl">5.5.4. Flow Control</a></span></dt></dl></dd><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageConsumer.html">5.6. MessageConsumer</a></span></dt><dd><dl><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageConsumer.html#JMS-Client-0-8-Client-Understanding-MessageConsumer-Co
nsumerSideEffect">5.6.1. Consumers have Exchange/Queue Declaration and Binding Side Effect</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageConsumer.html#JMS-Client-0-8-Client-Understanding-MessageConsumer-TopicSubscriptions">5.6.2. Topic Subscriptions</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-MessageConsumer.html#JMS-Client-0-8-Client-Understanding-MessageConsumer-MaximumDeliveryCount">5.6.3. Maximum Delivery Count</a></span></dt></dl></dd><dt><span class="section"><a href="JMS-Client-0-8-Client-Understanding-Destinations.html">5.7. Destinations</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="JMS-Client-0-8-Client-Understanding-Overview"></a>5.1. Overview</h2></div></div></div><p>The Qpid JMS client provides a JMS 1.1 compliant implementation. As such, the primary
+ source of documentation is the <a class="link" href="http://download.oracle.com/otndocs/jcp/7195-jms-1.1-fr-spec-oth-JSpec/" target="_top">JMS specification</a> and the
+ <a class="link" href="http://docs.oracle.com/javaee/6/api//javax/jms/package-summary.html" target="_top">JMS javadocs</a>. This
+ documentation assumes the reader has familiarity with these resources.</p><p>The remainder of this section describes how the Qpid JMS client behaves and the effect(s)
+ making JMS method calls will have on the Broker. </p><p>There areas where the Qpid JMS client provides features beyond those required for JMS
+ compliance. These are described in the sections that follow.</p><p>These sections are also used to bring out differences that may surprise those moving from
+ JMS implementations provided by other vendors.</p><div class="figure"><a id="d0e327"></a><p class="title"><strong>Figure 5.1. Architecture of a typical JMS application</strong></p><div class="figure-contents"><div class="mediaobject"><img alt="Architecture of a typical JMS application" src="images/QpidJmsOverview.png" /></div></div></div><br class="figure-break" /></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-Examples-PubSub.html">Prev</a> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="JMS-Client-0-8-Client-Understanding-ConnectionFactory.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">4.2. Publish/subscribe example </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.2.
 ConnectionFactory</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="http://www.apache.org/security/">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>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org