Author: rgodfrey
Date: Fri Oct 17 21:04:49 2014
New Revision: 1632665
URL: http://svn.apache.org/r1632665
Log:
QPID-6164 : add documentation to the client book
Modified:
qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
Modified:
qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml?rev=1632665&r1=1632664&r2=1632665&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
(original)
+++ qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-Connection-URL.xml
Fri Oct 17 21:04:49 2014
@@ -74,23 +74,25 @@
</para>
</entry>
</row>
- <!-- 0-10 only
- <row>
+ <row
id="JMS-Client-0-8-Connection-URL-ConnectionOptions-SyncPublish">
<entry> sync_publish </entry>
- <entry> {'persistent' | 'all'} </entry>
- <entry> A sync command is sent after
every persistent message to guarantee that
- it has been received; if the
value is 'persistent', this is done only for
- persistent messages. </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>
- -->
- <!-- 0-10 only
<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>
Modified:
qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml?rev=1632665&r1=1632664&r2=1632665&view=diff
==============================================================================
---
qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
(original)
+++
qpid/trunk/qpid/doc/book/src/jms-client-0-8/JMS-Client-System-Properties.xml
Fri Oct 17 21:04:49 2014
@@ -319,17 +319,22 @@
/>. The frequency at
which the log message informing that the producer
is flow controlled
.</para></entry>
</row>
- <!--
- <row>
+
+ <row
id="JMS-Client-0-8-System-Properties-SyncPublish">
<entry>sync_publish</entry>
<entry>string</entry>
<entry>"" (disabled)</entry>
- <entry><para>If one of {persistent|all}
is set then persistent messages or all
- messages will be sent
synchronously.</para><para>This can also be set
- per connection using
the <link linkend="section-jms-connection-url"
- >Connection
URL</link> options.</para></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>
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=1632665&r1=1632664&r2=1632665&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
Fri Oct 17 21:04:49 2014
@@ -352,7 +352,7 @@ amqp://guest:guest@clientid/?brokerlist=
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>
+ 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>
@@ -363,7 +363,7 @@ amqp://guest:guest@clientid/?brokerlist=
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>
+ 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>
@@ -378,8 +378,8 @@ amqp://guest:guest@clientid/?brokerlist=
<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 not used on a transactional
session, <ulink
-
url="&oracleJeeDocUrl;javax/jms/MessageProducer.html#send(javax.jms.Message)"
+ <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
@@ -387,7 +387,10 @@ amqp://guest:guest@clientid/?brokerlist=
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.</para>
+ <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">
@@ -403,6 +406,10 @@ amqp://guest:guest@clientid/?brokerlist=
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"
@@ -441,6 +448,10 @@ amqp://guest:guest@clientid/?brokerlist=
>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"
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
