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

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. </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
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 @@
 
 		<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-properties-destination" linkends="callout-ptp
 				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-properties-destination" linkends="callout-ptp
 
 		<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,9 +218,9 @@ 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);
 
@@ -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();
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 @@
 
 <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>
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 <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">
@@ -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>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>
+       </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='localhost:5671?trust_store='/path/to/ap
           >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>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>).</note>
     </section>
     <section id="JMS-Client-0-8-Client-Understanding-Session-TemporaryQueues">
       <title>TemporaryQueues</title>
@@ -358,6 +379,10 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/ap
           linkend="JMS-Client-0-8-System-Properties-DefaultMandatoryTopic"
             ><literal>qpid.default_mandatory_topic</literal></link> for Queues and Topics
         respectively.</para>
+      <note>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.</note>
     </section>
     <section id="JMS-Client-0-8-Client-Understanding-MessageProducer-CloseWhenNoRoute">
       <title>Close When No Route</title>
@@ -373,6 +398,7 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/ap
     </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
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 @@
 <!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">