QPID-5374: Create book for Qpid JMS Client when used with AMQP 0-8/0-9/0-9-1
Merged from trunk with commands:
svn merge -c 1554333 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1554404 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1554547 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1556193 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1556310 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1559483 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1563355 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1575617 https://svn.apache.org/repos/asf/qpid/trunk
git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/0.26@1575624 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/qpid/doc/book/Makefile b/qpid/doc/book/Makefile
index 3ba8354..a8a5c45 100644
--- a/qpid/doc/book/Makefile
+++ b/qpid/doc/book/Makefile
@@ -17,7 +17,7 @@
# under the License.
#
-DIRS = src/java-broker src/java-perftests src/cpp-broker src/programming
+DIRS = src/java-broker src/java-perftests src/cpp-broker src/programming src/jms-client-0-8
.PHONY: all $(DIRS)
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml
new file mode 100644
index 0000000..eb021f3
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml
@@ -0,0 +1,173 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<appendix id="JMS-Client-0-8-Appendix-Exceptions">
+ <title>Exceptions</title>
+
+ <para>The methods of Qpid JMS Client throw <ulink url="&oracleJeeDocUrl;javax/jms/JMSException.html"
+ >JMSExceptions</ulink> in response to error conditions. Typically the exception's message
+ (#getMessage()) summarises the error condition, with contextual information being provided by
+ the messages of linked exception(s). To understand the problem, it is important to read the messages
+ associated with <emphasis>all</emphasis> the linked exceptions.</para>
+
+ <para>The following table describes some of the more common exceptions linked to JMSException
+ thrown by JMS methods whilst using the client:</para>
+
+ <table pgwide="1">
+ <title>Exceptions linked to JMSExceptions thrown by JMS methods</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Linked Exception</entry>
+ <entry>Message</entry>
+ <entry>Explanation/Common Causes</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>AMQUnresolvedAddressException</entry>
+ <entry><emphasis>message varies</emphasis></entry>
+ <entry><para>Indicates that the hostname included in the Connection URL's <link
+ linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Brokerlist"
+ >brokerlist</link>, could not be resolved, . This could mean that the hostname is
+ mispelt, or there is name resolution problem.</para></entry>
+ </row>
+ <row>
+ <entry>AMQConnectionFailure</entry>
+ <entry>Connection refused</entry>
+ <entry><para>Indicates that the host included in the Connection URL's <link
+ linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Brokerlist"
+ >brokerlist</link>, actively refused the connection. This could mean that the
+ hostname and/or port number is incorrect, or the Broker may not be
+ running.</para></entry>
+ </row>
+ <row>
+ <entry>AMQConnectionFailure</entry>
+ <entry>connect timed out</entry>
+ <entry><para>Indicates that the host included in the Connection URL's <link
+ linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Brokerlist"
+ >brokerlist</link>, could not be contacted within the <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-ConnectTimeout"
+ >connecttimeout</link>. This could mean that the host is shutdown, or a networking
+ routing problem means the host is unreachable.</para></entry>
+ </row>
+ <row>
+ <entry>AMQConnectionFailure</entry>
+ <entry>General SSL Problem; PKIX path building failed; unable to find valid certification
+ path to requested target</entry>
+ <entry><para>Indicates that the CA that signed the Broker's certificate is not trusted by
+ the JVM of the client. If the Broker is using a private-CA (or a self signed
+ certificate) check that the client has been properly configured with a truststore. See
+ <xref linkend="JMS-Client-0-8-Client-Understanding-Connection-SSL"/></para></entry>
+ </row>
+ <row>
+ <entry>AMQTimeoutException</entry>
+ <entry>Server did not respond in a timely fashion; Request Timeout</entry>
+ <entry><para>Indicates that the broker did not respond to a request sent by the client in
+ a reasonable length of time. The timeout is governed by <link
+ linkend="JMS-Client-0-8-System-Properties-SyncOpTimeout"
+ ><literal>qpid.sync_op_timeout</literal></link>.</para><para>This can be a symptom
+ of a heavily loaded broker that cannot respond or the Broker may have failed in
+ unexpected manner. Check the broker and the host on which it runs and performance of
+ its storage.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The following table describes some of the more common exceptions linked to JMSException sent
+ to <ulink url="&oracleJeeDocUrl;javax/jmx/ExceptionListener.html">ExceptionListener</ulink>
+ instances.</para>
+
+ <table pgwide="1">
+ <title>Exceptions linked to JMSExceptions received by ExceptionListeners</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Linked Exception</entry>
+ <entry>Message</entry>
+ <entry>Explanation/Common Causes</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row id="JMS-Client-0-8-Appendix-Exceptions-AMQNoRouteException">
+ <entry>AMQNoRouteException</entry>
+ <entry>No Route for message [Exchange: <emphasis>exchange name</emphasis>, Routing key:
+ <emphasis>routing key</emphasis>] [error code 312: no route]</entry>
+ <entry><para>Indicate that the named exchange is unable to route a message to at least one
+ queue.</para>
+ <para>This will occur if a queue has been improperly bound to an exchange. Use the
+ Broker's management interface to check the bindings. See <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-MandatoryMessage"
+ /></para></entry>
+ </row>
+ <row id="JMS-Client-0-8-Appendix-Exceptions-AMQNoConsumersException">
+ <entry>AMQNoConsumersException</entry>
+ <entry>Immediate delivery is not possible. [error code 313: no consumers]</entry>
+ <entry><para>Immediate delivery was requested by the MessageProducer, but as there are no
+ consumers on any target queue, the message has been returned to the publisher. See
+ <xref linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-ImmediateMessage"
+ />
+ </para></entry>
+ </row>
+ <row>
+ <entry>AMQDisconnectedException</entry>
+ <entry>Server closed connection and reconnection not permitted</entry>
+ <entry><para>Indicates that the connection was closed by the Broker, and as <link
+ linkend="JMS-Client-0-8-Client-Understanding-Connection-Failover">failover
+ options</link> are not included in the Connection URL, the client has been unable to
+ reestablish connection.</para>
+ <para>The Connection is now closed and any attempt to use either Connection object, or
+ any objects created from the Connection will receive an <ulink
+ url="&oracleJeeDocUrl;javax/jms/IllegalStateException.html"
+ >IllegalStateException</ulink>.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-Appendix-Exceptions-AMQDisconnectedException">
+ <entry>AMQDisconnectedException</entry>
+ <entry>Server closed connection and no failover was successful</entry>
+ <entry><para>Indicates that the connection was closed by the Broker. The client has tried
+ failover according to the rules of the <link
+ linkend="JMS-Client-0-8-Client-Understanding-Connection-Failover">failover
+ options</link>within the Connection URL, but these attempts were all
+ unsuccessful.</para>
+ <para>The Connection is now closed and any attempt to use either Connection object, or
+ any objects created from the Connection will receive an <ulink
+ url="&oracleJeeDocUrl;javax/jms/IllegalStateException.html"
+ >IllegalStateException</ulink>.</para></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <!--
+ :
+ AMQDisconnectedException: Server closed connection
+ -->
+
+</appendix>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml
new file mode 100644
index 0000000..9042854
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml
@@ -0,0 +1,69 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<appendix id="JMS-Client-0-8-Appendix-Maven">
+ <title>Minimal Maven POM</title>
+ <para> The following is a minimal Maven POM required to use the Qpid Client. It is suitable for
+ use with the <link linkend="JMS-Client-0-8-Examples">examples</link> included in this
+ book.</para>
+
+ <example>
+ <title>Minimal Maven POM </title>
+ <programlisting>
+ <![CDATA[
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>test</groupId>
+ <artifactId>test</artifactId>
+ <version>0.0.1-SNAPSHOT</version>
+ <dependencies>
+ <dependency>
+ <groupId>]]>&qpidClientGroupId;<![CDATA[</groupId>
+ <artifactId>]]>&qpidClientArtefactId;<![CDATA[</artifactId>
+ <version>]]>&qpidVersion;<![CDATA[</version>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-log4j12</artifactId>
+ <version>1.6.4</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.geronimo.specs</groupId>
+ <artifactId>geronimo-jms_1.1_spec</artifactId>
+ <version>1.1.1</version>
+ </dependency>
+ </dependencies>
+</project>
+ ]]>
+ </programlisting>
+ </example>
+ <para>Note: We use the SLF4J Binding for Log4J12 here, but any SLF4J Binding could be used
+ instead. Similarly, Geronimo JMS Spec is used, but any dependency that provides the JMS 1.1
+ specification could be subsituted.</para>
+</appendix>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Binding-URL.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Binding-URL.xml
new file mode 100644
index 0000000..2f6bafb
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Binding-URL.xml
@@ -0,0 +1,243 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-Binding-URL">
+ <title>Binding URL</title>
+
+ <para> The <emphasis>Binding URL</emphasis> syntax is the only addressing syntax supported by the
+ Qpid JMS client for AMQP 0-8, 0-9 and 0-9-1. It allows to specify the bindings that define the
+ relationship between a queue and an exchange, queue and exchange creation arguments and client
+ behaviour. </para>
+
+ <para> The format for a <emphasis>Binding URL</emphasis> is provided below <screen><![CDATA[
+<Exchange Class>://<Exchange Name>/[<Destination>]/[<Queue>][?<option>='<value>'[&<option>='<value>']]
+ ]]></screen> where <itemizedlist>
+ <listitem>
+ <para><emphasis>Exchange Class</emphasis>, specifies the type of the exchange, for example,
+ <emphasis>direct</emphasis>,<emphasis>topic</emphasis>,<emphasis>fanout</emphasis>, etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Exchange Name</emphasis>, specifies the name of the exchange, for example,
+ <emphasis>amq.direct</emphasis>,<emphasis>amq.topic</emphasis>, etc. </para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Destination</emphasis>, is an optional part of <emphasis>Binding
+ URL</emphasis>. It can be used to specify a routing key with the non direct exchanges if
+ an option <emphasis>routingkey</emphasis> is not specified. If both
+ <emphasis>Destination</emphasis> and option <emphasis>routingkey</emphasis> are
+ specified, then option <emphasis>routingkey</emphasis> has precedence. </para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Queue</emphasis>, is an optional part of <emphasis>Binding URL</emphasis> 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 </para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Options</emphasis>, key-value pairs separated by '=' character specifying
+ queue and exchange creation arguments, routing key, client behaviour, etc. </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <important>
+ <title>Binding URL option quoting</title>
+ <para>Take care with the quoting surrounding option values. Each option value
+ <emphasis>must</emphasis> be surrounded with single quotes ('). </para>
+ </important>
+
+ <para> The following <emphasis>Binding URL</emphasis> options are currently defined: <table
+ pgwide="1">
+ <title>Binding URL options </title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>durable</para></entry>
+ <entry><para>boolean </para></entry>
+ <entry><para>Queue durability flag. If it is set to <emphasis>true</emphasis>, 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.</para></entry>
+ </row>
+ <row>
+ <entry><para>exclusive</para></entry>
+ <entry><para>boolean </para></entry>
+ <entry><para>Queue exclusivity flag. The client cannot use a queue that was declared as
+ exclusive by another still-open connection.</para></entry>
+ </row>
+ <row>
+ <entry><para>autodelete</para></entry>
+ <entry><para>boolean </para></entry>
+ <entry><para>Queue auto-deletion flag. If it is set to <emphasis>true</emphasis> on
+ queue creation, the queue is deleted if there are no remaining
+ subscribers.</para></entry>
+ </row>
+ <row>
+ <entry><para>exchangeautodelete</para></entry>
+ <entry><para>boolean </para></entry>
+ <entry><para>Exchange auto-deletion flag.</para></entry>
+ </row>
+ <row>
+ <entry><para>exchangedurable</para></entry>
+ <entry><para>boolean </para></entry>
+ <entry><para>Exchange durability flag. If it is set to <emphasis>true</emphasis> 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.</para></entry>
+ </row>
+ <row>
+ <entry><para>routingkey</para></entry>
+ <entry><para>string </para></entry>
+ <entry>
+ <para> 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 <emphasis>Binding URL</emphasis> and direct exchange class is specified, the
+ queue name is used as a routing key. <emphasis>MessagePublisher</emphasis> uses
+ routing key to publish messages onto exchange. </para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>browse</para></entry>
+ <entry><para>boolean </para></entry>
+ <entry><para>If set to <emphasis>true</emphasis> 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.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-Binding-URL-Options-RejectBehaviour">
+ <entry><para>rejectbehaviour</para></entry>
+ <entry><para>string </para></entry>
+ <entry><para>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. </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <section id="JMS-Client-0-8-Binding-URL-Examples">
+ <title>Binding URL Examples</title>
+
+ <section id="JMS-Client-0-8-Binding-URL-JMS-Queues" role="h4">
+ <title>Binding URLs for declaring of JMS Queues</title>
+ <para>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.): <screen><![CDATA[
+direct://amq.direct//<Queue Name>
+ ]]></screen>
+ </para>
+ <para>The Binding URLs for destinations created with calls to
+ <emphasis>Session.createQueue(String)</emphasis> can be expressed as <screen><![CDATA[
+direct://amq.direct//<Queue Name>?durable='true'
+ ]]></screen> The durability flag is set to <emphasis>true</emphasis> in such destinations. </para>
+ <example>
+ <title>Binding URL examples for JMS queues</title>
+ <screen><![CDATA[
+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
+ ]]></screen>
+ </example>
+ </section>
+
+ <section id="JMS-Client-0-8-Binding-URL-JMS-Topics" role="h4">
+ <title>Binding URLs for declaring of JMS Topics</title>
+ <para>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): <screen><![CDATA[
+topic://amq.topic//<Queue name>?routingkey='<Topic Name>'&exclusive='true'&autodelete='true'
+ ]]></screen>
+ </para>
+ <para>The Binding URLs for a topic destination created with calls to
+ <emphasis>Session.createTopic("hello")</emphasis> is provided below: <example>
+ <title>Binding URL examples for JMS topics</title>
+ <screen><![CDATA[
+topic://amq.topic/hello/tmp_127_0_0_1_36973_1?routingkey='hello'&exclusive='true'&autodelete='true'
+ ]]></screen>
+ </example>
+ </para>
+ </section>
+
+ <section id="JMS-Client-0-8-Binding-URL-Topics-Wildcards" role="h4">
+ <title>Wildcard characters in routing keys for topic destinations</title>
+ <para> AMQP exchanges of class <emphasis>topic</emphasis> 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. </para>
+ <para> The examples of the <emphasis>Binding URLs</emphasis> having routing keys with
+ wildcards characters are provided below: <screen><![CDATA[
+topic://amq.topic?routingkey='stocks.#'
+topic://amq.topic?routingkey='stocks.*.ibm'
+topic://amq.topic?routingkey='stocks.nyse.ibm'
+ ]]></screen>
+ </para>
+ </section>
+
+ <section id="JMS-Client-0-8-Binding-URL-Extra-Examples" role="h4">
+ <title>More Examples</title>
+ <table>
+ <title>Binding URL examples</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Binding URL</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>fanout://amq.fanout//myQueue</para></entry>
+ <entry><para>Binding URL binding queue "myQueue" to predefined "amq.fanout" exchange
+ of class "fanout"</para></entry>
+ </row>
+ <row>
+ <entry><para>topic://custom.topic//anotherQueue?routingkey='aq'</para></entry>
+ <entry><para>Binding URL binding queue "anotherQueue" to the exchange with name
+ "custom.topic" of class "topic" using binding key "aq".</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ </section>
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
new file mode 100644
index 0000000..956981e
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0"?>
+<!--
+
+ 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.
+
+-->
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>Qpid JMS Client for AMQP protocols 0-8, 0-9 and 0-9-1</title>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Introduction.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Document-Scope-And-Intended-Audience.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Getting-And-Dependencies.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Examples.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Understanding.xml"/>
+ <!-- TODO:
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JMS-Extensions.xml"/>
+ -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JNDI-Properties-Format.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Connection-URL.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Binding-URL.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-System-Properties.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Logging.xml"/>
+
+ <!-- TODO:
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Interoperability.xml"/>
+ -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-Exceptions.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-Maven.xml"/>
+
+
+
+</book>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
new file mode 100644
index 0000000..09ad985
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
@@ -0,0 +1,324 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-Connection-URL">
+ <title>Connection URLs</title>
+ <para> In JNDI properties, a Connection URL specifies options for a connection. The format for a
+ Connection URL is: </para>
+
+ <programlisting><![CDATA[amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>=&'<value>']]]]></programlisting>
+ <para> For instance, the following Connection URL specifies a user name, a password, a client
+ ID, a virtual host ("test"), a broker list with a single broker: a TCP host with the host
+ name <quote>localhost</quote> using port 5672: </para>
+
+ <programlisting><![CDATA[amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672']]></programlisting>
+
+ <important>
+ <title>Connection option quoting</title>
+ <para>Take care with the quoting surrounding option values. Each option value
+ <emphasis>must</emphasis> be surrounded with single quotes ('). </para>
+ </important>
+
+ <para>The Connection URL supports the following options:</para>
+ <table pgwide="1" id="JMS-Client-0-8-Connection-URL-Options">
+ <title>Connection URL Options</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry> Option </entry>
+ <entry> Type </entry>
+ <entry> Description </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-Brokerlist">
+ <entry> brokerlist </entry>
+ <entry> see below </entry>
+ <entry> List of one or more broker addresses. </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-Maxprefetch">
+ <entry> maxprefetch </entry>
+ <entry> integer </entry>
+ <entry>
+ <para> The maximum number of pre-fetched messages per Session. If not
+ specified, default value of 500 is used. </para>
+ <para> Note: You can also set the default per-session prefetch value on a
+ client-wide basis by configuring the client using <link
+ linkend="JMS-Client-0-8-System-Properties">Java system
+ properties.</link>
+ </para>
+ </entry>
+ </row>
+ <!-- 0-10 only
+ <row>
+ <entry> sync_publish </entry>
+ <entry> {'persistent' | 'all'} </entry>
+ <entry> A sync command is sent after every persistent message to guarantee that
+ it has been received; if the value is 'persistent', this is done only for
+ persistent messages. </entry>
+ </row>
+ -->
+ <!-- 0-10 only
+ <row>
+ <entry> sync_ack </entry>
+ <entry> Boolean </entry>
+ <entry> A sync command is sent after every acknowledgement to guarantee that it
+ has been received. </entry>
+ </row>
+ -->
+ <row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-UseLegacyMap">
+ <entry> use_legacy_map_msg_format </entry>
+ <entry> Boolean </entry>
+ <entry> If you are using JMS Map messages and deploying a new client with any
+ JMS client older than 0.8 release, you must set this to true to ensure the
+ older clients can understand the map message encoding. </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-Failover">
+ <entry> failover </entry>
+ <entry> {'singlebroker' | 'roundrobin'
+ ,<!-- Cpp/0-10 only | 'failover_exchange' --> | 'nofailover' |
+ '<class>'} </entry>
+ <entry>
+ <para> This option controls failover behaviour. The method
+ <literal>singlebroker</literal> uses only the first broker in the
+ list, <literal>roundrobin</literal> will try each broker given in the
+ broker list until a connection is established,
+ <!--<literal>failover_exchange</literal> connects to the initial broker
+ given in the broker URL and will receive membership updates via the
+ failover exchange. --><literal>nofailover</literal>
+ disables all retry and failover logic. Any other value is interpreted as
+ a classname which must implement the
+ <literal>org.apache.qpid.jms.failover.FailoverMethod</literal>
+ interface. </para>
+ <para> The broker list options <literal>retries</literal> and
+ <literal>connectdelay</literal> (described below) determine the
+ number of times a connection to a broker will be retried and the
+ length of time to wait between successive connection attempts before
+ moving on to the next broker in the list. The failover option
+ <literal>cyclecount</literal> controls the number of times to loop
+ through the list of available brokers before finally giving up. </para>
+ <para> Defaults to <literal>roundrobin</literal> if the brokerlist contains
+ multiple brokers, or <literal>singlebroker</literal> otherwise. </para>
+ </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-CloseWhenNoRoute">
+ <entry> closeWhenNoRoute </entry>
+ <entry> boolean </entry>
+ <entry>
+ <para>See <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-CloseWhenNoRoute"
+ />.</para>
+ </entry>
+ </row>
+ <row>
+ <entry> ssl </entry>
+ <entry> boolean </entry>
+ <entry>
+ <para> If <literal>ssl='true'</literal>, use SSL for all broker connections.
+ Overrides any per-broker settings in the brokerlist (see below) entries.
+ If not specified, the brokerlist entry for each given broker is used to
+ determine whether SSL is used. </para>
+ <para> Introduced in version 0.22. </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para> Broker lists are specified using a URL in this format: </para>
+
+ <programlisting><(&<param>='<value>')*]]></programlisting>
+ <para> For instance, this is a typical broker list: </para>
+
+ <programlisting><![CDATA[brokerlist='tcp://localhost:5672']]></programlisting>
+
+ <para> A broker list can contain more than one broker address; if so, the connection is made to
+ the first broker in the list that is available.
+ <!--In general, it is better to use the failover
+ exchange when using multiple brokers, since it allows applications to fail over if a broker
+ goes down.--></para>
+
+ <example>
+ <title>Broker Lists</title>
+ <para>A broker list can specify properties to be used when connecting to the broker. This
+ broker list specifies options for configuring heartbeating</para>
+ <programlisting><![CDATA[amqp://guest:guest@test/test?brokerlist='tcp://ip1:5672?heartbeat='5'']]></programlisting>
+
+ <para>This broker list specifies some SSL options</para>
+
+ <programlisting><![CDATA[amqp://guest:guest@test/test?brokerlist='tcp://ip1:5672?ssl='true'&ssl_cert_alias='cert1'']]></programlisting>
+
+ <para> This broker list specifies two brokers using the connectdelay and retries broker
+ options. It also illustrates the failover connection URL property. </para>
+
+ <programlisting><![CDATA[amqp://guest:guest@/test?failover='roundrobin?cyclecount='2''
+ &brokerlist='tcp://ip1:5672?retries='5'&connectdelay='2000';tcp://ip2:5672?retries='5'&connectdelay='2000''
+ ]]></programlisting>
+ </example>
+
+ <important>
+ <title>Broker option quoting</title>
+ <para>Take care with the quoting surrounding broker option values. Each broker option value
+ <emphasis>must</emphasis> be surrounded with their own single quotes ('). This is in
+ addition to the quotes surround the connection option value.</para>
+ </important>
+
+ <para>The following broker list options are supported.</para>
+
+ <table pgwide="1">
+ <title>Broker List Options</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry> Option </entry>
+ <entry> Type </entry>
+ <entry> Description </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-Heartbeat">
+ <entry> heartbeat </entry>
+ <entry> Long </entry>
+ <entry> Frequency of heartbeat messages (in seconds). A value of 0 disables
+ heartbeating. <para>For compatibility with old client configuration, option
+ <varname>idle_timeout</varname> (in milliseconds) is also
+ supported.</para>
+ </entry>
+ </row>
+ <!-- 0-10 only
+ <row>
+ <entry> sasl_mechs </entry>
+ <entry> - </entry>
+ <entry> For secure applications, we suggest CRAM-MD5, DIGEST-MD5, or GSSAPI. The
+ ANONYMOUS method is not secure. The PLAIN method is secure only when used
+ together with SSL. For Kerberos, sasl_mechs must be set to GSSAPI,
+ sasl_protocol must be set to the principal for the qpidd broker, e.g.
+ qpidd/, and sasl_server must be set to the host for the SASL server, e.g.
+ sasl.com. SASL External is supported using SSL certification, e.g.
+ <literal>ssl='true'&sasl_mechs='EXTERNAL'</literal>
+ </entry>
+ </row>
+ <row>
+ <entry> sasl_encryption </entry>
+ <entry> Boolean </entry>
+ <entry> If <literal>sasl_encryption='true'</literal>, the JMS client attempts to
+ negotiate a security layer with the broker using GSSAPI to encrypt the
+ connection. Note that for this to happen, GSSAPI must be selected as the
+ sasl_mech. </entry>
+ </row>
+ <row>
+ <entry> sasl_protocol </entry>
+ <entry> - </entry>
+ <entry> Used only for Kerberos. <literal>sasl_protocol</literal> must be set to
+ the principal for the qpidd broker, e.g. <literal>qpidd/</literal>
+ </entry>
+ </row>
+ <row>
+ <entry> sasl_server </entry>
+ <entry> - </entry>
+ <entry> For Kerberos, sasl_mechs must be set to GSSAPI, sasl_server must be set
+ to the host for the SASL server, e.g. <literal>sasl.com</literal>. </entry>
+ </row>
+ -->
+ <row>
+ <entry> ssl </entry>
+ <entry> Boolean </entry>
+ <entry>
+ <para>If <literal>ssl='true'</literal>, the JMS client will encrypt the
+ connection to this broker using SSL.</para>
+ <para>This can also be set/overridden for all brokers using the Connection
+ URL option <literal>ssl</literal>.</para>
+ </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-TrustStore">
+ <entry> trust_store </entry>
+ <entry> String </entry>
+ <entry> Path to trust store. Used when using SSL and the Broker's certificate is
+ signed by a private-CA (or a self-signed certificate),</entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-TrustStorePassword">
+ <entry> trust_store_password </entry>
+ <entry> String </entry>
+ <entry> Trust store password. Password used to open the trust store. </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-KeyStore">
+ <entry> key_store </entry>
+ <entry> String </entry>
+ <entry> Path to key store . Used when using SSL and the client must authenticate
+ using client-auth. If the store contains more than one certificate,
+ <literal>ssl_cert_alias</literal> must be used to identify the
+ certificate that the client must present to the Broker.</entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-KeyStorePassword">
+ <entry> key_store_password </entry>
+ <entry> String </entry>
+ <entry> Key store password. Password used to open the key store. </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-SslCertAlias">
+ <entry> ssl_cert_alias </entry>
+ <entry> String </entry>
+ <entry> If multiple certificates are present in the keystore, the alias will be
+ used to extract the correct certificate. </entry>
+ </row>
+ <row>
+ <entry> ssl_verify_hostname </entry>
+ <entry> Boolean </entry>
+ <entry> When using SSL you can enable hostname verification by using
+ <literal>ssl_verify_hostname='true'</literal> in the broker URL.
+ </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-Retries">
+ <entry> retries </entry>
+ <entry> Integer </entry>
+ <entry> The number of times to retry connection to each broker in the broker
+ list. Defaults to 1. </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-ConnectDelay">
+ <entry> connectdelay </entry>
+ <entry> integer </entry>
+ <entry> Length of time (in milliseconds) to wait before attempting to reconnect.
+ Defaults to 0. </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-ConnectTimeout">
+ <entry> connecttimeout </entry>
+ <entry> integer </entry>
+ <entry> Length of time (in milliseconds) to wait for the socket connection to
+ succeed. A value of 0 represents an infinite timeout, i.e. the connection
+ attempt will block until established or an error occurs. Defaults to 30000.
+ </entry>
+ </row>
+ <row id="JMS-Client-0-8-Connection-URL-BrokerOptions-TcpNoDelay">
+ <entry> tcp_nodelay </entry>
+ <entry> Boolean </entry>
+ <entry> If <literal>tcp_nodelay='true'</literal>, TCP packet batching is
+ disabled. Defaults to true since Qpid 0.14. </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
new file mode 100644
index 0000000..234a286
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
@@ -0,0 +1,64 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-Document-Scope-And-Intended-Audience">
+ <title>Document Scope And Intended Audience</title>
+
+ <para> The intended audience of this document is Java developers who are familiar with the JMS
+ specification. Readers are not required to know all the details of AMQP protocols. However, some
+ knowledge of AMQP basic concepts would be advantageous for reading of this document. </para>
+
+ <para> This document only covers the usage of 0-8, 0-9 and 0-9-1 AMQP protocols with Qpid JMS
+ client. The specifications for these protocols are available from the <ulink
+ url="&amqpSrc;">AMQP web site</ulink>. </para>
+
+ <para> The document covers some specific implementation details of JMS connections, sessions,
+ consumers and producers in <xref linkend="JMS-Client-0-8-Client-Understanding"/>. It also
+ demonstrates how to write a simple point to point and simple publish/subscribe application using
+ Qpid JMS Client in <xref linkend="JMS-Client-0-8-Examples"/>. </para>
+
+ <para>The Qpid JMS Client supports various configuration options which can be set via JVM system
+ properties, connection URLs and JNDI configuration file. The setting of system properties is
+ described in <xref linkend="JMS-Client-0-8-System-Properties"/>. The details of supported
+ options within the connection URLs are given in <xref linkend="JMS-Client-0-8-Connection-URL"/>.
+ The details of Qpid JMS client JNDI properties format is provided in <xref
+ linkend="JMS-Client-0-8-JNDI-Properties-Format"/>. The Qpid destination URL format is covered
+ in <xref linkend="JMS-Client-0-8-Binding-URL"/>. </para>
+
+ <para>The Qpid JMS Client can be used for writing of JMS vendor neutral messaging applications.
+ However, in some cases it might be required to use specific AMQP features. Thus, the Qpid client
+ provides the extended operation set to invoke those features. </para>
+
+ <para>
+ <xref linkend="JMS-Client-0-8-Logging"/> provides the details about turning on client logging
+ which can help in debugging of various issues while developing the messaging applications. </para>
+
+ <para>The details about Qpid JMS Client Exceptions are provided in <xref
+ linkend="JMS-Client-0-8-Appendix-Exceptions"/></para>
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml
new file mode 100644
index 0000000..87abbb8
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml
@@ -0,0 +1,297 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-Examples">
+ <title>Examples</title>
+
+ <para>The following programs shows how to send and receive messages using the Qpid JMS client.
+ The first program illustrates a <emphasis>point to point</emphasis> example, the second, a
+ pubish/subscribe example. </para>
+ <para>Both examples show the use JNDI to obtain connection factory and destination objects which
+ the application needs. In this way the configuration is kept separate from the application
+ code itself.</para>
+ <para>The example code will be straightforward for anyone familiar with Java JMS. Readers in
+ need of an introduction are directed towards <ulink url="&oracleJmsTutorial;">Oracle's JMS
+ tutorial</ulink>.</para>
+ <section id="JMS-Client-0-8-Examples-PTP">
+ <title>Point to point example</title>
+ <para>In this example, we illustrate point to point messaging. We create a JNDI context
+ using a properties file, use the context to lookup a connection factory, create and
+ start a connection, create a session, and lookup a destination (a queue) from the JNDI
+ context. Then we create a producer and a consumer, send a message with the producer and
+ receive it with the consumer.</para>
+
+ <example id="JMS-Client-0-8-Examples-PTP-Java">
+ <title>JMS Example - Point to Point Messaging</title>
+ <programlisting language="java">
+import javax.jms.*;
+import javax.naming.Context;
+import javax.naming.InitialContext;
+import java.util.Properties;
+
+public class Hello {
+
+ public Hello() {
+ }
+
+ public static void main(String[] args) throws Exception {
+ Hello hello = new Hello();
+ hello.runTest();
+ }
+
+ private void runTest() throws Exception {
+ Properties properties = new Properties();
+ properties.load(this.getClass().getResourceAsStream("helloworld.properties")); <co id="ptp-java-properties" linkends="callout-ptp-properties"/>
+ Context context = new InitialContext(properties); <co id="ptp-java-context" linkends="callout-ptp-context"/>
+
+ ConnectionFactory connectionFactory
+ = (ConnectionFactory) context.lookup("qpidConnectionFactory"); <co id="ptp-java-connection-factory" linkends="callout-ptp-connection-factory"/>
+ Connection connection = connectionFactory.createConnection(); <co id="ptp-java-connection" linkends="callout-ptp-connection"/>
+ connection.start(); <co id="ptp-java-start" linkends="callout-ptp-start"/>
+
+ Session session = connection.createSession(true, Session.SESSION_TRANSACTED); <co id="ptp-java-session" linkends="callout-ptp-session"/>
+ Queue queue = (Queue) context.lookup("myqueue"); <co id="ptp-java-destination" linkends="callout-ptp-destination"/>
+
+ MessageConsumer messageConsumer = session.createConsumer(queue); <co id="ptp-java-consumer" linkends="callout-ptp-consumer"/>
+ MessageProducer messageProducer = session.createProducer(queue); <co id="ptp-java-producer" linkends="callout-ptp-producer"/>
+
+ TextMessage message = session.createTextMessage("Hello world!"); <co id="ptp-java-send" linkends="callout-ptp-send"/>
+ messageProducer.send(message);
+ session.commit();
+
+ message = (TextMessage)messageConsumer.receive(); <co id="ptp-java-receive" linkends="callout-ptp-receive"/>
+ session.commit();
+ System.out.println(message.getText());
+
+ connection.close(); <co id="ptp-java-close" linkends="callout-ptp-close"/>
+ context.close(); <co id="ptp-java-jndi-close" linkends="callout-ptp-jndi-close"/>
+ }
+}
+ </programlisting>
+ </example>
+
+ <calloutlist>
+ <callout id="callout-ptp-properties" arearefs="ptp-java-properties">
+ <para>Loads the JNDI properties file, which specifies the connection factory, queues
+ and topics. See <xref linkend="JMS-Client-0-8-JNDI-Properties-Format"/> for
+ details.</para>
+ </callout>
+ <callout id="callout-ptp-context" arearefs="ptp-java-context">
+ <para>Creates the JNDI initial context.</para>
+ </callout>
+ <callout id="callout-ptp-connection-factory" arearefs="ptp-java-connection-factory">
+ <para>Looks up a JMS connection factory for Qpid.</para>
+ </callout>
+ <callout id="callout-ptp-connection" arearefs="ptp-java-connection">
+ <para>Creates a JMS connection. Creating the JMS connections establishes the
+ connection to the Broker.</para>
+ </callout>
+ <callout id="callout-ptp-start" arearefs="ptp-java-start">
+ <para>Starts the connection, required for the consumption of messages.</para>
+ </callout>
+ <callout id="callout-ptp-session" arearefs="ptp-java-session">
+ <para>Creates a transactional session.</para>
+ </callout>
+ <callout id="callout-ptp-destination" arearefs="ptp-java-destination">
+ <para>Looks up a destination for the queue with JNDI name <emphasis>myqueue</emphasis>.</para>
+ </callout>
+ <callout id="callout-ptp-consumer" arearefs="ptp-java-consumer">
+ <para>Creates a consumer that reads messages from the queue<footnote>
+ <para>Creating consumer will automatically create the queue on the Broker
+ and bind it to an exchange. Specifically, in this case as the
+ <literal>queue.</literal> form is used in the JNDI properties the
+ effect will be to create a queue called <literal>queue1</literal> on the
+ Broker, and create a binding between the <literal>amq.direct</literal>
+ exchange and this queue using the queue's name. This process is
+ described in detail in <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageConsumer-ConsumerSideEffect"
+ /></para>
+ </footnote>.</para>
+ </callout>
+ <callout id="callout-ptp-producer" arearefs="ptp-java-producer">
+ <para>Creates a producer that sends messages to the queue.</para>
+ </callout>
+ <callout id="callout-ptp-send" arearefs="ptp-java-send">
+ <para>Creates a new message of type <emphasis>javax.jms.TextMessage</emphasis>, publishes the message and commits the
+ session.</para>
+ </callout>
+ <callout id="callout-ptp-receive" arearefs="ptp-java-receive">
+ <para>Reads the next available message (awaiting indefinitely if necessary) and
+ commits the session.</para>
+ </callout>
+ <callout id="callout-ptp-close" arearefs="ptp-java-close">
+ <para>Closes the Connection. All sessions owned by the Connection along with their
+ MessageConsumers and MessageProducers are automatically closed. The connection
+ to the Broker is closed as this point.</para>
+ </callout>
+ <callout id="callout-ptp-jndi-close" arearefs="ptp-java-jndi-close">
+ <para>Closes the JNDI context.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The contents of the <literal>helloworld.properties</literal> file are shown
+ below.</para>
+
+ <example id="JMS-Client-0-8-Examples-PTP-PropertiesFile">
+ <title>JMS Example - Point to Point Messaging - JNDI Properties</title>
+ <programlisting language="properties">
+java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
+connectionfactory.qpidConnectionFactory = amqp://guest:guest@clientid/?brokerlist='tcp://localhost:5672' <co id="ptp-properties-connectionfactory" linkends="callout-ptp-properties-connectionfactory"/>
+queue.myqueue = queue1 <co id="ptp-properties-destination" linkends="callout-ptp-properties-destination"/>
+ </programlisting>
+ </example>
+
+ <calloutlist>
+ <callout id="callout-ptp-properties-connectionfactory"
+ arearefs="ptp-properties-connectionfactory">
+ <para>Defines a connection factory from which Connections can be created. The syntax
+ of a ConnectionURL is given in <xref
+ linkend="JMS-Client-0-8-Connection-URL"/>.</para>
+ </callout>
+ <callout id="callout-ptp-properties-destination" arearefs="ptp-properties-destination">
+ <para>Defines a queue for which MessageProducers and/or MessageConsumers send and
+ receive messages. The format of these entries is described in <xref
+ linkend="JMS-Client-0-8-JNDI-Properties-Format-Queue"/>.</para>
+ </callout>
+ </calloutlist>
+ </section>
+ <section id="JMS-Client-0-8-Examples-PubSub">
+ <title>Publish/subscribe example</title>
+ <para>In this second example, we illustrate publish/subscribe messaging. Again, we create a
+ JNDI context using a properties file, use the context to lookup a connection factory,
+ create and start a connection, create a session, and lookup a destination (a topic) from
+ the JNDI context. Then we create a producer and two durable subscribers , send a message
+ with the producer. Both subscribers receive the same message.</para>
+
+ <example id="JMS-Client-0-8-Examples-PubSub-Java">
+ <title>JMS Example - Publish/subscribe Messaging</title>
+ <programlisting language="java">
+import javax.jms.*;
+import javax.naming.Context;
+import javax.naming.InitialContext;
+
+import java.util.Properties;
+
+public class StocksExample {
+
+ public StocksExample() {
+ }
+
+ public static void main(String[] args) throws Exception {
+ StocksExample stocks = new StocksExample();
+ stocks.runTest();
+ }
+
+ private void runTest() throws Exception {
+ Properties properties = new Properties();
+ properties.load(this.getClass().getResourceAsStream("stocks.properties"));
+ Context context = new InitialContext(properties);
+
+ ConnectionFactory connectionFactory
+ = (ConnectionFactory) context.lookup("qpidConnectionFactory");
+ Connection connection = connectionFactory.createConnection();
+ connection.start();
+
+ Session session = connection.createSession(true, Session.SESSION_TRANSACTED);
+ Topic priceTopic = (Topic) context.lookup("myprices"); <co id="pubsub-java-destination" linkends="callout-pubsub-destination"/>
+
+ MessageConsumer subscriber1 = session.createDurableSubscriber(priceTopic, "sub1"); <co id="pubsub-java-subscribers" linkends="callout-pubsub-subscribers"/>
+ MessageConsumer subscriber2 = session.createDurableSubscriber(priceTopic, "sub2" /*, "price > 150", false*/ );
+ MessageProducer messageProducer = session.createProducer(priceTopic);
+
+ Message message = session.createMessage();
+ message.setStringProperty("instrument", "IBM");
+ message.setIntProperty("price", 100);
+ messageProducer.send(message);
+ session.commit();
+
+ message = subscriber1.receive(1000);
+ session.commit();
+ System.out.println("Subscriber 1 received : " + message);
+
+ message = subscriber2.receive(1000);
+ session.commit();
+ System.out.println("Subscriber 2 received : " + message);
+
+ session.unsubscribe("sub1"); <co id="pubsub-java-unsubscribe" linkends="callout-pubsub-unsubscribe"/>
+ session.unsubscribe("sub2");
+ connection.close();
+ context.close();
+ }
+}
+ </programlisting>
+ </example>
+
+ <calloutlist>
+ <callout id="callout-pubsub-destination" arearefs="pubsub-java-destination">
+ <para>Looks up a destination for the topic with JNDI name myprices.</para>
+ </callout>
+ <callout id="callout-pubsub-subscribers" arearefs="pubsub-java-subscribers">
+ <para>Creates two durable subscribers, <literal>sub1</literal> and
+ <literal>sub2</literal>. Durable subscriptions retain messages for the
+ client even when the client is disconnected, until the subscription is
+ unsubscribed. Subscription 2 has a (commented out) message selector argument so
+ you can conveniently experiement with the effect of those. <footnote>
+ <para>Each durable subscription is implemented as a queue on the Broker. See
+ <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageConsumer-TopicSubscriptions"
+ /> for details.</para>
+ </footnote></para>
+ </callout>
+ <callout id="callout-pubsub-unsubscribe" arearefs="pubsub-java-unsubscribe">
+ <para>Unsubscribes the two durable subscribers, permanently removing the knowledge
+ of the subscriptions from the system. An application would normally
+ <emphasis>NOT</emphasis> do this. The typical use-case for durable
+ subsciption is one where the subscription exists over an extended period of
+ time.</para>
+ </callout>
+ </calloutlist>
+
+ <para>The contents of the <literal>stocks.properties</literal> file are shown below.</para>
+
+ <example id="JMS-Client-0-8-Examples-PubSub-PropertiesFile">
+ <title>JMS Example - Publish/subscribe Messaging - JNDI Properties</title>
+ <programlisting>
+java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
+connectionfactory.qpidConnectionFactory = amqp://guest:guest@clientid/?brokerlist='tcp://localhost:5672'
+topic.myprices = prices <co id="pubsub-properties-destination" linkends="callout-pubsub-properties-destination"/>
+ </programlisting>
+ </example>
+
+ <calloutlist>
+ <callout id="callout-pubsub-properties-destination"
+ arearefs="pubsub-properties-destination">
+ <para>Defines a topic for which MessageProducers and/or MessageConsumers send and
+ receive messages. The format of this entry is described in <xref
+ linkend="JMS-Client-0-8-JNDI-Properties-Format-Topic"/>.</para>
+ </callout>
+ </calloutlist>
+ </section>
+
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml
new file mode 100644
index 0000000..bae5278
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml
@@ -0,0 +1,68 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-JMS-Getting-And-Dependencies">
+ <title>Getting the Client And Dependencies</title>
+ <section id="JMS-Client-0-8-JMS-Getting-And-Dependencies-Getting">
+ <title>Getting the Client</title>
+ <para>The Qpid JMS client is available as a bundle or from &qpidMavenRepoDesc;.</para>
+ <para>The bundle (a .tar.gz) includes the Qpid JMS client itself (formed by two JAR: qpid-client
+ and qpid-common) together with slf4j-api, and geronimo-jms_1.1_spec. There is also a qpid-all
+ JAR artifact that, for convenience, includes a manifest classpath that references the other
+ JARs. The bundle is available from <ulink url="&qpidDownloadUrl;"
+ >&qpidDownloadUrlDesc;</ulink>.</para>
+ <para>The Qpid JMS client is also available from &qpidMavenRepoDesc;. Add the following
+ dependency:</para>
+ <screen><![CDATA[
+ <dependency>
+ <groupId>]]>&qpidClientGroupId;<![CDATA[</groupId>
+ <artifactId>]]>&qpidClientArtefactId;<![CDATA[</artifactId>
+ <version>]]>&qpidVersion;<![CDATA[</version>
+ </dependency>
+ ]]></screen>
+ <para><xref linkend="JMS-Client-0-8-Appendix-Maven"/> illustrates a minimal Maven POM required to use the Qpid Client.</para>
+ </section>
+ <section id="JMS-Client-0-8-JMS-Getting-And-Dependencies-Dependencies">
+ <title>Dependencies</title>
+ <para>The Qpid JMS client has minimal set of external dependencies. </para>
+ <para> It requires: <itemizedlist>
+ <listitem>
+ <para>JDK 1.6 or higher. (An up to date JDK 1.7 is recommended)</para>
+ </listitem>
+ <listitem>
+ <para>JMS 1.1 specification (such as geronimo-jms_1.1_spec JAR)</para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://www.slf4j.org">Apache SLF4J</ulink> (slf4j-api-x.y.z JAR)</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>The use of SLF4J means that application authors are free to plug in any logging framework
+ for which an SLF4J binding exists. </para>
+ </section>
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml
new file mode 100644
index 0000000..3707e89
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml
@@ -0,0 +1,49 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<!-- TODO add dependencies + getting the client -->
+
+<chapter id="JMS-Client-0-8-Introduction">
+ <title>Introduction</title>
+ <para>Qpid JMS client is an implementation of <ulink url="&oracleJmsSpec;">JMS specification
+ 1.1</ulink>. It utilises an <ulink url="&amqpSrc;">AMQP</ulink> transport layer for the performing of messaging operations.
+ The client is intended to be used for the writing of JMS compatible messaging applications. Such
+ applications can send and receive messages via any AMQP-compatible brokers like RabbitMQ, Qpid
+ Java Broker which support the AMQP protocols 0-8, 0-9, or 0-9-1.</para>
+ <para>The Qpid JMS client hides the details of AMQP transport implementation behind the JMS API.
+ Thus, the developers need only to be familiar with JMS API in order to use the client. However,
+ the knowledge of the basic concepts of AMQP protocols can help developers in writing reliable
+ and high-performant messaging application. </para>
+ <important>
+ <title>Using the Qpid JMS client with 0-10</title>
+ <para>This book documents the behaviour of the Qpid JMS client when used with the AMQP
+ protocols <emphasis>0-8, 0-9, and 0-9-1</emphasis> only. For behaviour when using the client
+ with AMQP 0-10 protocol, please refer to <ulink url="&qpidProgrammingBook;">Programming in Apache Qpid</ulink>.</para>
+ </important>
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml
new file mode 100644
index 0000000..bdc7832
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml
@@ -0,0 +1,33 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-JMS-Extensions">
+ <title>JMS Extensions</title>
+
+ <para>TODO</para>
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml
new file mode 100644
index 0000000..fb7d96f
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-JNDI-Properties-Format">
+ <title>JNDI Properties Format</title>
+
+ <para>The Qpid JMS Client comes with own JNDI context factory
+ <literal>org.apache.qpid.jndi.PropertiesFileInitialContextFactory</literal> which utilises a
+ Java properties file for declaring the JMS administered objects: connection factories, queues,
+ topics and destinations. It uses the following syntax:</para>
+ <para>
+ <screen><![CDATA[
+connectionfactory.<jndi name>=<connection url>
+queue.<jndi name>=<queue name>
+topic.<jndi name>=<topic name>
+destination.<jndi name>=<binding url>
+]]></screen></para>
+ <para>An arbitrary number of connection factories, queues, topics, queues or destinations or can
+ be declared in the JNDI properties file. Each JNDI name must be unique.</para>
+ <para>The application looks up the objects via an InitialContext. This lookup and an example JNDI
+ properties file is provided in <xref linkend="JMS-Client-0-8-Examples"/></para>
+ <para>We now consider each JMS administered object type in turn.</para>
+
+ <section id="JMS-Client-0-8-JNDI-Properties-Format-ConnectionFactory">
+ <title>ConnectionFactory</title>
+ <para><literal>connectionfactory.</literal><emphasis>name</emphasis> declares a <ulink
+ url="&oracleJeeDocUrl;javax/jms/ConnectionFactory.html">ConnectionFactory</ulink> with the
+ given JNDI name. The value must be a legal Connection URL.</para>
+ <para>See <xref linkend="JMS-Client-0-8-Connection-URL"/> for format of the URL and its
+ permitted options.</para>
+ </section>
+ <section id="JMS-Client-0-8-JNDI-Properties-Format-Queue">
+ <title>Queue</title>
+ <para><literal>queue.</literal><emphasis>name</emphasis> declares a <ulink
+ url="&oracleJeeDocUrl;javax/jms/Queue.html">Queue</ulink> with the given JNDI name. The
+ value is simple queue name. This is the name of the queue as known by the Broker.</para>
+ <para>The <literal>queue.</literal> form is a short hand for declaring a destination:</para>
+ <screen><![CDATA[destination.name=direct://amq.direct//<queue name>?routingkey=’<queue name>’&durable=’true’]]></screen>
+ </section>
+ <section id="JMS-Client-0-8-JNDI-Properties-Format-Topic">
+ <title>Topic</title>
+ <para><literal>topic.</literal><emphasis>name</emphasis> declares a <ulink
+ url="&oracleJeeDocUrl;javax/jms/Topic.html">Topic</ulink> with the given JNDI name. The
+ value is topic name. This topic name is used on the Broker as a binding key between the
+ <literal>amq.topic</literal> exchange and the queue corresponding to the topic
+ subscriber.</para>
+ <para>The <literal>topic.</literal> form is a short hand for declaring a destination:</para>
+ <screen><![CDATA[destination.name=topic://amq.topic/<topic name>/?routingkey=<topic name>]]></screen>
+ </section>
+ <section id="JMS-Client-0-8-JNDI-Properties-Format-Destination">
+ <title>Destination</title>
+ <para><literal>destination.</literal><emphasis>name</emphasis> declares either a <ulink
+ url="&oracleJeeDocUrl;javax/jms/Queue.html">Queue</ulink> or <ulink
+ url="&oracleJeeDocUrl;javax/jms/Topic.html">Topic</ulink> (depending on the class) with the
+ given JNDI name. The value must be a Binding URL.</para>
+ <para>See <xref linkend="JMS-Client-0-8-Binding-URL"/> for format of the URL and its permitted
+ options.</para>
+ </section>
+
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml
new file mode 100644
index 0000000..b231972
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-Logging">
+ <title>Logging</title>
+ <para>The Qpid JMS client uses the <ulink url="http://www.slf4j.org">Apache SLF4J</ulink> logging
+ framework. All logging activity created by the client is directed through the SLF4J API. SLF4J
+ is a is a façade for other common logging frameworks. This makes it easy for application authors
+ to use their prefered logging framework in their application stack, and have the Qpid JMS Client
+ use it too. </para>
+ <para>SLF4J suppplies bindings for many common logging frameworks (<ulink
+ url="&oracleJdkDocUrl;java/util/logging/package-summary.html">JUL</ulink>, <ulink
+ url="http://logging.apache.org/log4j/1.2/">Apache Log4J</ulink>, <ulink
+ url="http://logback.qos.ch">Logback</ulink>.</para>
+ <para>Include the SLF4J binding corresponding to the logging framework of your choosen logging
+ framework on classpath. For full details, see the SLF4J <ulink url="http://www.slf4j.org"
+ >documentation</ulink>.</para>
+
+ <section id="JMS-Client-0-8-Logging-RecommendedProductionLoggingLevel">
+ <title>Recommended Production Logging Level</title>
+ <para>In production, it is recommended that you configure your logging framework is configured
+ with logger <literal>org.apache.qpid</literal> set to <literal>WARN</literal>.</para>
+ <para>If you are using Apache Log4j with a log4j.properties file, this simply means adding the
+ following line:</para>
+ <screen>
+ org.apache.qpid=WARN
+ </screen>
+ <para>If you are using another logging framework, or you are using Log4j but configuring in
+ another manner, refer to the documentation accompanying the logging framework for details of
+ how to proceed.</para>
+ </section>
+ <section id="JMS-Client-0-8-Logging-EnablingDebugLogging">
+ <title>Enabling Debug</title>
+ <para>If you are experiencing a problem, it can be informative to enable debug logging to allow
+ the behaviour of the Qpid JMS client to be understood at a deeper level.</para>
+ <para>To do this, set the <literal>org.apache.qpid</literal> logger to
+ <literal>DEBUG</literal>.</para>
+ <para>If you are using Apache Log4j with a log4j.properties file, this simply means adding (or
+ changing) the following line:</para>
+ <screen>
+ org.apache.qpid=DEBUG
+ </screen>
+ <para>If you are using another logging framework, or you are using Log4j but configuring in
+ another manner, refer to the documentation accompanying the logging framework for details of
+ how to proceed.</para>
+ </section>
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
new file mode 100644
index 0000000..e2f419c
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
@@ -0,0 +1,623 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-System-Properties">
+ <title>System Properties</title>
+ <para>The following system properties affect the behaviour of the Qpid JMS client. System
+ properties are global in nature so affect all Qpid interactions made from within the same
+ JVM. For many options, there are equivalent <link linkend="JMS-Client-0-8-Connection-URL"
+ >Connection URL</link> options allowing the option to be controlled at the level of the
+ Connection.</para>
+
+ <table pgwide="1">
+ <title>System Properties Affecting Connection Behaviour</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>qpid.amqp.version</entry>
+ <entry>string</entry>
+ <entry>0-10</entry>
+ <entry><para>Sets the AMQP version to be used - currently supports one of
+ {0-8,0-9,0-91,0-10}.</para><para>The client will begin negotiation at
+ the specified version and only negotiate downwards if the Broker does
+ not support the specified version.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-Heartbeat">
+ <entry>qpid.heartbeat</entry>
+ <entry>int</entry>
+ <entry><para>Defaults to the heartbeat value suggested by the Broker, if
+ any.</para></entry>
+ <entry>Frequency of heartbeat messages (in seconds). A value of 0 disables
+ heartbeating. <para>Two consecutive missed heartbeats will result in the
+ connection timing out.</para><para>This can also be set per connection
+ using the <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-Heartbeat"
+ >Connection URL</link> options.</para><para>For compatibility with
+ old client configuration, the synonym
+ <varname>amqj.heartbeat.delay</varname> is supported.</para></entry>
+ </row>
+ <row>
+ <entry>ignore_setclientID</entry>
+ <entry>boolean</entry>
+ <entry>false</entry>
+ <entry>If a client ID is specified in the connection URL it's used or else an ID
+ is generated. If an ID is specified after it's been set Qpid will throw an
+ exception. <para>Setting this property to 'true' will disable that check and
+ allow you to set a client ID of your choice later on.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ <table pgwide="1">
+ <title>Config Options For Session Behaviour</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row id="JMS-Client-0-8-System-Properties-DestSyntax">
+ <entry>qpid.dest_syntax</entry>
+ <entry>String</entry>
+ <entry>ADDR</entry>
+ <entry><para>The default addressing syntax. The Address (ADDR) syntax is supported when using AMQP 0-10. Binding URL (BURL)
+ is supported by AMQP protocols 0-8 through to 0-10.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-Maxprefetch">
+ <entry>max_prefetch</entry>
+ <entry>int</entry>
+ <entry>500</entry>
+ <entry><para>Maximum number of pre-fetched messages per Session. This can also
+ be defaulted for sessions created on a particular connection using the
+ <link
+ linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Maxprefetch"
+ >Connection URL</link> options.</para></entry>
+ </row>
+
+
+ <!-- 0-10
+ <row>
+ <entry>qpid.session.command_limit</entry>
+ <entry>int</entry>
+ <entry>65536</entry>
+ <entry>Limits the # of unacked commands</entry>
+ </row>
+-->
+ <!-- 0-10
+ <row>
+ <entry>qpid.session.byte_limit</entry>
+ <entry>int</entry>
+ <entry>1048576</entry>
+ <entry>Limits the # of unacked commands in terms of bytes</entry>
+ </row>
+ -->
+ <row>
+ <entry>qpid.use_legacy_map_message</entry>
+ <entry>boolean</entry>
+ <entry>false</entry>
+ <entry><para>If set will use the old map message encoding. By default the Map
+ messages are encoded using the 0-10 map encoding.</para><para>This can
+ also be set per connection using the <link
+ linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-UseLegacyMap"
+ >Connection URL</link> options.</para></entry>
+ </row>
+
+ <row>
+ <entry>qpid.jms.daemon.dispatcher</entry>
+ <entry>boolean</entry>
+ <entry>false</entry>
+ <entry><para>Controls whether the Session dispatcher thread is a daemon thread
+ or not. If this system property is set to true then the Session
+ dispatcher threads will be created as daemon threads. This setting is
+ introduced in version 0.16.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1">
+ <title>Config Options For Consumer Behaviour</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row id="JMS-Client-0-8-System-Properties-DeclareExchanges">
+ <entry>qpid.declare_exchanges</entry>
+ <entry>Boolean</entry>
+ <entry>true</entry>
+ <entry><para>If true, creating a consumer will also declare the exchange on the
+ Broker (specified within the Binding URL associated with the
+ Destination), creating it if is does not already exist.
+ </para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-DeclareQueues">
+ <entry>qpid.declare_queues</entry>
+ <entry>Boolean</entry>
+ <entry>true</entry>
+ <entry><para>If true, creating a consumer will also declare the queue on the
+ Broker (specified within the Binding URL associated with the
+ Destination), creating it if is does not already
+ exist.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-RejectBehaviour">
+ <entry>qpid.reject.behaviour</entry>
+ <entry>String</entry>
+ <entry>NORMAL</entry>
+ <entry><para>Used with the maximum delivery count feature. See <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageConsumer-MaximumDeliveryCount"
+ /> for details.</para></entry>
+ </row>
+
+ <!-- 0-10
+ <row>
+ <entry>qpid.session.max_ack_delay</entry>
+ <entry>long</entry>
+ <entry>1000 (ms)</entry>
+ <entry><para>Timer interval to flush message acks in buffer when using AUTO_ACK
+ and DUPS_OK.</para>
+ <para>When using the above ack modes, message acks are batched and sent if
+ one of the following conditions are met (which ever happens first). <itemizedlist>
+ <listitem>
+ <para>When the ack timer fires.</para>
+ </listitem>
+ <listitem>
+ <para>if un_acked_msg_count > max_prefetch/2.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>The ack timer can be disabled by setting it to 0.</para>
+ </entry>
+ </row>
+-->
+ <!-- 0-10
+ <row>
+ <entry>sync_ack</entry>
+ <entry>boolean</entry>
+ <entry>false</entry>
+ <entry><para>If set, each message will be acknowledged synchronously. When using
+ AUTO_ACK mode, you need to set this to "true", in order to get the
+ correct behaviour as described by the JMS spec.</para><para>This is set
+ to false by default for performance reasons, therefore by default
+ AUTO_ACK behaves similar to DUPS_OK.</para><para>This can also be set
+ per connection using the <link linkend="section-jms-connection-url"
+ >Connection URL</link> options.</para></entry>
+ </row>
+ -->
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1">
+ <title>Config Options For Producer Behaviour</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row id="JMS-Client-0-8-System-Properties-DefaultMandatory">
+ <entry>qpid.default_mandatory</entry>
+ <entry>Boolean</entry>
+ <entry>True</entry>
+ <entry><para>If true, messages sent to Queue destinations for which cannot be
+ routed to at least one queue on the Broker, will be returned to the
+ application. See <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-MandatoryMessage"
+ /> for more details.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-DefaultMandatoryTopic">
+ <entry>qpid.default_mandatory_topic</entry>
+ <entry>Boolean</entry>
+ <entry>False</entry>
+ <entry><para>If true, messages sent to Topic destinations for which cannot be
+ routed to at least one queue on the Broker, will be returned to the
+ application. See <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-MandatoryMessage"
+ /> for more details..</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-DefaultImmediate">
+ <entry>qpid.default_immediate</entry>
+ <entry>Boolean</entry>
+ <entry>False</entry>
+ <entry><para>If true, the message will be returned to the application unless the
+ Broker is able to route the message to at least one queue with a
+ consumer attached. See <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-ImmediateMessage"
+ /> for more details.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-FlowControlWaitFailure">
+ <entry>qpid.flow_control_wait_failure</entry>
+ <entry>Long</entry>
+ <entry>60000</entry>
+ <entry><para>Used with <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-FlowControl"
+ />. The amount of time (in milliseconds) to wait before timing
+ out.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-FlowControlWaitNotifyPeriod">
+ <entry>qpid.flow_control_wait_notify_period</entry>
+ <entry>Long</entry>
+ <entry>5000</entry>
+ <entry><para>Used with <xref
+ linkend="JMS-Client-0-8-Client-Understanding-MessageProducer-FlowControl"
+ />. The frequency at which the log message informing that the producer
+ is flow controlled .</para></entry>
+ </row>
+ <!--
+ <row>
+ <entry>sync_publish</entry>
+ <entry>string</entry>
+ <entry>"" (disabled)</entry>
+ <entry><para>If one of {persistent|all} is set then persistent messages or all
+ messages will be sent synchronously.</para><para>This can also be set
+ per connection using the <link linkend="section-jms-connection-url"
+ >Connection URL</link> options.</para></entry>
+ </row>
+ -->
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1">
+ <title>Config Options For Threading</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>qpid.thread_factory</entry>
+ <entry>string</entry>
+ <entry>org.apache.qpid.thread.DefaultThreadFactory</entry>
+ <entry><para>Specifies the thread factory to use.</para><para>If using a real
+ time JVM, you need to set the above property to
+ <varname>org.apache.qpid.thread.RealtimeThreadFactory</varname>.</para></entry>
+ </row>
+
+ <row>
+ <entry>qpid.rt_thread_priority</entry>
+ <entry>int</entry>
+ <entry>20</entry>
+ <entry><para>Specifies the priority (1-99) for Real time threads created by the
+ real time thread factory.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1">
+ <title>Config Options For I/O</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>qpid.transport</entry>
+ <entry>string</entry>
+ <entry>org.apache.qpid.transport.network.io.IoNetworkTransport</entry>
+ <entry><para>The transport implementation to be used.</para><para>A user could
+ specify an alternative transport mechanism that implements the interface
+ <varname>org.apache.qpid.transport.network.OutgoingNetworkTransport</varname>.</para></entry>
+ </row>
+ <row id="JMS-Client-0-8-System-Properties-SyncOpTimeout">
+ <entry>qpid.sync_op_timeout</entry>
+ <entry>long</entry>
+ <entry>60000</entry>
+ <entry><para>The length of time (in milliseconds) to wait for a synchronous
+ operation to complete.</para><para>For compatibility with older clients,
+ the synonym <varname>amqj.default_syncwrite_timeout</varname> is
+ supported.</para></entry>
+ </row>
+ <row>
+ <entry>qpid.tcp_nodelay</entry>
+ <entry>boolean</entry>
+ <entry>true</entry>
+ <entry>
+ <para>Sets the TCP_NODELAY property of the underlying socket. The default
+ was changed to true as of Qpid 0.14.</para>
+ <para>This can also be set per connection using the Connection URL broker
+ option<link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-TcpNoDelay"
+ ><literal>tcp_nodelay</literal>.</link> options.</para>
+ <para>For compatibility with older clients, the synonym
+ <varname>amqj.tcp_nodelay</varname> is supported.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>qpid.send_buffer_size</entry>
+ <entry>integer</entry>
+ <entry>65535</entry>
+ <entry>
+ <para>Sets the SO_SNDBUF property of the underlying socket. Added in Qpid
+ 0.16.</para>
+ <para>For compatibility with older clients, the synonym
+ <varname>amqj.sendBufferSize</varname> is supported.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>qpid.receive_buffer_size</entry>
+ <entry>integer</entry>
+ <entry>65535</entry>
+ <entry>
+ <para>Sets the SO_RCVBUF property of the underlying socket. Added in Qpid
+ 0.16.</para>
+ <para>For compatibility with older clients, the synonym
+ <varname>amqj.receiveBufferSize</varname> is supported.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>qpid.failover_method_timeout</entry>
+ <entry>long</entry>
+ <entry>60000</entry>
+ <entry>
+ <para>During failover, this is the timeout for each attempt to try to
+ re-establish the connection. If a reconnection attempt exceeds the
+ timeout, the entire failover process is aborted.</para>
+ <para>It is only applicable for AMQP 0-8/0-9/0-9-1 clients.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <!-- These are all 0-10 related
+ <table pgwide="1">
+ <title>Config Options For Security</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+
+ <row>
+ <entry>qpid.sasl_mechs</entry>
+ <entry>string</entry>
+ <entry>PLAIN</entry>
+ <entry><para>The SASL mechanism to be used. More than one could be specified as
+ a comma separated list.</para><para>We currently support the following
+ mechanisms {PLAIN | GSSAPI | EXTERNAL}.</para><para>This can also be set
+ per connection using the <link linkend="JMS-Client-0-8-Connection-URL"
+ >Connection URL</link> options.</para></entry>
+ </row>
+
+ <row>
+ <entry>qpid.sasl_protocol</entry>
+ <entry>string</entry>
+ <entry>AMQP</entry>
+ <entry><para>When using GSSAPI as the SASL mechanism,
+ <varname>sasl_protocol</varname> must be set to the principal for
+ the qpidd broker, e.g. <varname>qpidd</varname>.</para><para>This can
+ also be set per connection using the <link
+ linkend="JMS-Client-0-8-Connection-URL">Connection URL</link>
+ options.</para></entry>
+ </row>
+ <row>
+ <entry>qpid.sasl_server_name</entry>
+ <entry>string</entry>
+ <entry>localhost</entry>
+ <entry><para>When using GSSAPI as the SASL mechanism,
+ <varname>sasl_server</varname> must be set to the host for the SASL
+ server, e.g. <varname>example.com</varname>.</para><para>This can also
+ be set per connection using the <link
+ linkend="JMS-Client-0-8-Connection-URL">Connection URL</link>
+ options.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1">
+ <title>Config Options For Security - Standard JVM properties needed when using GSSAPI as the
+ SASL mechanism.<footnote>
+ <para>Please refer to the Java security documentation for a complete understanding
+ of the above properties.</para>
+ </footnote></title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>javax.security.auth.useSubjectCredsOnly</entry>
+ <entry>boolean</entry>
+ <entry>true</entry>
+ <entry><para>If set to 'false', forces the SASL GASSPI client to obtain the
+ kerberos credentials explicitly instead of obtaining from the "subject"
+ that owns the current thread.</para></entry>
+ </row>
+
+ <row>
+ <entry>java.security.auth.login.config</entry>
+ <entry>string</entry>
+ <entry/>
+ <entry><para>Specifies the jass configuration
+ file.</para><para><varname>Ex-Djava.security.auth.login.config=myjas.conf</varname>
+ </para><para>Here is the sample myjas.conf JASS configuration file: <programlisting><![CDATA[
+
+ com.sun.security.jgss.initiate {
+ com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
+ };
+
+ ]]></programlisting></para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ -->
+ <table pgwide="1">
+ <title>Config Options For Security - Using SSL for securing connections or using EXTERNAL as
+ the SASL mechanism.</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>qpid.ssl_timeout</entry>
+ <entry>long</entry>
+ <entry>60000</entry>
+ <entry><para>Timeout value used by the Java SSL engine when waiting on
+ operations.</para></entry>
+ </row>
+
+ <row>
+ <entry>qpid.ssl.KeyManagerFactory.algorithm</entry>
+ <entry>string</entry>
+ <entry>-</entry>
+ <entry>
+ <para>The key manager factory algorithm name. If not set, defaults to the
+ value returned from the Java runtime call
+ <literal>KeyManagerFactory.getDefaultAlgorithm()</literal></para>
+ <para>For compatibility with older clients, the synonym
+ <varname>qpid.ssl.keyStoreCertType</varname> is supported.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>qpid.ssl.TrustManagerFactory.algorithm</entry>
+ <entry>string</entry>
+ <entry>-</entry>
+ <entry>
+ <para>The trust manager factory algorithm name. If not set, defaults to the
+ value returned from the Java runtime call
+ <literal>TrustManagerFactory.getDefaultAlgorithm()</literal></para>
+ <para>For compatibility with older clients, the synonym
+ <varname>qpid.ssl.trustStoreCertType</varname> is supported.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1">
+ <title>Config Options For Security - Standard JVM properties needed when Using SSL for
+ securing connections or using EXTERNAL as the SASL mechanism.<footnote>
+ <para>Qpid allows you to have per connection key and trust stores if required. If
+ specified per connection, the JVM arguments are ignored.</para>
+ </footnote></title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Type</entry>
+ <entry>Default Value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>javax.net.ssl.keyStore</entry>
+ <entry>string</entry>
+ <entry>jvm default</entry>
+ <entry><para>Specifies the key store path.</para><para>This can also be set per
+ connection using the <link linkend="JMS-Client-0-8-Connection-URL"
+ >Connection URL</link> options.</para></entry>
+ </row>
+
+ <row>
+ <entry>javax.net.ssl.keyStorePassword</entry>
+ <entry>string</entry>
+ <entry>jvm default</entry>
+ <entry><para>Specifies the key store password.</para><para>This can also be set
+ per connection using the <link linkend="JMS-Client-0-8-Connection-URL"
+ >Connection URL</link> options.</para></entry>
+ </row>
+
+ <row>
+ <entry>javax.net.ssl.trustStore</entry>
+ <entry>string</entry>
+ <entry>jvm default</entry>
+ <entry><para>Specifies the trust store path.</para><para>This can also be set
+ per connection using the <link linkend="JMS-Client-0-8-Connection-URL"
+ >Connection URL</link> options.</para></entry>
+ </row>
+
+ <row>
+ <entry>javax.net.ssl.trustStorePassword</entry>
+ <entry>string</entry>
+ <entry>jvm default</entry>
+ <entry><para>Specifies the trust store password.</para><para>This can also be
+ set per connection using the <link
+ linkend="JMS-Client-0-8-Connection-URL">Connection URL</link>
+ options.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
new file mode 100644
index 0000000..6eae389
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
@@ -0,0 +1,526 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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.
+
+-->
+
+<chapter id="JMS-Client-0-8-Client-Understanding">
+ <title>Understanding the Qpid JMS client</title>
+ <section id="JMS-Client-0-8-Client-Understanding-Overview">
+ <title>Overview</title>
+ <para>The Qpid JMS client provides a JMS 1.1 compliant implementation. As such, the primary
+ source of documentation is the <ulink url="&oracleJmsSpec;">JMS specification</ulink> and the
+ <ulink url="&oracleJeeDocUrl;/javax/jms/package-summary.html">JMS javadocs</ulink>. This
+ documentation assumes the reader has familiarity with these resources.</para>
+ <para>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. </para>
+ <para>There areas where the Qpid JMS client provides features beyond those required for JMS
+ compliance. These are described in the sections that follow.</para>
+ <para>These sections are also used to bring out differences that may surprise those moving from
+ JMS implementations provided by other vendors.</para>
+ <figure>
+ <title>Architecture of a typical JMS application</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/QpidJmsOverview.png" format="PNG" scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-ConnectionFactory">
+ <title>ConnectionFactory</title>
+ <para>A <ulink url="&oracleJeeDocUrl;javax/jms/ConnectionFactory.html">ConnectionFactory</ulink>
+ allows an application to create a <ulink url="&oracleJeeDocUrl;javax/jms/Connection.html"
+ >Connection</ulink>.</para>
+ <para>The application obtains the ConnectionFactory from an <ulink
+ url="&oracleJdkDocUrl;javax/naming/InitialContext.html">InitialContext</ulink>. The
+ InitialContext is itself obtained from an InitialContextFactory. </para>
+ <para>The Qpid JMS client provides a single implementation of the InitialContextFactory in class
+ <literal>org.apache.qpid.jndi.PropertiesFileInitialContextFactory</literal>. This
+ implementation is backed by a <ulink url="&oracleJdkDocUrl;java/util/Properties.html"
+ >Properties</ulink> object which can of course be loaded from an external properties file,
+ or created programatically.</para>
+ <para>The examples in the previous chapter illustrated the Java code required to <link
+ linkend="JMS-Client-0-8-Examples-PTP">create the InitialContext</link> and an <link
+ linkend="JMS-Client-0-8-Examples-PTP-PropertiesFile">example properties file</link>.</para>
+ <para>Note that the Qpid Broker does not present a JNDI interface to the application.</para>
+ <figure>
+ <title>JNDI overview</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/JndiOverview.png" format="PNG" scalefit="1"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-Connection">
+ <title>Connection</title>
+ <para>A Connection represents an open communication channel between application and
+ Broker.</para>
+ <para>Connections are created from the ConnectionFactory <footnote>
+ <para>Constructors of the AMQConnection class must not be used.</para>
+ </footnote>.</para>
+ <para>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. </para>
+ <para>The underlying TCP/IP connection remains open for the lifetime of the JMS connection. It
+ is closed when the application calls <ulink
+ url="&oracleJeeDocUrl;javax/jms/Connection.html#close()">Connection#close()</ulink>, 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 coditions 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.</para>
+ <para>Qpid connections have failover and heartbeating capabilities. They support SSL and
+ client-auth. These are described in the sub-sections that follow.</para>
+ <section id="JMS-Client-0-8-Client-Understanding-Connection-Failover">
+ <title>Failover</title>
+ <para>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.</para>
+ <para>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.</para>
+ <para>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 <ulink
+ url="&oracleJeeDocUrl;javax/jms/TransactionRolledBackException.html"
+ >TransactionRolledBackException</ulink> from the <ulink
+ url="&oracleJeeDocUrl;javax/jms/Session.html#commit">Session#commit()</ulink> 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.</para>
+ <para>If, after all retries are exhausted, failover has failed to reconnect the application,
+ the Connection's <ulink url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html"
+ >ExceptionListener</ulink> will receive a JMSException with a linked exception of <ulink
+ url="JMS-Client-0-8-Appendix-Exceptions-AMQDisconnectedException"
+ >AMQDisconnectedException</ulink>. Any further use of the JMS objects (Connection, Session
+ etc), will results in a <ulink url="&oracleJeeDocUrl;javax/jms/IllegalStateException.html"
+ >IllegalStateException</ulink>.</para>
+ <para>Configure failover using the Connection URL. Here's an example Connection URL utilising
+ failover between two brokers. Note the use of the broker options <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-Retries"
+ ><literal>retries</literal></link> and <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-ConnectDelay"
+ ><literal>connectdelay</literal></link> to control the number of connection attempts to
+ each individual broker, and the delay between each connection attempt. Also note the use of
+ the <emphasis>failover option</emphasis>
+ <literal>cyclecount</literal> to control the number of times the failover mechanism will
+ traverse the brokerlist.</para>
+ <example>
+ <title>Connection URL configured for failover</title>
+ <screen><![CDATA[
+amqp://username:password@clientid/test
+ ?brokerlist='tcp://localhost:15672?retries='10'&connectdelay='1000';tcp://localhost:25672?retries='10'&connectdelay='1000''
+ &failover='roundrobin?cyclecount='20'']]>
+ </screen>
+ </example>
+ <para>For full details see <xref linkend="JMS-Client-0-8-Connection-URL"/></para>
+ <note><para>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 <emphasis>nofailover</emphasis> as in the example below
+ <example>
+ <title>Connection URL configured with nofailover</title>
+ <screen><![CDATA[
+amqp://username:password@clientid/test
+ ?brokerlist='tcp://localhost:15672?failover='nofailover']]>
+ </screen>
+ </example>
+ </para></note>
+ <!-- TODO perhaps mention ConnectionListener?-->
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-Connection-Heartbeating">
+ <title>Heartbeating</title>
+ <para>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.</para>
+ <para>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.</para>
+ <para>It is also allows the both the JMS client and the Broker to confirm that the other is
+ <emphasis>minimally</emphasis> 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.</para>
+ <para>If the client ever fails to receive two consecutive heartbeats, the Connection will be
+ automatically closed and the Connection's <ulink
+ url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html">ExceptionListener</ulink> will
+ receive a JMSException with a linked exception of AMQDisconnectedException. Any further use
+ of the JMS objects (Connection, Session etc), will results in a <ulink
+ url="&oracleJeeDocUrl;javax/jms/IllegalStateException.html"
+ >IllegalStateException</ulink>.</para>
+ <para>To enable heartbeating either use a Connection URL including the broker option <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-Heartbeat"
+ ><literal>heartbeat</literal></link>, or use the system property <link
+ linkend="JMS-Client-0-8-System-Properties-Heartbeat"
+ ><literal>qpid.heartbeat</literal></link>. </para>
+ <example>
+ <title>Connection URL configured for heartbeating</title>
+ <screen><![CDATA[
+amqp://guest:guest@clientid/?brokerlist='localhost:5672?heartbeat='5'']]>
+ </screen>
+ </example>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-Connection-SSL">
+ <title>SSL</title>
+ <para>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.</para>
+ <para>Some example Connection URLs using SSL follow:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Simple SSL when the Broker is secured by a certificate that is signed by a CA which
+ is trusted by the JVM.</para>
+ <example>
+ <title>Connection URL configured for SSL - CA trusted by JVM</title>
+ <screen><![CDATA[
+amqp://guest:guest@clientid/?brokerlist='localhost:5671'&ssl='true']]>
+ </screen>
+ </example>
+ </listitem>
+ <listitem>
+ <para>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 <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-TrustStore"
+ ><literal>trust_store</literal></link> and <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-TrustStorePassword"
+ ><literal>trust_store_password</literal></link> to specify a path a truststore file
+ (containing the certificate of the private-CA) and the truststore password.</para>
+ <example>
+ <title>Connection URL configured for SSL - CA not trusted by JVM</title>
+ <screen><![CDATA[
+amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/acme_org_ca.ts'&trust_store_password='secret''&ssl='true']]>
+ </screen>
+ </example>
+ </listitem>
+ <listitem>
+ <para>SSL with SSL client-auth. For this case, we use <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-KeyStore"
+ ><literal>key_store</literal></link> and <link
+ linkend="JMS-Client-0-8-Connection-URL-BrokerOptions-KeyStorePassword"
+ ><literal>key_store_password</literal></link> to specify a path a keystore file
+ (containing the certificate of the client) and the keystore password.</para>
+ <example>
+ <title>Connection URL configured for SSL - SSL client-auth</title>
+ <screen><![CDATA[
+amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/app1_client_cert.ks'&key_store_password='secret''&ssl='true']]>
+ </screen>
+ </example>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-Session">
+ <title>Session</title>
+ <para>A Session object is a single-threaded context for producing and consuming messages.</para>
+ <para>Session objects are created from the Connection. Whilst Session objects are relatively
+ lightweight, patterns utilising a single Session per message are not recommended.</para>
+ <para>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.</para>
+ <para>Qpid JMS Sessions have the ability to prefetch messages to improve consumer performance.
+ This feature is described next.</para>
+ <section id="JMS-Client-0-8-Client-Understanding-Session-Prefecth">
+ <title>Prefetch</title>
+ <para>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 <emphasis>Session</emphasis>.</para>
+ <para>The size of the prefetch buffer can be tuned per Connection using the connection url
+ option <link linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Maxprefetch"
+ ><literal>maxprefetch</literal></link> (or JVM wide using the system property <link
+ linkend="JMS-Client-0-8-System-Properties-Maxprefetch"
+ ><literal>max_prefetch</literal></link>). By default, prefetch defaults to 500.</para>
+ <para>There are situations when you may wish to consider reducing the size of prefetch:</para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>When using a <ulink url="http://www.eaipatterns.com/CompetingConsumers.html"
+ >Competing Consumers</ulink> 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.</para>
+ </listitem>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para>When message size is large and you do not wish the memory footprint of the
+ application to grow (or suffer an OutOfMemoryError).</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>Finally, if using multiple MessageConsumers on a single Session, keep in mind that
+ unless you keep polling <emphasis>all</emphasis> 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 <ulink
+ url="&oracleJeeDocUrl;javax/jms/MessageConsumer.html#receive()"
+ >MessageConsumer#receive()</ulink> 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. </para>
+ <note><para>Please note, when the acknowlegement mode <emphasis>Session#SESSION_TRANSACTED</emphasis>
+ or <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis> is set on a consuming session,
+ the prefetched messages are released from the prefetch buffer on transaction commit/rollback
+ (in case of acknowledgement mode <emphasis>Session#SESSION_TRANSACTED</emphasis> )
+ or acknowledgement of the messages receipt (in case of acknowledgement mode
+ <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis> ). 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 <emphasis>Session#SESSION_TRANSACTED</emphasis> )
+ or received messages are acknowledged (for <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis>).</para></note>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-Session-TemporaryQueues">
+ <title>TemporaryQueues</title>
+ <para>Qpid implements JMS temporary queues as AMQP auto-delete queues. The life cycle of these
+ queues deviates from the JMS specification.</para>
+ <para>AMQP auto-delete queues are deleted either when the <emphasis>last</emphasis> 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.</para>
+ <para>This deviation has no practical impact on the implementation of the <ulink
+ url="http://www.eaipatterns.com/RequestReply.html">request/reply messaging pattern</ulink>
+ utilising a per-request temporary reply queue. The reply to queue is deleted as the
+ application closes the Consumer awaiting the response. </para>
+ <para>Temporary queues are exposed to Management in the same way as normal queues. Temporary
+ queue names take the form string <literal>TempQueue</literal> followed by a random
+ UUID.</para>
+ <para>Note that <ulink url="&oracleJeeDocUrl;javax/jms/TemporaryQueue.html#delete()"
+ >TemporaryQueue#delete()</ulink> 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.</para>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-Session-CreateQueue">
+ <title>CreateQueue</title>
+ <para>In the Qpid JMS client, <ulink
+ url="&oracleJeeDocUrl;javax/jms/Session.html#createQueue(java.lang.String)"
+ >Session#createQueue()</ulink> 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’. </para>
+ <para>Calling Session#createQueue() has no effect on the Broker.</para>
+ <para>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.</para>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-Session-CreateTopic">
+ <title>CreateTopic</title>
+ <para>In the Qpid JMS client, <ulink
+ url="&oracleJeeDocUrl;javax/jms/Session.html#createTopic(java.lang.String)"
+ >Session#createTopic()</ulink> 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>’.</para>
+ <para>Calling Session#createTopic() has no effect on the Broker.</para>
+ <para>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.</para>
+ </section>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageProducer">
+ <title>MessageProducer</title>
+ <para>A MessageProducer sends a message an <emphasis>Exchange</emphasis>. 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 <emphasis>bindings</emphasis> between the exchange and queues
+ and a <emphasis>routing key</emphasis> included with each message.</para>
+ <para>To understand how this mechanism is used to deliver messages to queues and topics, see
+ <ulink url="&qpidJavaBrokerBook;Java-Broker-Concepts-Exchanges.html">Exchanges</ulink>
+ within the Java Broker book.</para>
+ <para>It is important to understand that when not used on a transactional session, <ulink
+ url="&oracleJeeDocUrl;javax/jms/MessageProducer.html#send(javax.jms.Message)"
+ >MessageProducer#send()</ulink> is <emphasis>asynchronous</emphasis> 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
+ <ulink url="&oracleJeeDocUrl;javax/jms/Session.html#SESSION_TRANSACTED">transactional
+ session</ulink>
+ <emphasis>must</emphasis> be used.</para>
+ <para>Qpid JMS MessageProducers have a number of features above that required by JMS. These are
+ described in the sub-sections that follow.</para>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageProducer-MandatoryMessage">
+ <title>Mandatory Messages</title>
+ <para>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.</para>
+ <para>The Message is returned to the application in an asynchronous fashion via the
+ Connection's <ulink url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html"
+ >ExceptionListener</ulink>. When a message is returned, it will be invoked with a
+ JMSException whose linked exception is an <ulink
+ url="JMS-Client-0-8-Appendix-Exceptions-AMQNoRouteException">AMQNoRouteException</ulink>.
+ The returned message is available to the application by calling
+ AMQNoRouteException#getUndeliveredMessage(). The ExceptionListener will be invoked exactly
+ once for each returned message.</para>
+ <para>The mandatory message feature is turned <emphasis>on</emphasis> by default for Queue
+ destinations and <emphasis>off</emphasis> for Topic destinations. This can be overridden
+ using system properties <link linkend="JMS-Client-0-8-System-Properties-DefaultMandatory"
+ ><literal>qpid.default_mandatory</literal></link> and <link
+ linkend="JMS-Client-0-8-System-Properties-DefaultMandatoryTopic"
+ ><literal>qpid.default_mandatory_topic</literal></link> for Queues and Topics
+ respectively.</para>
+ <note><para>Please note, according to AMQP specifications the mandatory flag on a message tells the server
+ how to react if the message cannot be routed to a queue. If this flag is set, the server will return an unroutable message with a
+ Return method. If this flag is zero, the server silently drops the message. Please, refer <ulink url="&amqpSrc;">AMQP specifications</ulink>
+ for more details.</para></note>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageProducer-CloseWhenNoRoute">
+ <title>Close When No Route</title>
+ <para>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.</para>
+ <para>To enable or disable from the client, use the Connection URL option <link
+ linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-CloseWhenNoRoute"
+ ><literal>closeWhenNoRoute</literal></link>.</para>
+ <para>See <ulink url="&qpidJavaBrokerBook;Java-Broker-Close-Connection-When-No-Route.html">
+ Closing client connections on unroutable mandatory messages</ulink> within the Java Broker
+ book for full details of the functioning of this feature.</para>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageProducer-ImmediateMessage">
+ <title>Immediate Messages</title>
+ <para>This feature is defined in <ulink url="&amqpSrc;">AMQP specifications</ulink>.</para>
+ <para>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 <ulink
+ url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html">ExceptionListener</ulink>.</para>
+ <para>The ExceptionListener will be invoked with a JMSException whose linked exception is an
+ <ulink url="JMS-Client-0-8-Appendix-Exceptions-AMQNoConsumersException"
+ >AMQNoConsumersException</ulink>. The returned message is available to the application by
+ calling AMQNoConsumersException#getUndeliveredMessage(). The ExceptionListener will be
+ invoked exactly once for each returned message.</para>
+ <para>The immediate message feature is turned <emphasis>off</emphasis> by default. It can be
+ enabled with system property <link
+ linkend="JMS-Client-0-8-System-Properties-DefaultImmediate"
+ ><literal>qpid.default_immediate</literal></link>.</para>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageProducer-FlowControl">
+ <title>Flow Control</title>
+ <para>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.</para>
+ <para>To control the timeout use System property <link
+ linkend="JMS-Client-0-8-System-Properties-FlowControlWaitFailure"
+ ><literal>qpid.flow_control_wait_failure</literal></link>. To control the frequency with
+ which warnings are logged whilst a Session is blocked, use System property <link
+ linkend="JMS-Client-0-8-System-Properties-FlowControlWaitNotifyPeriod"
+ ><literal>qpid.flow_control_wait_notify_period</literal></link></para>
+ <para>See <ulink
+ url="&qpidJavaBrokerBook;Java-Broker-Runtime-Disk-Space-Management.html#Qpid-Producer-Flow-Control"
+ > Producer Flow Control</ulink> within the Java Broker book for full details of the
+ functioning of this feature.</para>
+ </section>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageConsumer">
+ <title>MessageConsumer</title>
+ <para>A MessageConsumer receives messages from a Queue or Topic.</para>
+ <para>MessageConsumer objects are created from the Session.</para>
+ <para>Qpid JMS MessageConsumers have a number of features above that required by JMS. These are
+ described in the sub-sections that follow.</para>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageConsumer-ConsumerSideEffect">
+ <title>Consumers have Exchange/Queue Declaration and Binding Side Effect</title>
+ <para>By default, calling <ulink
+ url="&oracleJeeDocUrl;javax/jms/Session.html#createConsumer(javax.jms.Destination)"
+ >Session#createConsumer()</ulink> will cause:</para>
+ <orderedlist>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </orderedlist>
+ <para>The exchange and queue declare side effect can be suppressed using system properties
+ <link linkend="JMS-Client-0-8-System-Properties-DeclareExchanges"
+ ><literal>qpid.declare_exchanges</literal></link> and <link
+ linkend="JMS-Client-0-8-System-Properties-DeclareQueues"
+ ><literal>qpid.declare_queues</literal></link>.</para>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageConsumer-TopicSubscriptions">
+ <title>Topic Subscriptions</title>
+ <para>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.</para>
+ <para>Durable topic subscriptions use a <emphasis>durable</emphasis> and
+ <emphasis>exclusive</emphasis> queue named as follows:</para>
+ <programlisting>
+ clientid: + subscriptionId
+ </programlisting>
+ <para>where <literal>subscriptionId</literal> is that passed to the <ulink
+ url="&oracleJeeDocUrl;javax/jms/Session.html#createDurableSubscriber(javax.jms.Topic,%20java.lang.String)"
+ >Session#createDurableSubscriber(javax.jms.Topic,java.lang.String)</ulink></para>
+ <para>Calling <ulink
+ url="&oracleJeeDocUrl;javax/jms/Session.html#unsubscribe(java.lang.String)"
+ >Session#unsubscribe(java.lang.String)</ulink> deletes the underlying queue.</para>
+ <para>Non-durable topic subscriptions use a <emphasis>non-durable</emphasis>,
+ <emphasis>exclusive</emphasis> and <emphasis>auto-delete</emphasis> queue named as
+ follows:</para>
+ <programlisting>
+ tmp + _ + ip + _ + port + _ + sequence
+ </programlisting>
+ <para>where <literal>ip</literal> is the ip address of the client with dots replaced by
+ underscores, <literal>port</literal> is the ephemeral port number assigned to the client's
+ connection, and <literal>sequence</literal> is a sequence number.</para>
+ <para>Closing the consumer (or closing the connection) will delete the underlying
+ queue.</para>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-MessageConsumer-MaximumDeliveryCount">
+ <title>Maximum Delivery Count</title>
+ <para>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.</para>
+ <para>When using this feature, the application must either set system property <link
+ linkend="JMS-Client-0-8-System-Properties-RejectBehaviour">qpid.reject.behaviour</link> or
+ the Binding URL option <link linkend="JMS-Client-0-8-Binding-URL-Options-RejectBehaviour"
+ ><literal>rejectbehaviour</literal></link> to the value
+ <literal>server</literal>.</para>
+ <para>See <ulink
+ url="&qpidJavaBrokerBook;Java-Broker-Runtime-Handling-Undeliverable-Messages.html#Java-Broker-Runtime-Handling-Undeliverable-Messages-Maximum-Delivery-Count"
+ > Handling Undeliverable Messages</ulink> within the Java Broker book for full details of
+ the functioning of this feature.</para>
+ <note><para>The optional JMS message header <literal>JMSXDeliveryCount</literal> is <emphasis>not</emphasis>
+ supported.</para></note>
+ </section>
+ </section>
+ <section id="JMS-Client-0-8-Client-Understanding-Destinations">
+ <title>Destinations</title>
+ <para>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 <xref
+ linkend="JMS-Client-0-8-Binding-URL"/>. </para>
+ <para>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
+ <literal>queue.</literal> and <literal>topic.</literal> prefix to create Queues and Topics
+ objects respectively. </para>
+ </section>
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/Makefile b/qpid/doc/book/src/jms-client-0-8/Makefile
new file mode 100644
index 0000000..ccb9d29
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/Makefile
@@ -0,0 +1,20 @@
+#
+# 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.
+#
+
+include ../Makefile.inc
diff --git a/qpid/doc/book/src/jms-client-0-8/commonEntities.xml b/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
new file mode 100644
index 0000000..64158f0
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
@@ -0,0 +1,47 @@
+<!--
+
+ 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.
+
+-->
+
+<!ENTITY qpidVersion "0.26">
+<!ENTITY qpidDownloadUrlDesc "the Apache Qpid project web site">
+<!ENTITY qpidDownloadUrl "http://qpid.apache.org/download.html">
+
+<!ENTITY qpidMavenRepoDesc "Maven repositories">
+<!ENTITY qpidClientGroupId "org.apache.qpid">
+<!ENTITY qpidClientArtefactId "qpid-client">
+
+
+<!ENTITY qpidProgrammingBook "../../Programming-In-Apache-Qpid/html/">
+<!ENTITY qpidJavaBrokerBook "../../AMQP-Messaging-Broker-Java-Book/html/">
+<!ENTITY qpidSrc "http://svn.apache.org/viewvc/qpid/trunk/qpid/java/">
+
+<!ENTITY amqpSrc "http://www.amqp.org">
+
+<!-- Oracle javadoc -->
+
+<!ENTITY oracleJmsSpec "http://download.oracle.com/otndocs/jcp/7195-jms-1.1-fr-spec-oth-JSpec/">
+<!ENTITY oracleJdkDocUrl "http://docs.oracle.com/javase/6/docs/api/">
+<!ENTITY oracleJeeDocUrl "http://docs.oracle.com/javaee/6/api/">
+<!ENTITY oracleJmsTutorial "http://docs.oracle.com/javaee/6/tutorial/doc/bncdq.html">
+
+
+
+
+
diff --git a/qpid/doc/book/src/jms-client-0-8/images/JndiOverview.png b/qpid/doc/book/src/jms-client-0-8/images/JndiOverview.png
new file mode 100644
index 0000000..82f6efd
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/images/JndiOverview.png
Binary files differ
diff --git a/qpid/doc/book/src/jms-client-0-8/images/JndiOverview.svg b/qpid/doc/book/src/jms-client-0-8/images/JndiOverview.svg
new file mode 100644
index 0000000..a8d1f05
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/images/JndiOverview.svg
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!--
+
+ 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.
+
+-->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="61 27 572 361" width="572pt" height="361pt" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata> Produced by OmniGraffle 6.0.3 <dc:date>2013-12-29 17:48Z</dc:date></metadata><defs><filter id="Shadow" filterUnits="userSpaceOnUse"><feGaussianBlur in="SourceAlpha" result="blur" stdDeviation="1.308"/><feOffset in="blur" result="offset" dx="0" dy="2"/><feFlood flood-color="black" flood-opacity=".5" result="flood"/><feComposite in="flood" in2="offset" operator="in"/></filter><linearGradient x1="0" x2="1" id="Gradient" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#6383ab"/><stop offset="1" stop-color="white"/></linearGradient><linearGradient id="Obj_Gradient" xl:href="#Gradient" gradientTransform="translate(137 97) rotate(90) scale(78)"/><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><linearGradient x1="0" x2="1" id="Gradient_2" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#62a073"/><stop offset="1" stop-color="white"/></linearGradient><linearGradient id="Obj_Gradient_2" xl:href="#Gradient_2" gradientTransform="translate(552 71) rotate(90) scale(250)"/><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><linearGradient x1="0" x2="1" id="Gradient_3" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#baa6ff"/><stop offset="1" stop-color="#624aba"/></linearGradient><linearGradient id="Obj_Gradient_3" xl:href="#Gradient_3" gradientTransform="translate(344.1991 155.44433) rotate(101.76829) scale(21.564619)"/><linearGradient x1="0" x2="1" id="Gradient_4" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#ff6"/><stop offset="1" stop-color="#fc6"/></linearGradient><linearGradient id="Obj_Gradient_4" xl:href="#Gradient_4" gradientTransform="translate(149.57673 206.53541) rotate(180) scale(25.153465)"/><font-face font-family="Monaco" font-size="8" units-per-em="1000" underline-position="-37.597656" underline-thickness="75.683594" slope="0" x-height="560.54688" cap-height="780.27344" ascent="1e3" descent="-250" font-weight="500"><font-face-src><font-face-name name="Monaco"/></font-face-src></font-face><font-face font-family="Monaco" font-size="7" units-per-em="1000" underline-position="-37.597656" underline-thickness="75.683594" slope="0" x-height="560.54688" cap-height="780.27344" ascent="1e3" descent="-250" font-weight="500"><font-face-src><font-face-name name="Monaco"/></font-face-src></font-face><linearGradient id="Obj_Gradient_5" xl:href="#Gradient_4" gradientTransform="translate(209.73909 266.2009) rotate(99.75359) scale(20.210732)"/><font-face font-family="Helvetica Neue" font-size="12" panose-1="2 0 5 3 0 0 0 9 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="-1e3" x-height="517" cap-height="714" ascent="957.00194" descent="-213.00043" font-style="italic" font-weight="500"><font-face-src><font-face-name name="HelveticaNeue-Italic"/></font-face-src></font-face><font-face font-family="Helvetica Neue" font-size="12" panose-1="2 0 8 3 0 0 0 9 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="975.002" descent="-217.00044" font-weight="bold"><font-face-src><font-face-name name="HelveticaNeue-Bold"/></font-face-src></font-face><font-face font-family="Helvetica Neue" font-size="11" panose-1="2 0 5 3 0 0 0 2 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="952.00193" descent="-213.00043" font-weight="500"><font-face-src><font-face-name name="HelveticaNeue"/></font-face-src></font-face><linearGradient id="Obj_Gradient_6" xl:href="#Gradient_4" gradientTransform="translate(220.71163 202) rotate(140.077054) scale(25.153465)"/></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>JNDI overview</title><rect fill="white" width="960" height="1172"/><g><title>Layer 1</title><g><xl:use xl:href="#id26_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id570_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id10_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id594_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id19_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id599_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id600_Graphic" filter="url(#Shadow)"/></g><line x1="443.50465" y1="38.532298" x2="437.70354" y2="370.8774" fill="white"/><line x1="443.50465" y1="38.532298" x2="437.70354" y2="370.8774" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1" stroke-dasharray="1,4"/><g id="id26_Graphic"><path d="M 76 175 L 76 104.8 L 88.2 97 L 198 97 L 198 167.2 L 185.8 175 Z" fill="url(#Obj_Gradient)"/><path d="M 76 175 L 76 104.8 L 88.2 97 L 198 97 L 198 167.2 L 185.8 175 L 76 175 M 76 104.8 L 185.8 104.8 L 198 97 M 185.8 104.8 L 185.8 175" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(81 104.8)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="17.233984" y="11" textLength="65.33203">Application</tspan></text></g><g id="id570_Graphic"><path d="M 486 321 L 486 96 L 499.2 71 L 618 71 L 618 296 L 604.8 321 Z" fill="url(#Obj_Gradient_2)"/><path d="M 486 321 L 486 96 L 499.2 71 L 618 71 L 618 296 L 604.8 321 L 486 321 M 486 96 L 604.8 96 L 618 71 M 604.8 96 L 604.8 321" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(491 96)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="35.058203" y="11" textLength="38.683594">Broker</tspan></text></g><path d="M 107.4296 270.77631 C 94.5 267.5 99.656 239.91885 120.2816 244.625 C 122.1952 235.45121 146.18 236.94022 146.0232 244.625 C 161.0624 234.79607 180.2816 254.39476 167.3904 264.22369 C 182.8592 268.98901 167.1952 294.66391 154.5 290.375 C 153.484 297.52359 130.7888 300.0252 128.7968 290.375 C 115.9456 300.68095 89.1488 284.83498 107.4296 270.77631 Z" fill="white"/><path d="M 107.4296 270.77631 C 94.5 267.5 99.656 239.91885 120.2816 244.625 C 122.1952 235.45121 146.18 236.94022 146.0232 244.625 C 161.0624 234.79607 180.2816 254.39476 167.3904 264.22369 C 182.8592 268.98901 167.1952 294.66391 154.5 290.375 C 153.484 297.52359 130.7888 300.0252 128.7968 290.375 C 115.9456 300.68095 89.1488 284.83498 107.4296 270.77631 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(114 260.5)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="9.666992" y="11" textLength="26.666016">JNDI</tspan></text><path d="M 198 136 L 224.69935 130.54855 L 223.59255 135.86122 L 462.59204 185.65278 L 463.69884 180.34011 L 486 196 L 459.30065 201.45145 L 460.40745 196.13878 L 221.40796 146.34722 L 220.30116 151.65989 Z" fill="url(#Obj_Gradient_3)"/><path d="M 198 136 L 224.69935 130.54855 L 223.59255 135.86122 L 462.59204 185.65278 L 463.69884 180.34011 L 486 196 L 459.30065 201.45145 L 460.40745 196.13878 L 221.40796 146.34722 L 220.30116 151.65989 Z" stroke="#513d99" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><path d="M 130.71163 175 L 143.28837 175 L 143.28837 218.07082 L 149.57673 218.07082 L 137 238.07083 L 124.42327 218.07082 L 130.71163 218.07082 Z" fill="url(#Obj_Gradient_4)"/><path d="M 130.71163 175 L 143.28837 175 L 143.28837 218.07082 L 149.57673 218.07082 L 137 238.07083 L 124.42327 218.07082 L 130.71163 218.07082 Z" stroke="#e97b00" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(144 187.88385) rotate(90)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="0" y="11" textLength="35.361328">lookup</tspan></text><path d="M 413 266.0802 C 413 258.69126 410.8283 257.7771 394.96463 250.4646 L 394.79705 250.38894 C 378.8496 243 378.68372 243 362.3173 243 C 340.52507 243 242 243 242 243 L 242 321 L 413 321 L 413 266.0802 Z" fill="white"/><path d="M 413 266.0802 C 413 258.69126 410.8283 257.7771 394.96463 250.4646 L 394.79705 250.38894 C 378.8496 243 378.68372 243 362.3173 243 C 340.52507 243 242 243 242 243 L 242 321 L 413 321 L 413 266.0802 Z M 413 265.69956 C 413 258.69126 412.83242 258.69126 378.68372 258.69126 L 378.68372 258.69126 C 378.68372 243.07644 378.68372 243 363.31937 243" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(247 260)" fill="black"><tspan font-family="Monaco" font-size="8" font-weight="500" x="0" y="8" textLength="139.22266">java.naming.factory.initial=…</tspan><tspan font-family="Monaco" font-size="7" font-weight="500" x="0" y="19" textLength="100.816406">connectionfactory.qpidCF</tspan><tspan font-family="Monaco" font-size="8" font-weight="500" x="100.816406" y="19" textLength="9.6015625">=…</tspan><tspan font-family="Monaco" font-size="8" font-weight="500" x="0" y="30" textLength="100.816406">queue.mytrades=trades</tspan><tspan font-family="Monaco" font-size="8" font-weight="500" x="0" y="41" textLength="148.82422">queue.myinstruments=instruments</tspan></text><path d="M 173.19828 275.30005 L 174.91024 265.34075 L 223.14507 273.63212 L 224.00105 268.65248 L 242 282 L 220.57713 288.57107 L 221.43311 283.59142 Z" fill="url(#Obj_Gradient_5)"/><path d="M 173.19828 275.30005 L 174.91024 265.34075 L 223.14507 273.63212 L 224.00105 268.65248 L 242 282 L 220.57713 288.57107 L 221.43311 283.59142 Z" stroke="#e97b00" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(189.84696 258.82977) rotate(9.75359)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" fill="black" x="1.16878206" y="11" textLength="19.347656">defi</tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" fill="black" x="20.516438" y="11" textLength="23.355469">ned </tspan><tspan font-family="Helvetica" font-size="12" font-weight="500" fill="black" x="14.516438" y="25" textLength="12.673828">by</tspan></text><g id="id10_Graphic"><path d="M 551.4536 133.07864 L 587.49484 133.70774 C 589.9817 133.75115 591.785 146.1045 591.52006 161.28219 C 591.25513 176.45988 589.0218 188.74277 586.53496 188.69936 L 550.49372 188.07026 C 548.00687 188.02685 546.20358 175.6735 546.4685 160.49581 C 546.73343 145.31812 548.96675 133.03523 551.4536 133.07864" fill="#218041"/><path d="M 551.4536 133.07864 L 587.49484 133.70774 C 589.9817 133.75115 591.785 146.1045 591.52006 161.28219 C 591.25513 176.45988 589.0218 188.74277 586.53496 188.69936 L 550.49372 188.07026 C 548.00687 188.02685 546.20358 175.6735 546.4685 160.49581 C 546.73343 145.31812 548.96675 133.03523 551.4536 133.07864 M 587.49484 133.70774 C 585.008 133.66433 582.77468 145.94723 582.50975 161.12491 C 582.24482 176.3026 584.0481 188.65596 586.53496 188.69936" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><text transform="translate(201.5625 332)" fill="#7e7e7e"><tspan font-family="Helvetica Neue" font-size="12" font-style="italic" font-weight="500" fill="#7e7e7e" x="18.36675" y="11" textLength="21.12">Defi</tspan><tspan font-family="Helvetica Neue" font-size="12" font-style="italic" font-weight="500" fill="#7e7e7e" x="39.48675" y="11" textLength="125.796">nes the JMS administer</tspan><tspan font-family="Helvetica Neue" font-size="12" font-style="italic" font-weight="500" fill="#7e7e7e" x="165.06675" y="11" textLength="59.34">ed objects </tspan><tspan font-family="Helvetica Neue" font-size="12" font-style="italic" font-weight="500" fill="#7e7e7e" x="19.71075" y="25" textLength="200.016">(connection factories, queues, topics)</tspan><tspan font-family="Helvetica Neue" font-size="12" font-style="italic" font-weight="500" fill="#7e7e7e" x="57.58875" y="39" textLength="124.26">used by the application</tspan></text><text transform="translate(247 223)" fill="black"><tspan font-family="Helvetica Neue" font-size="12" font-weight="bold" x=".064" y="12" textLength="36.216">jndi.pr</tspan><tspan font-family="Helvetica Neue" font-size="12" font-weight="bold" x="36.064" y="12" textLength="46.872">operties</tspan></text><text transform="translate(548 159.778)" fill="black"><tspan font-family="Helvetica Neue" font-size="11" font-weight="500" x=".0175" y="10" textLength="30.965">trades</tspan></text><g id="id594_Graphic"><path d="M 550.24356 203.85664 L 586.2848 204.48574 C 588.77165 204.52915 590.57495 216.8825 590.31002 232.06019 C 590.0451 247.23788 587.81177 259.52077 585.32492 259.47736 L 549.28368 258.84826 C 546.79683 258.80485 544.99354 246.4515 545.25846 231.27381 C 545.5234 216.09612 547.7567 203.81323 550.24356 203.85664" fill="#218041"/><path d="M 550.24356 203.85664 L 586.2848 204.48574 C 588.77165 204.52915 590.57495 216.8825 590.31002 232.06019 C 590.0451 247.23788 587.81177 259.52077 585.32492 259.47736 L 549.28368 258.84826 C 546.79683 258.80485 544.99354 246.4515 545.25846 231.27381 C 545.5234 216.09612 547.7567 203.81323 550.24356 203.85664 M 586.2848 204.48574 C 583.79796 204.44233 581.56464 216.72523 581.2997 231.90291 C 581.03478 247.0806 582.83808 259.43396 585.32492 259.47736" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><text transform="translate(540 224)" fill="black"><tspan font-family="Helvetica Neue" font-size="11" font-weight="500" x=".1635" y="10" textLength="57.673">instruments</tspan></text><path d="M 176.95547 179.10681 L 186.60067 171.0356 L 232.34226 225.69743 L 237.16486 221.66183 L 240.3548 245.0712 L 217.87446 237.80424 L 222.69706 233.76864 Z" fill="url(#Obj_Gradient_6)"/><path d="M 176.95547 179.10681 L 186.60067 171.0356 L 232.34226 225.69743 L 237.16486 221.66183 L 240.3548 245.0712 L 217.87446 237.80424 L 222.69706 233.76864 Z" stroke="#e97b00" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(197.6773 183.16345) rotate(50.077054)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" x="0" y="11" textLength="30.017578">reads</tspan></text><g id="id19_Graphic"><rect x="499" y="152" width="31" height="32" fill="#218041"/><rect x="499" y="152" width="31" height="32" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><g id="id599_Graphic"><rect x="499" y="195" width="31" height="32" fill="#218041"/><rect x="499" y="195" width="31" height="32" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><g id="id600_Graphic"><rect x="499" y="238" width="31" height="32" fill="#218041"/><rect x="499" y="238" width="31" height="32" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g></g></g></svg>
diff --git a/qpid/doc/book/src/jms-client-0-8/images/QpidJmsOverview.png b/qpid/doc/book/src/jms-client-0-8/images/QpidJmsOverview.png
new file mode 100644
index 0000000..1f90905
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/images/QpidJmsOverview.png
Binary files differ
diff --git a/qpid/doc/book/src/jms-client-0-8/images/QpidJmsOverview.svg b/qpid/doc/book/src/jms-client-0-8/images/QpidJmsOverview.svg
new file mode 100644
index 0000000..55a354a
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/images/QpidJmsOverview.svg
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!--
+
+ 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.
+
+-->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="197 97 577 280" width="577pt" height="280pt" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata> Produced by OmniGraffle 6.0.3 <dc:date>2013-12-29 17:48Z</dc:date></metadata><defs><filter id="Shadow" filterUnits="userSpaceOnUse"><feGaussianBlur in="SourceAlpha" result="blur" stdDeviation="1.308"/><feOffset in="blur" result="offset" dx="0" dy="2"/><feFlood flood-color="black" flood-opacity=".5" result="flood"/><feComposite in="flood" in2="offset" operator="in"/></filter><linearGradient x1="0" x2="1" id="Gradient" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#6383ab"/><stop offset="1" stop-color="white"/></linearGradient><linearGradient id="Obj_Gradient" xl:href="#Gradient" gradientTransform="translate(273 207) rotate(90) scale(78)"/><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><linearGradient x1="0" x2="1" id="Gradient_2" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#62a073"/><stop offset="1" stop-color="white"/></linearGradient><linearGradient id="Obj_Gradient_2" xl:href="#Gradient_2" gradientTransform="translate(471 110) rotate(90) scale(250)"/><linearGradient x1="0" x2="1" id="Gradient_3" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#baa6ff"/><stop offset="1" stop-color="#624aba"/></linearGradient><linearGradient id="Obj_Gradient_3" xl:href="#Gradient_3" gradientTransform="translate(374.5 235.21769) rotate(90) scale(21.564619)"/><font-face font-family="Helvetica" font-size="12" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><linearGradient id="Obj_Gradient_4" xl:href="#Gradient" gradientTransform="translate(697.6057 142) rotate(90) scale(78)"/><linearGradient id="Obj_Gradient_5" xl:href="#Gradient_3" gradientTransform="translate(572.72086 183.88282) rotate(77.709507) scale(21.564619)"/><linearGradient id="Obj_Gradient_6" xl:href="#Gradient" gradientTransform="translate(697.6057 251) rotate(90) scale(78)"/><linearGradient id="Obj_Gradient_7" xl:href="#Gradient_3" gradientTransform="translate(574.32974 275.36927) rotate(93.517516) scale(21.564619)"/></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Typical Architecture</title><rect fill="white" width="960" height="1172"/><g><title>Layer 1</title><g><xl:use xl:href="#id26_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id570_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id10_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id594_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id597_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id599_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id19_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id601_Graphic" filter="url(#Shadow)"/><xl:use xl:href="#id602_Graphic" filter="url(#Shadow)"/></g><g id="id26_Graphic"><path d="M 212 285 L 212 214.8 L 224.2 207 L 334 207 L 334 277.2 L 321.8 285 Z" fill="url(#Obj_Gradient)"/><path d="M 212 285 L 212 214.8 L 224.2 207 L 334 207 L 334 277.2 L 321.8 285 L 212 285 M 212 214.8 L 321.8 214.8 L 334 207 M 321.8 214.8 L 321.8 285" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(217 214.8)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="12.230078" y="11" textLength="75.339844">Application 1</tspan></text></g><g id="id570_Graphic"><path d="M 403 360 L 403 135 L 416.6 110 L 539 110 L 539 335 L 525.4 360 Z" fill="url(#Obj_Gradient_2)"/><path d="M 403 360 L 403 135 L 416.6 110 L 539 110 L 539 335 L 525.4 360 L 403 360 M 403 135 L 525.4 135 L 539 110 M 525.4 135 L 525.4 360" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(408 135)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="36.858203" y="11" textLength="38.683594">Broker</tspan></text></g><path d="M 334 251.39115 L 334 240.60885 L 393 240.60885 L 393 235.21769 L 415 246 L 393 256.78231 L 393 251.39115 Z" fill="url(#Obj_Gradient_3)"/><path d="M 334 251.39115 L 334 240.60885 L 393 240.60885 L 393 235.21769 L 415 246 L 393 256.78231 L 393 251.39115 Z" stroke="#513d99" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(349.125 239)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" fill="black" x="6.361328" y="11" textLength="38.027344">publish</tspan></text><g id="id10_Graphic"><path d="M 477.42644 182.83601 L 509.42644 182.83601 C 511.63444 182.83601 513.42644 194.03601 513.42644 207.83601 C 513.42644 221.63601 511.63444 232.83601 509.42644 232.83601 L 477.42644 232.83601 C 475.21844 232.83601 473.42644 221.63601 473.42644 207.83601 C 473.42644 194.03601 475.21844 182.83601 477.42644 182.83601" fill="#218041"/><path d="M 477.42644 182.83601 L 509.42644 182.83601 C 511.63444 182.83601 513.42644 194.03601 513.42644 207.83601 C 513.42644 221.63601 511.63444 232.83601 509.42644 232.83601 L 477.42644 232.83601 C 475.21844 232.83601 473.42644 221.63601 473.42644 207.83601 C 473.42644 194.03601 475.21844 182.83601 477.42644 182.83601 M 509.42644 182.83601 C 507.21844 182.83601 505.42644 194.03601 505.42644 207.83601 C 505.42644 221.63601 507.21844 232.83601 509.42644 232.83601" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><g id="id594_Graphic"><path d="M 474.7307 257.26253 L 506.7307 257.26253 C 508.9387 257.26253 510.7307 268.46253 510.7307 282.26253 C 510.7307 296.06253 508.9387 307.26253 506.7307 307.26253 L 474.7307 307.26253 C 472.5227 307.26253 470.7307 296.06253 470.7307 282.26253 C 470.7307 268.46253 472.5227 257.26253 474.7307 257.26253" fill="#218041"/><path d="M 474.7307 257.26253 L 506.7307 257.26253 C 508.9387 257.26253 510.7307 268.46253 510.7307 282.26253 C 510.7307 296.06253 508.9387 307.26253 506.7307 307.26253 L 474.7307 307.26253 C 472.5227 307.26253 470.7307 296.06253 470.7307 282.26253 C 470.7307 268.46253 472.5227 257.26253 474.7307 257.26253 M 506.7307 257.26253 C 504.5227 257.26253 502.7307 268.46253 502.7307 282.26253 C 502.7307 296.06253 504.5227 307.26253 506.7307 307.26253" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><g id="id597_Graphic"><path d="M 636.6057 220 L 636.6057 149.8 L 648.8057 142 L 758.6057 142 L 758.6057 212.2 L 746.4057 220 Z" fill="url(#Obj_Gradient_4)"/><path d="M 636.6057 220 L 636.6057 149.8 L 648.8057 142 L 758.6057 142 L 758.6057 212.2 L 746.4057 220 L 636.6057 220 M 636.6057 149.8 L 746.4057 149.8 L 758.6057 142 M 746.4057 149.8 L 746.4057 220" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(641.6057 149.8)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="12.230078" y="11" textLength="75.339844">Application 2</tspan></text></g><path d="M 514.57405 213.10361 L 512.27883 202.56842 L 613.96232 180.41551 L 612.81472 175.14791 L 636.6057 181 L 617.40514 196.21829 L 616.25754 190.9507 Z" fill="url(#Obj_Gradient_5)"/><path d="M 514.57405 213.10361 L 512.27883 202.56842 L 613.96232 180.41551 L 612.81472 175.14791 L 636.6057 181 L 617.40514 196.21829 L 616.25754 190.9507 Z" stroke="#513d99" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(532.21918 196.5776) rotate(-12.290493)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" fill="black" x="17.930041" y="11" textLength="48.691406">consume</tspan></text><g id="id599_Graphic"><path d="M 636.6057 329 L 636.6057 258.8 L 648.8057 251 L 758.6057 251 L 758.6057 321.2 L 746.4057 329 Z" fill="url(#Obj_Gradient_6)"/><path d="M 636.6057 329 L 636.6057 258.8 L 648.8057 251 L 758.6057 251 L 758.6057 321.2 L 746.4057 329 L 636.6057 329 M 636.6057 258.8 L 746.4057 258.8 L 758.6057 251 M 746.4057 258.8 L 746.4057 329" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(641.6057 258.8)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="bold" x="12.230078" y="11" textLength="75.339844">Application 3</tspan></text></g><path d="M 510.39994 287.64353 L 511.06147 276.88153 L 614.97792 283.26922 L 615.3087 277.88822 L 636.6057 290 L 613.98562 299.41222 L 614.3164 294.03122 Z" fill="url(#Obj_Gradient_7)"/><path d="M 510.39994 287.64353 L 511.06147 276.88153 L 614.97792 283.26922 L 615.3087 277.88822 L 636.6057 290 L 613.98562 299.41222 L 614.3164 294.03122 Z" stroke="#513d99" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(531.88514 276.54967) rotate(3.5175156)" fill="black"><tspan font-family="Helvetica" font-size="12" font-weight="500" fill="black" x="17.946518" y="11" textLength="48.691406">consume</tspan></text><g id="id19_Graphic"><rect x="415" y="188" width="31" height="32" fill="#218041"/><rect x="415" y="188" width="31" height="32" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><g id="id601_Graphic"><rect x="415" y="230" width="31" height="32" fill="#218041"/><rect x="415" y="230" width="31" height="32" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><g id="id602_Graphic"><rect x="415" y="272" width="31" height="32" fill="#218041"/><rect x="415" y="272" width="31" height="32" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g><path d="M 448.79433 245.96582 L 443.80928 242.23727 L 457.7571 223.5891 L 455.26457 221.72483 L 473.42644 207.83601 L 465.23466 229.18192 L 462.74214 227.31765 Z" fill="#e0c635"/><path d="M 448.79433 245.96582 L 443.80928 242.23727 L 457.7571 223.5891 L 455.26457 221.72483 L 473.42644 207.83601 L 465.23466 229.18192 L 462.74214 227.31765 Z" stroke="#513d99" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><path d="M 443.9547 246.64579 L 449.17973 243.26174 L 461.11203 261.68537 L 463.72454 259.99335 L 470.4589 281.84286 L 453.2745 266.76145 L 455.887 265.06942 Z" fill="#e0c635"/><path d="M 443.9547 246.64579 L 449.17973 243.26174 L 461.11203 261.68537 L 463.72454 259.99335 L 470.4589 281.84286 L 453.2745 266.76145 L 455.887 265.06942 Z" stroke="#513d99" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/></g></g></svg>
