diff options
| author | Alex Rudyy <orudyy@apache.org> | 2015-04-15 10:01:30 +0000 |
|---|---|---|
| committer | Alex Rudyy <orudyy@apache.org> | 2015-04-15 10:01:30 +0000 |
| commit | db3ef0f8eab2d3e6bc2001c6dcbf0fd896537314 (patch) | |
| tree | 4bbb0ac9072332074f8c30214e0b94c946fc526f /qpid | |
| parent | b15e32a943ae269c1c7dae4b2084e2ad87f3940d (diff) | |
| download | qpid-python-db3ef0f8eab2d3e6bc2001c6dcbf0fd896537314.tar.gz | |
QPID-6481: Move docbook for jms client for amqp 0.8/0.9.x into java source tree
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1673704 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'qpid')
20 files changed, 0 insertions, 2992 deletions
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 deleted file mode 100644 index f6d663c8b0..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml +++ /dev/null @@ -1,200 +0,0 @@ -<?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>AMQConnectionFailure / AMQAuthenticationException</entry> - <entry>not allowed</entry> - <entry><para>Indicates that the user cannot be authenticated by the Broker. Check the - username and/or password elements within the <link - linkend="JMS-Client-0-8-Connection-URL">Connection URL</link>.</para></entry> - </row> - <row> - <entry>AMQConnectionFailure / AMQSecurityException</entry> - <entry>Permission denied: <emphasis>virtualhost name</emphasis>; access refused</entry> - <entry><para>Indicates that the user is not authorised to connect to the given - virtualhost. The user is recognised by the Broker and is using the correct password - but does not have permission. This exception normally indicates that the user (or - group) has not been permissioned within the Broker's <ulink - url="&qpidJavaBrokerBook;Java-Broker-Security-ACLs.html">Access Control List - (ACL)</ulink>.</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> - <row> - <entry>AMQSecurityException</entry> - <entry>Permission denied: <emphasis>message varies</emphasis></entry> - <entry><para>Indicates that the user is not authorised to use the given resource or - perform the given operation. This exception normally indicates that the user (or - group) has not been permissioned within the Broker's <ulink - url="&qpidJavaBrokerBook;Java-Broker-Security-ACLs.html">Access Control List - (ACL)</ulink>.</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 deleted file mode 100644 index 9042854f56..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml +++ /dev/null @@ -1,69 +0,0 @@ -<?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 deleted file mode 100644 index dd1c86c846..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Binding-URL.xml +++ /dev/null @@ -1,244 +0,0 @@ -<?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 for addressing<footnote> - <para>The client also supports the ADDR format. This is documented in <ulink - url="&qpidProgrammingBook;">Programming in Apache Qpid</ulink>.</para> - </footnote>. It allows the specification of the bindings between a queue and an exchange, queue - and exchange creation arguments and some ancillary options.</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 deleted file mode 100644 index 5db6d4aa19..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml +++ /dev/null @@ -1,46 +0,0 @@ -<?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"/> - <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"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JMS-Extensions.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 deleted file mode 100644 index 06b1d6d7fc..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml +++ /dev/null @@ -1,337 +0,0 @@ -<?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> - <row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-SyncPublish"> - <entry> sync_publish </entry> - <entry> String </entry> - <entry> - <para> - If the value is 'all' the client library waits for confirmation - before returning from a send(), and if the send is unsuccessful the - send() will throw a JMSException. (Note this option requires an - extension to the AMQP protocol and will only work against a broker of - the 0.32 release or later.) - </para> - </entry> - </row> - <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> - <row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-CompressMessages"> - <entry>compressMessages</entry> - <entry>Boolean</entry> - <entry><para>Controls whether the client will compress messages before they they are sent.</para></entry> - </row> - <row id="JMS-Client-0-8-Connection-URL-ConnectionOptions-MessageCompressionThresholdSize"> - <entry>messageCompressionThresholdSize</entry> - <entry>Integer</entry> - <entry><para>The payload size beyond which the client will start to compress message payloads.</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> This option is used for turning on/off hostname verification when using SSL. - It is set to 'true' by default. You can disable verification by setting it to 'false': - <literal>ssl_verify_hostname='false'</literal>. - </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 deleted file mode 100644 index 234a2862cb..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml +++ /dev/null @@ -1,64 +0,0 @@ -<?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 deleted file mode 100644 index 87abbb8bfb..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml +++ /dev/null @@ -1,297 +0,0 @@ -<?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 deleted file mode 100644 index 7ffddade3a..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml +++ /dev/null @@ -1,68 +0,0 @@ -<?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.7 or higher.</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 deleted file mode 100644 index 3707e8981b..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml +++ /dev/null @@ -1,49 +0,0 @@ -<?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 deleted file mode 100644 index 537a1075fe..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml +++ /dev/null @@ -1,95 +0,0 @@ -<?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-JMS-Extensions"> - <title>JMS Extensions</title> - <para>This section illustrates using Qpid specific extentions to JMX for the managament of queues, - exchanges and bindings.</para> - <!-- TODO perhaps mention ConnectionListener?--> - <important> - <para>It is not recommended that these extensions are generally used. These interfaces are - subject to change and will not be supported in this form for AMQP 1.0. Instead, the reader is - directed towards the Managment interfaces of the Broker.</para> - </important> - <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Queue"> - <title>Queue Management</title> - <para>These extensions allow queues to be created or removed.</para> - <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Queue-Creation"> - <title>Queue creation</title> - <para>The following example illustrates the creation of the a LVQ queue from a - javax.jms.Session object. Note that this utilises a Qpid specific extension to JMS and - involves casting the session object back to its Qpid base-class.</para> - <example> - <title>Creation of an LVQ using the Qpid extension to JMS</title> - <programlisting><![CDATA[Map<String,Object> arguments = new HashMap<String, Object>(); -arguments.put("qpid.last_value_queue_key","ISIN"); -AMQDestination amqQueue = (AMQDestination) context.lookup("myqueue"); -((AMQSession<?,?>) session).createQueue( - AMQShortString.valueOf(amqQueue.getQueueName()), - amqQueue.isAutoDelete(), - amqQueue.isDurable(), - amqQueue.isExclusive(), - arguments); -]]></programlisting> - </example> - </section> - </section> - - <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding"> - <title>Binding Management</title> - <para>These extensions allow bindings to be created or removed.</para> - - <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding-Creation"> - <title>Binding creation</title> - <para>The following example illustrates the creation of queue binding to topic exchange with - JMS client.</para> - <example> - <title>Binding a queue using JMS</title> - <programlisting><![CDATA[ConnectionFactory connectionFactory = ... -Connection connection = connectionFactory.createConnection(); -AMQSession<?, ?> session = (AMQSession<?,?>)connection.createSession(false, Session.AUTO_ACKNOWLEDGE); - -... - -AMQShortString queueName = new AMQShortString("testQueue"); -AMQShortString routingKey = new AMQShortString("testRoutingKey"); -AMQDestination destination = (AMQDestination) session.createQueue(queueName.asString()); - -... - -// binding arguments -Map<String, Object> arguments = new HashMap<String, Object>(); -arguments.put("x-filter-jms-selector", "application='app1'"); - -// create binding -session.bindQueue(queueName, routingKey, FieldTable.convertToFieldTable(arguments), - new AMQShortString("amq.topic"), destination);]]></programlisting> - </example> - </section> - </section> -</appendix> 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 deleted file mode 100644 index fb7d96fd68..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml +++ /dev/null @@ -1,86 +0,0 @@ -<?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 deleted file mode 100644 index b231972784..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml +++ /dev/null @@ -1,73 +0,0 @@ -<?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 deleted file mode 100644 index a1b7a44725..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml +++ /dev/null @@ -1,655 +0,0 @@ -<?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> - <row> - <entry>qpid.connection_ssl_verify_hostname</entry> - <entry>boolean</entry> - <entry>true</entry> - <entry>This property is used to turn on/off broker host name verification on SSL negotiation - if SSL transport is used. It is set to 'true' by default. - <para>Setting this property to 'false' will disable that check and - allow you to ignore host name errors.</para></entry> - </row> - <row id="JMS-Client-0-8-System-Properties-ConnectionCompressMessages"> - <entry>qpid.connection_compress_messages</entry> - <entry>Boolean</entry> - <entry>false</entry> - <entry><para>Controls whether the client will compress messages before they they are sent.</para></entry> - </row> - <row id="JMS-Client-0-8-System-Properties-MessageCompressionThresholdSize"> - <entry>qpid.message_compression_threshold_size</entry> - <entry>Integer</entry> - <entry>102400</entry> - <entry><para>The payload size beyond which the client will start to compress message payloads.</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>Addressing syntax: ADDR (Address format) or BURL (Binding URL)</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-BindQueues"> - <entry>qpid.bind_queues</entry> - <entry>Boolean</entry> - <entry>true</entry> - <entry><para>If true, creating a consumer will also bind the queue to the - to the exchange using the routing key as a binding key. The - exchange name, queue name and routing key are taken from - the Binding URL associated with the Destination.</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 id="JMS-Client-0-8-System-Properties-SyncPublish"> - <entry>sync_publish</entry> - <entry>string</entry> - <entry>"" (disabled)</entry> - <entry> - <para>If 'all' is set then messages will be sent synchronously.</para> - <para>This can also be set per connection using the - <link linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-SyncPublish"> - 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 deleted file mode 100644 index 60af03476e..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml +++ /dev/null @@ -1,596 +0,0 @@ -<?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 conditions which AMQP specifications treats as - errors and mandates closing the connection). The JMS connection will also be closed if the - underlying TCP/IP connection is broken.</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 - <literal>nofailover</literal> 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> - </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?key_store='/path/to/app1_client_cert.ks'&key_store_password='secret''&ssl='true']]> - </screen> - </example> - </listitem> - </itemizedlist> - </section> - <section id="JMS-Client-0-8-Client-Understanding-Connection-MessageCompression"> - <title>Message Compression</title> - <para>The client has the ability to transparently compress message payloads on outgoing - messages and decompress them on incoming messages. In some environments and with some - payloads this feature might offer performance improvements by reducing the number of bytes - transmitted over the connection.</para> - <para>In order to make use of message compression, the Broker must enable the feature too, - otherwise the compression options will be ignored.</para> - <para> To enable message compression on the client use the connection url property <link - linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-CompressMessages" - ><literal>compressMessages</literal></link> (or JVM wide using the system property <link - linkend="JMS-Client-0-8-System-Properties-ConnectionCompressMessages" - ><literal>qpid.connection_compress_messages</literal></link>)</para> - <para>It is also possible to control the threshold at which the client will begin to compress - message payloads. See connection url property <link - linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-MessageCompressionThresholdSize" - ><literal>messageCompressionThresholdSize</literal></link> (or JVM wide using the system - property <link linkend="JMS-Client-0-8-System-Properties-MessageCompressionThresholdSize" - ><literal>qpid.message_compression_threshold_size</literal></link>)</para> - <note> - <para>The Broker, where necessary, takes care of compressing/decompressing messages of the - fly so that clients using message compression can exchange messages with clients not - supporting message compression transparently, without application intervention.</para> - </note> - </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 acknowledgement 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> - <para> - Settings maxprefetch to 0 ( either globally via JVM system property - <link linkend="JMS-Client-0-8-System-Properties-Maxprefetch" ><literal>max_prefetch</literal></link> - or on a connection level as a connection option - <link linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-Maxprefetch"><literal>maxprefetch</literal></link> ) - switches off the pre-fetching functionality. With maxprefetch=0 messages are fetched one by one without caching on the client. - </para> - <note> - <para> Setting maxprefetch to 0 is recommended in Spring-JMS based applications whenever - <emphasis>DefaultMassgeListenerContainer</emphasis> is configured with a - <emphasis>CachingConnectionFactory</emphasis> that has <emphasis>cacheLevel</emphasis> - set to either <emphasis>CACHE_CONSUMER</emphasis> or <emphasis>CACHE_SESSION</emphasis>. - In these configurations the Qpid JMS <emphasis>Session</emphasis> objects remain open in - Spring's dynamically scaled pools. If maxprefetch is not 0, any prefetched messages held - by the <emphasis>Session</emphasis> and any new ones subsequently sent to it (in the - background until prefetch is reached) will be effectively by 'stuck' (unavailable to the - application) until Spring decides to utilise the cached Session again. This can give the - impression that message delivery has stopped even though messages remain of the queue. - Setting maxprefetch to 0 prevents this problem from occurring.</para> - <para> If using maxprefetch > 0 <emphasis>SingleConnectionFactory</emphasis> must be - used. SingleConnectionFactory does not have the same session/consumer caching behaviour so - does not exhibit the same problem. </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 synchronous publish is not exlicitly enabled, - <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, or synchronous publishing must be enabled using either the - <link linkend="JMS-Client-0-8-System-Properties-SyncPublish">system property</link> or the - <link linkend="JMS-Client-0-8-Connection-URL-ConnectionOptions-SyncPublish">connection URL - option</link>.</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>If synchronous publishing has been enabled, and a mandatory message is returned, the - <ulink url="&oracleJeeDocUrl;javax/jms/MessageProducer.html#send(javax.jms.Message)" - >MessageProducer#send()</ulink> method will throw a JMSException. - </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>If this the mandatory flag is not set, the Broker will treat <ulink - url="&qpidJavaBrokerBook;Java-Broker-Concepts-Exchanges.html#Java-Broker-Concepts-Exchanges-UnroutableMessage" - >the messages as unroutable</ulink>.</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>If synchronous publishing has been enabled, and an immediate message is returned, the - <ulink url="&oracleJeeDocUrl;javax/jms/MessageProducer.html#send(javax.jms.Message)" - >MessageProducer#send()</ulink> method will throw a JMSException. - </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 declare, queue declare and bind side effects can be suppressed using system - properties <link linkend="JMS-Client-0-8-System-Properties-DeclareExchanges" - ><literal>qpid.declare_exchanges</literal></link>, <link - linkend="JMS-Client-0-8-System-Properties-DeclareQueues" - ><literal>qpid.declare_queues</literal></link> and <link - linkend="JMS-Client-0-8-System-Properties-BindQueues" - ><literal>qpid.bind_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 deleted file mode 100644 index ccb9d29f2f..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/Makefile +++ /dev/null @@ -1,20 +0,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. -# - -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 deleted file mode 100644 index 31f3bd414a..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/commonEntities.xml +++ /dev/null @@ -1,47 +0,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. - ---> - -<!ENTITY qpidVersion "0.32-SNAPSHOT"> -<!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/7/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 Binary files differdeleted file mode 100644 index 82f6efd0ef..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/images/JndiOverview.png +++ /dev/null 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 deleted file mode 100644 index a8d1f05552..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/images/JndiOverview.svg +++ /dev/null @@ -1,23 +0,0 @@ -<?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 Binary files differdeleted file mode 100644 index 1f90905747..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/images/QpidJmsOverview.png +++ /dev/null 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 deleted file mode 100644 index 55a354a108..0000000000 --- a/qpid/doc/book/src/jms-client-0-8/images/QpidJmsOverview.svg +++ /dev/null @@ -1,23 +0,0 @@ -<?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> |
