Added: qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Binding-URL.html URL: http://svn.apache.org/viewvc/qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Binding-URL.html?rev=1718924&view=auto ============================================================================== --- qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Binding-URL.html (added) +++ qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Binding-URL.html Wed Dec 9 17:41:59 2015 @@ -0,0 +1,218 @@ +<!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 8. Binding URL - 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://github.com/alanconway/proton-go.git"/> + <meta name="go-source" + content="qpid.apache.org +https://github.com/alanconway/proton-go/tree/master/README.md +https://github.com/alanconway/proton-go/tree/master{/dir} +https://github.com/alanconway/proton-go/blob/master{/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.0/index.html">Qpid Java 6.0.0</a></li><li><a href="/releases/qpid-java-6.0.0/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 8. Binding URL</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 8. Binding URL</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Connection-URL.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="JMS-Client-0-8-System-Properties.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-Binding-URL"></a>Chapter 8. Binding URL</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-Binding-URL.html#JMS-Client-0-8-Binding-URL-Examples">8.1. Binding URL Examples</a></span></dt><dd><dl><dt><span class="section"><a href="JMS-Client-0-8-Binding-URL.html#JMS-Client-0-8-Binding-URL-JMS-Queues">8.1.1. Binding URLs for declar ing of JMS Queues</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Binding-URL.html#JMS-Client-0-8-Binding-URL-JMS-Topics">8.1.2. Binding URLs for declaring of JMS Topics</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Binding-URL.html#JMS-Client-0-8-Binding-URL-Topics-Wildcards">8.1.3. Wildcard characters in routing keys for topic destinations</a></span></dt><dt><span class="section"><a href="JMS-Client-0-8-Binding-URL.html#JMS-Client-0-8-Binding-URL-Extra-Examples">8.1.4. More Examples</a></span></dt></dl></dd></dl></div><p> The <span class="emphasis"><em>Binding URL</em></span> syntax for addressing<a class="footnote" href="#ftn.idm140185670235616" id="idm140185670235616"><sup class="footnote">[4]</sup></a>. It allows the specification of the bindings between a queue and an exchange, queue + and exchange creation arguments and some ancillary options.</p><p> The format for a <span class="emphasis"><em>Binding URL</em></span> is provided below </p><pre class="screen"> +<Exchange Class>://<Exchange Name>/[<Destination>]/[<Queue>][?<option>='<value>'[&<option>='<value>']] + </pre><p> where </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Exchange Class</em></span>, specifies the type of the exchange, for example, + <span class="emphasis"><em>direct</em></span>,<span class="emphasis"><em>topic</em></span>,<span class="emphasis"><em>fanout</em></span>, etc. + </p></li><li class="listitem"><p><span class="emphasis"><em>Exchange Name</em></span>, specifies the name of the exchange, for example, + <span class="emphasis"><em>amq.direct</em></span>,<span class="emphasis"><em>amq.topic</em></span>, etc. </p></li><li class="listitem"><p><span class="emphasis"><em>Destination</em></span>, is an optional part of <span class="emphasis"><em>Binding + URL</em></span>. It can be used to specify a routing key with the non direct exchanges if + an option <span class="emphasis"><em>routingkey</em></span> is not specified. If both + <span class="emphasis"><em>Destination</em></span> and option <span class="emphasis"><em>routingkey</em></span> are + specified, then option <span class="emphasis"><em>routingkey</em></span> has precedence. </p></li><li class="listitem"><p><span class="emphasis"><em>Queue</em></span>, is an optional part of <span class="emphasis"><em>Binding URL</em></span> to + specify a queue name for JMS queue destination. It is ignored in JMS topic destinations. + Queue names may consist of any mixture of digits, letters, and underscores </p></li><li class="listitem"><p><span class="emphasis"><em>Options</em></span>, key-value pairs separated by '=' character specifying + queue and exchange creation arguments, routing key, client behaviour, etc. </p></li></ul></div><p> + </p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Binding URL option quoting</h3><p>Take care with the quoting surrounding option values. Each option value + <span class="emphasis"><em>must</em></span> be surrounded with single quotes ('). </p></div><p> The following <span class="emphasis"><em>Binding URL</em></span> options are currently defined: </p><div class="table"><a id="idm140185674084096"></a><p class="title"><strong>Table 8.1. Binding URL options </strong></p><div class="table-contents"><table border="1" summary="Binding URL options " width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Option</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p>durable</p></td><td><p>boolean </p></td><td><p>Queue durability flag. If it is set to <span class="emphasis"><em>true</em></span>, a durable + queue is requested to create. The durable queue should be stored on the Broker and + remained there after Broker restarts until it is explicitly deleted. This option has + no meaning for JMS topic destinations, as by nature a topic destination only exists + when a subscriber is connected. If durability is required for topic destinations, + the durable subscription should be created.</p></td></tr><tr><td><p>exclusive</p></td><td><p>boolean </p></td><td><p>Queue exclusivity flag. The client cannot use a queue that was declared as + exclusive by another still-open connection.</p></td></tr><tr><td><p>autodelete</p></td><td><p>boolean </p></td><td><p>Queue auto-deletion flag. If it is set to <span class="emphasis"><em>true</em></span> on + queue creation, the queue is deleted if there are no remaining + subscribers.</p></td></tr><tr><td><p>exchangeautodelete</p></td><td><p>boolean </p></td><td><p>Exchange auto-deletion flag.</p></td></tr><tr><td><p>exchangedurable</p></td><td><p>boolean </p></td><td><p>Exchange durability flag. If it is set to <span class="emphasis"><em>true</em></span> when + creating a new exchange, the exchange will be marked as durable. Durable exchanges + should remain active after Broker restarts. Non-durable exchanges are deleted on + following Broker restart.</p></td></tr><tr><td><p>routingkey</p></td><td><p>string </p></td><td> + <p> Defines the value of the binding key to bind a queue to the exchange. It is + always required to specify for JMS topic destinations. If routing key option is not + set in <span class="emphasis"><em>Binding URL</em></span> and direct exchange class is specified, the + queue name is used as a routing key. <span class="emphasis"><em>MessagePublisher</em></span> uses + routing key to publish messages onto exchange. </p> + </td></tr><tr><td><p>browse</p></td><td><p>boolean </p></td><td><p>If set to <span class="emphasis"><em>true</em></span> on a destination for a message + consumer, such consumer can only read messages on the queue but cannot consume them. + The consumer behaves like a queue browser in this case.</p></td></tr><tr><td><a id="JMS-Client-0-8-Binding-URL-Options-RejectBehaviour"></a><p>rejectbehaviour</p></td><td><p>string </p></td><td><p>Defines the reject behaviour for the re-delivered messages. If set to + 'SERVER' the client delegates the requeue/DLQ decision to the server. If this option + is not specified, the messages won't be moved to the DLQ (or dropped) when delivery + count exceeds the maximum. </p></td></tr></tbody></table></div></div><p><br class="table-break" /> + </p><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="JMS-Client-0-8-Binding-URL-Examples"></a>8.1. Binding URL Examples</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Binding-URL-JMS-Queues"></a>8.1.1. Binding URLs for declaring of JMS Queues</h3></div></div></div><p>The Qpid client Binding URLs for JMS queue destinations can be declared using direct + exchange (Mostly it is a pre-defined exchange with a name "amq.direct". Also, custom direct + exchanges can be used.): </p><pre class="screen"> +direct://amq.direct//<Queue Name> + </pre><p> + </p><p>The Binding URLs for destinations created with calls to + <span class="emphasis"><em>Session.createQueue(String)</em></span> can be expressed as </p><pre class="screen"> +direct://amq.direct//<Queue Name>?durable='true' + </pre><p> The durability flag is set to <span class="emphasis"><em>true</em></span> in such destinations. </p><div class="example"><a id="idm140185672784016"></a><p class="title"><strong>Example 8.1. Binding URL examples for JMS queues</strong></p><div class="example-contents"><pre class="screen"> +direct://amq.direct//myNonDurableQueue +direct://amq.direct//myDurableQueue?durable='true' +direct://amq.direct//myAnotherQueue?durable='true'&routingkey='myqueue' +direct://amq.direct//myQueue?durable='true'&routingkey='myqueue'&rejectbehaviour='server' +direct://custom.direct//yetAnotherQueue + </pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Binding-URL-JMS-Topics"></a>8.1.2. Binding URLs for declaring of JMS Topics</h3></div></div></div><p>The Binding URLs for JMS queue destinations can be declared using topic exchange (A + pre-defined exchange having name "amq.topic" is used mainly. However, custom topic exchanges + can be used as well): </p><pre class="screen"> +topic://amq.topic//<Queue name>?routingkey='<Topic Name>'&exclusive='true'&autodelete='true' + </pre><p> + </p><p>The Binding URLs for a topic destination created with calls to + <span class="emphasis"><em>Session.createTopic("hello")</em></span> is provided below: </p><div class="example"><a id="idm140185669387552"></a><p class="title"><strong>Example 8.2. Binding URL examples for JMS topics</strong></p><div class="example-contents"><pre class="screen"> +topic://amq.topic/hello/tmp_127_0_0_1_36973_1?routingkey='hello'&exclusive='true'&autodelete='true' + </pre></div></div><p><br class="example-break" /> + </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Binding-URL-Topics-Wildcards"></a>8.1.3. Wildcard characters in routing keys for topic destinations</h3></div></div></div><p> AMQP exchanges of class <span class="emphasis"><em>topic</em></span> can route messages to the queues + using special matches containing wildcard characters (a "#" matches one or more words, a "*" + matches a single word). The routing keys words are separated with a "." delimiter to + distinguish words for matching. Thus, if a consumer application specifies a routing key in + the destination like "usa.#", it should receive all the messages matching to that routing + key. For example, "usa.boston", "usa.new-york", etc. </p><p> The examples of the <span class="emphasis"><em>Binding URLs</em></span> having routing keys with + wildcards characters are provided below: </p><pre class="screen"> +topic://amq.topic?routingkey='stocks.#' +topic://amq.topic?routingkey='stocks.*.ibm' +topic://amq.topic?routingkey='stocks.nyse.ibm' + </pre><p> + </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Binding-URL-Extra-Examples"></a>8.1.4. More Examples</h3></div></div></div><div class="table"><a id="idm140185674718496"></a><p class="title"><strong>Table 8.2. Binding URL examples</strong></p><div class="table-contents"><table border="1" summary="Binding URL examples"><colgroup><col /><col /></colgroup><thead><tr><th>Binding URL</th><th>Description</th></tr></thead><tbody><tr><td><p>fanout://amq.fanout//myQueue</p></td><td><p>Binding URL binding queue "myQueue" to predefined "amq.fanout" exchange + of class "fanout"</p></td></tr><tr><td><p>topic://custom.topic//anotherQueue?routingkey='aq'</p></td><td><p>Binding URL binding queue "anotherQueue" to the exchange with name + "custom.topic" of class "topic" using binding key "aq".</p></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="footnotes"><br /><hr align="left" width="100" /><div class="footnote" id="ftn.idm140185670235616"><p><a class="para" href="#idm140185670235616"><sup class="para">[4] </sup></a>The client also supports the ADDR format. This is documented in <a class="ulink" href="../../../qpid-0.32/programming/book/" target="_top">Programming in Apache Qpid</a>.</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-Connection-URL.html">Prev</a> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="JMS-Client-0-8-System-Properties.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">Chapter 7. Connection URLs </td><td align="center" width= "20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> Chapter 9. System Properties</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>
Added: qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Connection.html URL: http://svn.apache.org/viewvc/qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Connection.html?rev=1718924&view=auto ============================================================================== --- qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Connection.html (added) +++ qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Connection.html Wed Dec 9 17:41:59 2015 @@ -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.3. Connection - 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://github.com/alanconway/proton-go.git"/> + <meta name="go-source" + content="qpid.apache.org +https://github.com/alanconway/proton-go/tree/master/README.md +https://github.com/alanconway/proton-go/tree/master{/dir} +https://github.com/alanconway/proton-go/blob/master{/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.0/index.html">Qpid Java 6.0.0</a></li><li><a href="/releases/qpid-java-6.0.0/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.3. Connection</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.3. Connection</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding-ConnectionFactory.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-Session.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="JMS-Client-0-8-Client-Understanding-Connection"></a>5.3. Connection</h2></div></div></div><p>A Connection represents an open communication channel between application and + Broker.</p><p>Connections are created from the ConnectionFactory <a class="footnote" href="#ftn.idm140185670149056" id="idm140185670149056"><sup class="footnote">[3]</sup></a>.</p><p>Each connection utilises a single TCP/IP connection between the process of the application + and the process of the Broker. The act of establishing a connection is therefore a relatively + expensive operation. It is recommended that the same connection is used for a series of + message interactions. Patterns utilising a connection per message should not be used. </p><p>The underlying TCP/IP connection remains open for the lifetime of the JMS connection. It + is closed when the application calls <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Connection.html#close()" target="_top">Connection#close()</a>, but it + can also be closed if the connection is closed from the Broker side (via a Management + operation or broker shutdown or running into conditions which AMQP specifications treats as + errors and mandates closing the connection). The JMS connection will also be closed if the + underlying TCP/IP connection is broken.</p><p>Qpid connections have failover and heartbeating capabilities. They support SSL and + client-auth. 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-Connection-Failover"></a>5.3.1. Failover</h3></div></div></div><p>Qpid connections support a failover feature. This is the ability to automatically + re-establish a failed connection, either to the same Broker, or the next Broker in the + broker list.</p><p>This failover process is done in a manner that is mostly transparent to the application. + After a successful failover, any existing Connection, Session, MessageConsumer and + MessageProducer objects held by the application remain valid.</p><p>If a failover occurs during the scope of a JMS Transaction, any work performed by that + transaction is lost. The application is made aware of this loss by way of the <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/TransactionRolledBackException.html"; target="_top">TransactionRolledBackException</a> from the <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Session.html#commit"; target="_top">Session#commit()</a> call. + Applications utilising failover must be prepared to catch this exception and respond by + either repeating the work of the transaction, or by propagating a rollback to the + originating system.</p><p>If, after all retries are exhausted, failover has failed to reconnect the application, + the Connection's <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/ExceptionListener.html"; target="_top">ExceptionListener</a> will receive a JMSException with a linked exception of <a class="ulink" href="JMS-Client-0-8-Appendix-Exceptions-AMQDisconnectedException" target="_top">AMQDisconnectedException</a>. Any further use of the JMS objects (Connection, Session + etc), will results in a <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/IllegalStateException.html"; target="_top">IllegalStateException</a>.</p><p>Configure failover using the Connection URL. Here's an example Connection URL utilising + failover between two brokers. Note the use of the broker options <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-Retries"><code class="literal">retries</code></a> and <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-ConnectDelay"><code class="literal">connectdelay</code></a> to control the number of connection attempts to + each individual broker, and the delay between each connection attempt. Also note the use of + the <span class="emphasis"><em>failover option</em></span> + <code class="literal">cyclecount</code> to control the number of times the failover mechanism will + traverse the brokerlist.</p><div class="example"><a id="idm140185668918160"></a><p class="title"><strong>Example 5.1. Connection URL configured for failover</strong></p><div class="example-contents"><pre class="screen"> +amqp://username:password@clientid/test + ?brokerlist='tcp://localhost:15672?retries='10'&connectdelay='1000';tcp://localhost:25672?retries='10'&connectdelay='1000'' + &failover='roundrobin?cyclecount='20'' + </pre></div></div><br class="example-break" /><p>For full details see <a class="xref" href="JMS-Client-0-8-Connection-URL.html" title="Chapter 7. Connection URLs">Chapter 7, <em>Connection URLs</em></a></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Note, that a single broker failover is enabled by default. If the failover behaviour + is not desired it can be switched off by setting a failover option to + <code class="literal">nofailover</code> as in the example below </p><div class="example"><a id="idm140185668913968"></a><p class="title"><strong>Example 5.2. Connection URL configured with nofailover</strong></p><div class="example-contents"><pre class="screen"> +amqp://username:password@clientid/test + ?brokerlist='tcp://localhost:15672?failover='nofailover' + </pre></div></div><p><br class="example-break" /> + </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Connection-Heartbeating"></a>5.3.2. Heartbeating</h3></div></div></div><p>Qpid connections support heartbeating. When enabled, the Qpid JMS client and Broker + exchange a heartbeat during periods of inactivity. This allows both peers to discover if the + TCP/IP connection becomes inoperable in a timely manner.</p><p>This feature is sometimes useful in applications that must traverse firewalls as the + heartbeat prevents connections from being closed during periods when there is no application + traffic.</p><p>It is also allows the both the JMS client and the Broker to confirm that the other is + <span class="emphasis"><em>minimally</em></span> responsive. (It does nothing however to determine the + health of the higher level tiers of application, for this reason, applications may implement + an application level heartbeat either in addition to, or instead of the heartbeat.</p><p>If the client ever fails to receive two consecutive heartbeats, the Connection will be + automatically closed and the Connection's <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/ExceptionListener.html"; target="_top">ExceptionListener</a> will + receive a JMSException with a linked exception of AMQDisconnectedException. Any further use + of the JMS objects (Connection, Session etc), will results in a <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/IllegalStateException.html"; target="_top">IllegalStateException</a>.</p><p>To enable heartbeating either use a Connection URL including the broker option <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-Heartbeat"><code class="literal">heartbeat</code></a>, or use the system property <a class="link" href="JMS-Client-0-8-System-Properties.html#JMS-Client-0-8-System-Properties-Heartbeat"><code class="literal">qpid.heartbeat</code></a>. </p><div class="example"><a id="idm140185671609872"></a><p class="title"><strong>Example 5.3. Connection URL configured for heartbeating</strong></p><div class="example-contents"><pre class="screen"> +amqp://guest:guest@clientid/?brokerlist='localhost:5672?heartbeat='5'' + </pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Connection-SSL"></a>5.3.3. SSL</h3></div></div></div><p>The Qpid JMS client supports connections encrypted using Secure Socket Layer (SSL) and + SSL-Client Authentication. SSL is configured using Connection URL. To use SSL, SSL must be + be configured on the Broker.</p><p>Some example Connection URLs using SSL follow:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Simple SSL when the Broker is secured by a certificate that is signed by a CA which + is trusted by the JVM.</p><div class="example"><a id="idm140185671604992"></a><p class="title"><strong>Example 5.4. Connection URL configured for SSL - CA trusted by JVM</strong></p><div class="example-contents"><pre class="screen"> +amqp://guest:guest@clientid/?brokerlist='localhost:5671'&ssl='true' + </pre></div></div><br class="example-break" /></li><li class="listitem"><p>SSL when the Broker is secured by a certificate that is signed by a CA which is NOT + trusted by the JVM (such as when a organisation is using a private CA, or self-signed + certificates are in use). For this case, we use <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-TrustStore"><code class="literal">trust_store</code></a> and <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-TrustStorePassword"><code class="literal">trust_store_password</code></a> to specify a path a truststore file + (containing the certificate of the private-CA) and the truststore password.</p><div class="example"><a id="idm140185671599952"></a><p class="title"><strong>Example 5.5. Connection URL configured for SSL - CA not trusted by JVM</strong></p><div class="example-contents"><pre class="screen"> +amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/acme_org_ca.ts'&trust_store_password='secret''&ssl='true' + </pre></div></div><br class="example-break" /></li><li class="listitem"><p>SSL with SSL client-auth. For this case, we use <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-KeyStore"><code class="literal">key_store</code></a> and <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-KeyStorePassword"><code class="literal">key_store_password</code></a> to specify a path a keystore file + (containing the certificate of the client) and the keystore password.</p><div class="example"><a id="idm140185670084704"></a><p class="title"><strong>Example 5.6. Connection URL configured for SSL - SSL client-auth</strong></p><div class="example-contents"><pre class="screen"> +amqp://guest:guest@clientid/?brokerlist='localhost:5671?key_store='/path/to/app1_client_cert.ks'&key_store_password='secret''&ssl='true' + </pre></div></div><br class="example-break" /><p>Alternatively we can use <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-ClientCertPath"><code class="literal">client_cert_path</code></a> and <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-BrokerOptions-ClientCertPrivKeyPath"><code class="literal">client_cert_priv_key_ath</code></a> to specify a path to a certificate file (in PEM or DER format) + and the private key information (again in either PEM or DER format) respectively.</p><div class="example"><a id="idm140185670080032"></a><p class="title"><strong>Example 5.7. Connection URL configured for SSL - SSL client-auth (2)</strong></p><div class="example-contents"><pre class="screen"> +amqp://guest:guest@clientid/?brokerlist='localhost:5671?client_cert_path='/path/to/app1_client.crt'&client_cert_priv_key_path='/path/to/app1_client.key''&ssl='true' + </pre></div></div><br class="example-break" /></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="JMS-Client-0-8-Client-Understanding-Connection-MessageCompression"></a>5.3.4. Message Compression</h3></div></div></div><p>The client has the ability to transparently compress message payloads on outgoing + messages and decompress them on incoming messages. In some environments and with some + payloads this feature might offer performance improvements by reducing the number of bytes + transmitted over the connection.</p><p>In order to make use of message compression, the Broker must enable the feature too, + otherwise the compression options will be ignored.</p><p> To enable message compression on the client use the connection url property <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-ConnectionOptions-CompressMessages"><code class="literal">compressMessages</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-ConnectionCompressMessages"><code class="literal">qpid.connection_compress_messages</code></a>)</p><p>It is also possible to control the threshold at which the client will begin to compress + message payloads. See connection url property <a class="link" href="JMS-Client-0-8-Connection-URL.html#JMS-Client-0-8-Connection-URL-ConnectionOptions-MessageCompressionThresholdSize"><code class="literal">messageCompressionThresholdSize</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-MessageCompressionThresholdSize"><code class="literal">qpid.message_compression_threshold_size</code></a>)</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The Broker, where necessary, takes care of compressing/decompressing messages of the + fly so that clients using message compression can exchange messages with clients not + supporting message compression transparently, without application intervention.</p></div></div><div class="footnotes"><br /><hr align="left" width="100" /><div class="footnote" id="ftn.idm140185670149056"><p><a class="para" href="#idm140185670149056"><sup class="para">[3] </sup></a>Constructors of the AMQConnection class must not be used.</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-ConnectionFactory.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-Session.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">5.2. ConnectionFactory </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right " valign="top" width="40%"> 5.4. Session</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> Added: qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-ConnectionFactory.html URL: http://svn.apache.org/viewvc/qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-ConnectionFactory.html?rev=1718924&view=auto ============================================================================== --- qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-ConnectionFactory.html (added) +++ qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-ConnectionFactory.html Wed Dec 9 17:41:59 2015 @@ -0,0 +1,151 @@ +<!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.2. ConnectionFactory - 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://github.com/alanconway/proton-go.git"/> + <meta name="go-source" + content="qpid.apache.org +https://github.com/alanconway/proton-go/tree/master/README.md +https://github.com/alanconway/proton-go/tree/master{/dir} +https://github.com/alanconway/proton-go/blob/master{/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.0/index.html">Qpid Java 6.0.0</a></li><li><a href="/releases/qpid-java-6.0.0/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.2. ConnectionFactory</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.2. ConnectionFactory</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-8-Client-Understanding.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-Connection.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="JMS-Client-0-8-Client-Understanding-ConnectionFactory"></a>5.2. ConnectionFactory</h2></div></div></div><p>A <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/ConnectionFactory.html"; target="_top">ConnectionFactory</a> + allows an application to create a <a class="ulink" href="http://docs.oracle.com/javaee/6/api/javax/jms/Connection.html"; target="_top">Connection</a>.</p><p>The application obtains the ConnectionFactory from an <a class="ulink" href="http://docs.oracle.com/javase/7/docs/api/javax/naming/InitialContext.html"; target="_top">InitialContext</a>. The + InitialContext is itself obtained from an InitialContextFactory. </p><p>The Qpid JMS client provides a single implementation of the InitialContextFactory in class + <code class="literal">org.apache.qpid.jndi.PropertiesFileInitialContextFactory</code>. This + implementation is backed by a <a class="ulink" href="http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html"; target="_top">Properties</a> object which can of course be loaded from an external properties file, + or created programatically.</p><p>The examples in the previous chapter illustrated the Java code required to <a class="link" href="JMS-Client-0-8-Examples.html#JMS-Client-0-8-Examples-PTP" title="4.1. Point to point example">create the InitialContext</a> and an <a class="link" href="JMS-Client-0-8-Examples.html#JMS-Client-0-8-Examples-PTP-PropertiesFile" title="Example 4.2. JMS Example - Point to Point Messaging - JNDI Properties">example properties file</a>.</p><p>The Qpid JMS client also provides an alternate connection factory implementation providing a + connection pool. This can be useful when utilsing frameworks such as Spring. + <a class="xref" href="JMS-Client-0-8-Appendix-PooledConnecytionFactory.html" title="Appendix D. PooledConnectionFactory">Appendix D, <em>PooledConnectionFactory</em></a>.</p><div class="figure"><a id="idm140185675495856"></a><p class="title"><strong>Figure 5.2. JNDI overview</strong></p><div class="figure-contents"><div class="mediaobject"><img alt="JNDI overview" src="images/JndiOverview.png" /></div></div></div><br class="figure-break" /><p>Note that the Qpid Broker does not present a JNDI interface to the application.</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.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-Connection.html">Next</a></td></tr ><tr><td align="left" valign="top" >width="40%">Chapter 5. Understanding the Qpid JMS >client </td><td align="center" width="20%"><a accesskey="h" >href="index.html">Home</a></td><td align="right" valign="top" >width="40%"> 5.3. Connection</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> Added: qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Destinations.html URL: http://svn.apache.org/viewvc/qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Destinations.html?rev=1718924&view=auto ============================================================================== --- qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Destinations.html (added) +++ qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-Destinations.html Wed Dec 9 17:41:59 2015 @@ -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://github.com/alanconway/proton-go.git"/> + <meta name="go-source" + content="qpid.apache.org +https://github.com/alanconway/proton-go/tree/master/README.md +https://github.com/alanconway/proton-go/tree/master{/dir} +https://github.com/alanconway/proton-go/blob/master{/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.0/index.html">Qpid Java 6.0.0</a></li><li><a href="/releases/qpid-java-6.0.0/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"><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="index.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> Added: qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageConsumer.html URL: http://svn.apache.org/viewvc/qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageConsumer.html?rev=1718924&view=auto ============================================================================== --- qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageConsumer.html (added) +++ qpid/site/docs/releases/qpid-java-6.0.0/jms-client-0-8/book/JMS-Client-0-8-Client-Understanding-MessageConsumer.html Wed Dec 9 17:41:59 2015 @@ -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://github.com/alanconway/proton-go.git"/> + <meta name="go-source" + content="qpid.apache.org +https://github.com/alanconway/proton-go/tree/master/README.md +https://github.com/alanconway/proton-go/tree/master{/dir} +https://github.com/alanconway/proton-go/blob/master{/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.0/index.html">Qpid Java 6.0.0</a></li><li><a href="/releases/qpid-java-6.0.0/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"><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="ulink" 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="ulink" 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="ulink" 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="ulink" 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="index.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> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
