You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by rg...@apache.org on 2014/10/17 23:04:49 UTC
svn commit: r1632665 - in /qpid/trunk/qpid/doc/book/src/jms-client-0-8:
JMS-Client-Connection-URL.xml JMS-Client-System-Properties.xml
JMS-Client-Understanding.xml
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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org