You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kw...@apache.org on 2014/03/08 23:23:32 UTC
svn commit: r1575624 - in /qpid/branches/0.26: ./ qpid/ qpid/doc/book/
qpid/doc/book/src/jms-client-0-8/
Author: kwall
Date: Sat Mar 8 22:23:31 2014
New Revision: 1575624
URL: http://svn.apache.org/r1575624
Log:
QPID-5374: Create book for Qpid JMS Client when used with AMQP 0-8/0-9/0-9-1
Merged from trunk with commands:
svn merge -c 1554333 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1554404 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1554547 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1556193 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1556310 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1559483 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1563355 https://svn.apache.org/repos/asf/qpid/trunk
svn merge -c 1575617 https://svn.apache.org/repos/asf/qpid/trunk
Added:
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/
- copied from r1554333, qpid/trunk/qpid/doc/book/src/jms-client-0-8/
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml
- copied unchanged from r1554547, qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Exceptions.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml
- copied, changed from r1554404, qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml
- copied unchanged from r1554547, qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Logging.xml
Removed:
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Exceptions.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Hello-World-Example.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Turning-On-Logging.xml
Modified:
qpid/branches/0.26/ (props changed)
qpid/branches/0.26/qpid/ (props changed)
qpid/branches/0.26/qpid/doc/book/Makefile
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
Propchange: qpid/branches/0.26/
------------------------------------------------------------------------------
Merged /qpid/trunk:r1554333,1554404,1554547,1556193,1556310,1559483,1563355,1575617
Propchange: qpid/branches/0.26/qpid/
------------------------------------------------------------------------------
Merged /qpid/trunk/qpid:r1554333,1554404,1554547,1556193,1556310,1559483,1563355,1575617
Modified: qpid/branches/0.26/qpid/doc/book/Makefile
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/Makefile?rev=1575624&r1=1575623&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/Makefile (original)
+++ qpid/branches/0.26/qpid/doc/book/Makefile Sat Mar 8 22:23:31 2014
@@ -17,7 +17,7 @@
# under the License.
#
-DIRS = src/java-broker src/java-perftests src/cpp-broker src/programming
+DIRS = src/java-broker src/java-perftests src/cpp-broker src/programming src/jms-client-0-8
.PHONY: all $(DIRS)
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml Sat Mar 8 22:23:31 2014
@@ -29,8 +29,8 @@
<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-Hello-World-Example">examples</link> included in this
- book</para>
+ use with the <link linkend="JMS-Client-0-8-Examples">examples</link> included in this
+ book.</para>
<example>
<title>Minimal Maven POM </title>
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml Sat Mar 8 22:23:31 2014
@@ -26,7 +26,7 @@
<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-Hello-World-Example.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Examples.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Understanding.xml"/>
<!-- TODO:
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JMS-Extensions.xml"/>
@@ -35,12 +35,12 @@
<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-Turning-On-Logging.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-Exceptions.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"/>
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml Sat Mar 8 22:23:31 2014
@@ -56,7 +56,7 @@
</row>
</thead>
<tbody>
- <row>
+ <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>
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml Sat Mar 8 22:23:31 2014
@@ -34,14 +34,13 @@
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 is available from the <ulink
- url="http://www.amqp.org">AMQP web site</ulink>. </para>
+ 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
- <emphasis>Hello World</emphasis> application using Qpid JMS Client in <xref linkend="JMS-Client-0-8-Hello-World-Example"/>.
- </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
@@ -56,10 +55,10 @@
provides the extended operation set to invoke those features. </para>
<para>
- <xref linkend="JMS-Client-0-8-Turning-On-Logging"/> provides the details about turning on client logging
- which can help in debugging of various issues while developing the messaging applications.
- </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-Exceptions"/></para>
+ <para>The details about Qpid JMS Client Exceptions are provided in <xref
+ linkend="JMS-Client-0-8-Appendix-Exceptions"/></para>
</chapter>
Copied: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml (from r1554404, qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml)
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml?p2=qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml&p1=qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml&r1=1554404&r2=1575624&rev=1575624&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml Sat Mar 8 22:23:31 2014
@@ -48,7 +48,7 @@
<example id="JMS-Client-0-8-Examples-PTP-Java">
<title>JMS Example - Point to Point Messaging</title>
- <programlisting lang="java">
+ <programlisting language="java">
import javax.jms.*;
import javax.naming.Context;
import javax.naming.InitialContext;
@@ -67,29 +67,29 @@ public class Hello {
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"/>
+ 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"/>
+ = (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"/>
+ 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"/>
+ 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"/>
+ 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"/>
+ 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"/>
+ 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>
@@ -118,7 +118,7 @@ public class Hello {
<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 myqueue.</para>
+ <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>
@@ -137,7 +137,7 @@ public class Hello {
<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 TextMessages, publishes the messages and commits the
+ <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">
@@ -159,10 +159,10 @@ public class Hello {
<example id="JMS-Client-0-8-Examples-PTP-PropertiesFile">
<title>JMS Example - Point to Point Messaging - JNDI Properties</title>
- <programlisting>
+ <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"/>
+queue.myqueue = queue1 <co id="ptp-properties-destination" linkends="callout-ptp-properties-destination"/>
</programlisting>
</example>
@@ -171,7 +171,7 @@ queue.myqueue = queue1 <co id="ptp-prope
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-JNDI-Properties-Format"/>.</para>
+ 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
@@ -190,7 +190,7 @@ queue.myqueue = queue1 <co id="ptp-prope
<example id="JMS-Client-0-8-Examples-PubSub-Java">
<title>JMS Example - Publish/subscribe Messaging</title>
- <programlisting lang="java">
+ <programlisting language="java">
import javax.jms.*;
import javax.naming.Context;
import javax.naming.InitialContext;
@@ -218,15 +218,15 @@ public class StocksExample {
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"/>
+ 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 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.setStringProperty("price", "100");
+ message.setIntProperty("price", 100);
messageProducer.send(message);
session.commit();
@@ -238,7 +238,7 @@ public class StocksExample {
session.commit();
System.out.println("Subscriber 2 received : " + message);
- session.unsubscribe("sub1"); <co id="pubsub-java-unsubscribe" linkends="callout-pubsub-unsubscribe"/>
+ session.unsubscribe("sub1"); <co id="pubsub-java-unsubscribe" linkends="callout-pubsub-unsubscribe"/>
session.unsubscribe("sub2");
connection.close();
context.close();
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml Sat Mar 8 22:23:31 2014
@@ -28,7 +28,7 @@
<chapter id="JMS-Client-0-8-JMS-Getting-And-Dependencies">
<title>Getting the Client And Dependencies</title>
- <section>
+ <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
@@ -47,7 +47,7 @@
]]></screen>
<para><xref linkend="JMS-Client-0-8-Appendix-Maven"/> illustrates a minimal Maven POM required to use the Qpid Client.</para>
</section>
- <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>
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml Sat Mar 8 22:23:31 2014
@@ -30,9 +30,8 @@
<chapter id="JMS-Client-0-8-Introduction">
<title>Introduction</title>
- <para>Qpid JMS client is an implementation of <ulink
- url="http://download.oracle.com/otndocs/jcp/7195-jms-1.1-fr-spec-oth-JSpec/">JMS specification
- 1.1</ulink>. It utilises an AMQP transport layer for the performing of messaging operations.
+ <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>
@@ -44,7 +43,7 @@
<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 Programming in Apache Qpid.</para>
+ with AMQP 0-10 protocol, please refer to <ulink url="&qpidProgrammingBook;">Programming in Apache Qpid</ulink>.</para>
</important>
</chapter>
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml Sat Mar 8 22:23:31 2014
@@ -43,7 +43,7 @@ destination.<jndi name>=<binding url>
<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-Hello-World-Example"/></para>
+ 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">
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml Sat Mar 8 22:23:31 2014
@@ -172,7 +172,7 @@
<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), if creating it if is does not already exist.
+ Destination), creating it if is does not already exist.
</para></entry>
</row>
<row id="JMS-Client-0-8-System-Properties-DeclareQueues">
@@ -181,7 +181,7 @@
<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), if creating it if is does not already
+ Destination), creating it if is does not already
exist.</para></entry>
</row>
<row id="JMS-Client-0-8-System-Properties-RejectBehaviour">
@@ -359,7 +359,7 @@
specify an alternative transport mechanism that implements the interface
<varname>org.apache.qpid.transport.network.OutgoingNetworkTransport</varname>.</para></entry>
</row>
- <row>
+ <row id="JMS-Client-0-8-System-Properties-SyncOpTimeout">
<entry>qpid.sync_op_timeout</entry>
<entry>long</entry>
<entry>60000</entry>
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml Sat Mar 8 22:23:31 2014
@@ -60,12 +60,11 @@
<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 Hello World example in the previous chapter illustrated the Java code required to
- <link linkend="callout-java-properties">create the InitialContext</link> and an <link
- linkend="JMS-Client-0-8-Hello-World-Example-PropertiesFile">example properties
- file</link>.</para>
+ >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>
@@ -91,8 +90,8 @@
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). The JMS connection will also be closed if the underlying TCP/IP connection is
- broken.</para>
+ operation or broker shutdown or running into coditions which AMQP specifications treats as errors and mandates closing the connection).
+ The JMS connection will also be closed if the underlying TCP/IP connection is broken.</para>
<para>Qpid connections have failover and heartbeating capabilities. They support SSL and
client-auth. These are described in the sub-sections that follow.</para>
<section id="JMS-Client-0-8-Client-Understanding-Connection-Failover">
@@ -113,9 +112,10 @@
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
- AMQDisconnectedException. Any further use of the JMS objects (Connection, Session etc), will
- results in a <ulink url="&oracleJeeDocUrl;javax/jms/IllegalStateException.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
@@ -136,6 +136,16 @@ amqp://username:password@clientid/test
</screen>
</example>
<para>For full details see <xref linkend="JMS-Client-0-8-Connection-URL"/></para>
+ <note><para>Note, that a single broker failover is enabled by default. If the failover behaviour is not desired it can be switched off
+ by setting a failover option to <emphasis>nofailover</emphasis> as in the example below
+ <example>
+ <title>Connection URL configured with nofailover</title>
+ <screen><![CDATA[
+amqp://username:password@clientid/test
+ ?brokerlist='tcp://localhost:15672?failover='nofailover']]>
+ </screen>
+ </example>
+ </para></note>
<!-- TODO perhaps mention ConnectionListener?-->
</section>
<section id="JMS-Client-0-8-Client-Understanding-Connection-Heartbeating">
@@ -274,6 +284,17 @@ amqp://guest:guest@clientid/?brokerlist=
>MessageConsumer#receive()</ulink> for Consumer B on the same Session, the application
will hang indefinitely as even if messages suitable for B arrive at the Broker. Those
messages can never be sent to the Session as no space is available in prefetch. </para>
+ <note><para>Please note, when the acknowlegement mode <emphasis>Session#SESSION_TRANSACTED</emphasis>
+ or <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis> is set on a consuming session,
+ the prefetched messages are released from the prefetch buffer on transaction commit/rollback
+ (in case of acknowledgement mode <emphasis>Session#SESSION_TRANSACTED</emphasis> )
+ or acknowledgement of the messages receipt (in case of acknowledgement mode
+ <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis> ). If the consuming application does not commit/rollback
+ the receiving transaction (for example, due to mistakes in application exception handling logic),
+ the prefetched messages continue to remain in the prefetch buffer preventing the delivery of the following messages.
+ As result, the application might stop the receiving of the messages
+ until the transaction is committed/rolled back (for <emphasis>Session#SESSION_TRANSACTED</emphasis> )
+ or received messages are acknowledged (for <emphasis>Session#CLIENT_ACKNOWLEDGE</emphasis>).</para></note>
</section>
<section id="JMS-Client-0-8-Client-Understanding-Session-TemporaryQueues">
<title>TemporaryQueues</title>
@@ -312,7 +333,7 @@ amqp://guest:guest@clientid/?brokerlist=
>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#createTopix() has no effect on the Broker.</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>
@@ -346,9 +367,11 @@ amqp://guest:guest@clientid/?brokerlist=
<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 AMQNoRouteException. The returned message is
- available to the application by calling AMQNoRouteException#getUndeliveredMessage(). The
- ExceptionListener will be invoked exactly once for each returned message.</para>
+ JMSException whose linked exception is an <ulink
+ url="JMS-Client-0-8-Appendix-Exceptions-AMQNoRouteException">AMQNoRouteException</ulink>.
+ The returned message is available to the application by calling
+ AMQNoRouteException#getUndeliveredMessage(). The ExceptionListener will be invoked exactly
+ once for each returned message.</para>
<para>The mandatory message feature is turned <emphasis>on</emphasis> by default for Queue
destinations and <emphasis>off</emphasis> for Topic destinations. This can be overridden
using system properties <link linkend="JMS-Client-0-8-System-Properties-DefaultMandatory"
@@ -356,6 +379,10 @@ amqp://guest:guest@clientid/?brokerlist=
linkend="JMS-Client-0-8-System-Properties-DefaultMandatoryTopic"
><literal>qpid.default_mandatory_topic</literal></link> for Queues and Topics
respectively.</para>
+ <note><para>Please note, according to AMQP specifications the mandatory flag on a message tells the server
+ how to react if the message cannot be routed to a queue. If this flag is set, the server will return an unroutable message with a
+ Return method. If this flag is zero, the server silently drops the message. Please, refer <ulink url="&amqpSrc;">AMQP specifications</ulink>
+ for more details.</para></note>
</section>
<section id="JMS-Client-0-8-Client-Understanding-MessageProducer-CloseWhenNoRoute">
<title>Close When No Route</title>
@@ -371,15 +398,17 @@ amqp://guest:guest@clientid/?brokerlist=
</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
- AMQNoConsumersException. The returned message is available to the application by calling
- AMQNoConsumersException#getUndeliveredMessage(). The ExceptionListener will be invoked
- exactly once for each returned message.</para>
+ <ulink url="JMS-Client-0-8-Appendix-Exceptions-AMQNoConsumersException"
+ >AMQNoConsumersException</ulink>. The returned message is available to the application by
+ calling AMQNoConsumersException#getUndeliveredMessage(). The ExceptionListener will be
+ invoked exactly once for each returned message.</para>
<para>The immediate message feature is turned <emphasis>off</emphasis> by default. It can be
enabled with system property <link
linkend="JMS-Client-0-8-System-Properties-DefaultImmediate"
@@ -449,8 +478,8 @@ amqp://guest:guest@clientid/?brokerlist=
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#unsubscriber(java.lang.String)"
- >Session#unsubscriber(java.lang.String)</ulink> deletes the underlying queue.</para>
+ 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>
@@ -477,8 +506,10 @@ amqp://guest:guest@clientid/?brokerlist=
<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"
- > Unhandling Undeliverable Messages</ulink> within the Java Broker book for full details
- of the functioning of this feature.</para>
+ > 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">
Modified: qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
URL: http://svn.apache.org/viewvc/qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/commonEntities.xml?rev=1575624&r1=1554333&r2=1575624&view=diff
==============================================================================
--- qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/commonEntities.xml (original)
+++ qpid/branches/0.26/qpid/doc/book/src/jms-client-0-8/commonEntities.xml Sat Mar 8 22:23:31 2014
@@ -19,7 +19,7 @@
-->
-<!ENTITY qpidVersion "0.24">
+<!ENTITY qpidVersion "0.26">
<!ENTITY qpidDownloadUrlDesc "the Apache Qpid project web site">
<!ENTITY qpidDownloadUrl "http://qpid.apache.org/download.html">
@@ -32,11 +32,15 @@
<!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://docs.oracle.com/cd/E19957-01/816-5904-10/816-5904-10.pdf">
+<!ENTITY oracleJmsSpec "http://download.oracle.com/otndocs/jcp/7195-jms-1.1-fr-spec-oth-JSpec/">
<!ENTITY oracleJdkDocUrl "http://docs.oracle.com/javase/6/docs/api/">
<!ENTITY oracleJeeDocUrl "http://docs.oracle.com/javaee/6/api/">
+<!ENTITY oracleJmsTutorial "http://docs.oracle.com/javaee/6/tutorial/doc/bncdq.html">
+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org