qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From oru...@apache.org
Subject svn commit: r1556193 - in /qpid/trunk/qpid/doc/book/src/jms-client-0-8: JMS-Client-Document-Scope-And-Intended-Audience.xml JMS-Client-Examples.xml JMS-Client-Introduction.xml JMS-Client-Understanding.xml commonEntities.xml
Date Tue, 07 Jan 2014 12:09:35 GMT
Author: orudyy
Date: Tue Jan  7 12:09:34 2014
New Revision: 1556193

URL: http://svn.apache.org/r1556193
Log:
QPID-5374: [Documentation] Add minor corrections, notes and indentation fixes in JMS client
documentation

Modified:
    qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
    qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml
    qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml
    qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
    qpid/trunk/qpid/doc/book/src/jms-client-0-8/commonEntities.xml

Modified: qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml?rev=1556193&r1=1556192&r2=1556193&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
(original)
+++ qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
Tue Jan  7 12:09:34 2014
@@ -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

Modified: qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml?rev=1556193&r1=1556192&r2=1556193&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml (original)
+++ qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml Tue Jan  7 12:09:34
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,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();

Modified: qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml?rev=1556193&r1=1556192&r2=1556193&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml (original)
+++ qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Introduction.xml Tue Jan  7 12:09:34
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/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml?rev=1556193&r1=1556192&r2=1556193&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml (original)
+++ qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml Tue Jan  7 12:09:34
2014
@@ -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=
           >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=
           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=
     </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

Modified: qpid/trunk/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/jms-client-0-8/commonEntities.xml?rev=1556193&r1=1556192&r2=1556193&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/jms-client-0-8/commonEntities.xml (original)
+++ qpid/trunk/qpid/doc/book/src/jms-client-0-8/commonEntities.xml Tue Jan  7 12:09:34 2014
@@ -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">



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message