From 4db1b7d5f93ddbba1a8fe97b060fd920cdfaf2c1 Mon Sep 17 00:00:00 2001 From: Alex Rudyy Date: Tue, 7 Jan 2014 12:09:34 +0000 Subject: QPID-5374: [Documentation] Add minor corrections, notes and indentation fixes in JMS client documentation git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1556193 13f79535-47bb-0310-9956-ffa450edef68 --- ...Client-Document-Scope-And-Intended-Audience.xml | 4 +- .../src/jms-client-0-8/JMS-Client-Examples.xml | 44 +++++++++++----------- .../src/jms-client-0-8/JMS-Client-Introduction.xml | 7 ++-- .../jms-client-0-8/JMS-Client-Understanding.xml | 30 ++++++++++++++- .../doc/book/src/jms-client-0-8/commonEntities.xml | 4 +- 5 files changed, 58 insertions(+), 31 deletions(-) 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 index d4b88f61d2..234a2862cb 100644 --- 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 @@ -34,8 +34,8 @@ knowledge of AMQP basic concepts would be advantageous for reading of this document. 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 AMQP web site. + client. The specifications for these protocols are available from the AMQP web site. The document covers some specific implementation details of JMS connections, sessions, consumers and producers in . It also 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 index 5ab40a006a..d7dc481888 100644 --- 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 @@ -48,7 +48,7 @@ JMS Example - Point to Point Messaging - + 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")); - Context context = new InitialContext(properties); + Context context = new InitialContext(properties); ConnectionFactory connectionFactory - = (ConnectionFactory) context.lookup("qpidConnectionFactory"); - Connection connection = connectionFactory.createConnection(); - connection.start(); + = (ConnectionFactory) context.lookup("qpidConnectionFactory"); + Connection connection = connectionFactory.createConnection(); + connection.start(); - Session session = connection.createSession(true, Session.SESSION_TRANSACTED); - Queue queue = (Queue) context.lookup("myqueue"); + Session session = connection.createSession(true, Session.SESSION_TRANSACTED); + Queue queue = (Queue) context.lookup("myqueue"); - MessageConsumer messageConsumer = session.createConsumer(queue); - MessageProducer messageProducer = session.createProducer(queue); + MessageConsumer messageConsumer = session.createConsumer(queue); + MessageProducer messageProducer = session.createProducer(queue); - TextMessage message = session.createTextMessage("Hello world!"); + TextMessage message = session.createTextMessage("Hello world!"); messageProducer.send(message); session.commit(); - message = (TextMessage)messageConsumer.receive(); + message = (TextMessage)messageConsumer.receive(); session.commit(); System.out.println(message.getText()); - connection.close(); - context.close(); + connection.close(); + context.close(); } } @@ -118,7 +118,7 @@ public class Hello { Creates a transactional session. - Looks up a destination for the queue with JNDI name myqueue. + Looks up a destination for the queue with JNDI name myqueue. Creates a consumer that reads messages from the queue @@ -137,7 +137,7 @@ public class Hello { Creates a producer that sends messages to the queue. - Creates a new TextMessages, publishes the messages and commits the + Creates a new message of type javax.jms.TextMessage, publishes the message and commits the session. @@ -159,10 +159,10 @@ public class Hello { JMS Example - Point to Point Messaging - JNDI Properties - + java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory connectionfactory.qpidConnectionFactory = amqp://guest:guest@clientid/?brokerlist='tcp://localhost:5672' -queue.myqueue = queue1 +queue.myqueue = queue1 @@ -171,7 +171,7 @@ queue.myqueue = queue1 Defines a connection factory from which Connections can be created. The syntax of a ConnectionURL is given in . + linkend="JMS-Client-0-8-Connection-URL"/>. Defines a queue for which MessageProducers and/or MessageConsumers send and @@ -190,7 +190,7 @@ queue.myqueue = queue1 JMS Example - Publish/subscribe Messaging - + import javax.jms.*; import javax.naming.Context; import javax.naming.InitialContext; @@ -218,9 +218,9 @@ public class StocksExample { connection.start(); Session session = connection.createSession(true, Session.SESSION_TRANSACTED); - Topic priceTopic = (Topic) context.lookup("myprices"); + Topic priceTopic = (Topic) context.lookup("myprices"); - MessageConsumer subscriber1 = session.createDurableSubscriber(priceTopic, "sub1"); + MessageConsumer subscriber1 = session.createDurableSubscriber(priceTopic, "sub1"); MessageConsumer subscriber2 = session.createDurableSubscriber(priceTopic, "sub2" /*, "price > 150", false*/ ); MessageProducer messageProducer = session.createProducer(priceTopic); @@ -238,7 +238,7 @@ public class StocksExample { session.commit(); System.out.println("Subscriber 2 received : " + message); - session.unsubscribe("sub1"); + session.unsubscribe("sub1"); session.unsubscribe("sub2"); connection.close(); context.close(); 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 index 4cd65f6677..3707e8981b 100644 --- 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 @@ -30,9 +30,8 @@ Introduction - Qpid JMS client is an implementation of JMS specification - 1.1. It utilises an AMQP transport layer for the performing of messaging operations. + Qpid JMS client is an implementation of JMS specification + 1.1. It utilises an AMQP 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. @@ -44,7 +43,7 @@ Using the Qpid JMS client with 0-10 This book documents the behaviour of the Qpid JMS client when used with the AMQP protocols 0-8, 0-9, and 0-9-1 only. For behaviour when using the client - with AMQP 0-10 protocol, please refer to Programming in Apache Qpid. + with AMQP 0-10 protocol, please refer to Programming in Apache Qpid. 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 index bfb71ea73e..006978c9d4 100644 --- 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 @@ -90,8 +90,8 @@ is closed when the application calls Connection#close(), 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. + 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. Qpid connections have failover and heartbeating capabilities. They support SSL and client-auth. These are described in the sub-sections that follow.
@@ -136,6 +136,16 @@ amqp://username:password@clientid/test For full details see + 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 nofailover as in the example below + + Connection URL configured with nofailover + + + +
@@ -274,6 +284,17 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/ap >MessageConsumer#receive() 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. + Please note, when the acknowlegement mode Session#SESSION_TRANSACTED + or Session#CLIENT_ACKNOWLEDGE is set on a consuming session, + the prefetched messages are released from the prefetch buffer on transaction commit/rollback + (in case of acknowledgement mode Session#SESSION_TRANSACTED ) + or acknowledgement of the messages receipt (in case of acknowledgement mode + Session#CLIENT_ACKNOWLEDGE ). 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 Session#SESSION_TRANSACTED ) + or received messages are acknowledged (for Session#CLIENT_ACKNOWLEDGE).
TemporaryQueues @@ -358,6 +379,10 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/ap linkend="JMS-Client-0-8-System-Properties-DefaultMandatoryTopic" >qpid.default_mandatory_topic for Queues and Topics respectively. + 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 AMQP specifications + for more details.
Close When No Route @@ -373,6 +398,7 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/ap
Immediate Messages + This feature is defined in AMQP specifications. 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 diff --git a/qpid/doc/book/src/jms-client-0-8/commonEntities.xml b/qpid/doc/book/src/jms-client-0-8/commonEntities.xml index 86105ca95e..556b606878 100644 --- a/qpid/doc/book/src/jms-client-0-8/commonEntities.xml +++ b/qpid/doc/book/src/jms-client-0-8/commonEntities.xml @@ -32,9 +32,11 @@ + + - + -- cgit v1.2.1