Added a new section titled "Configuring the JMS Client".

Most of the properties added here are applicable to the 0-10 client.


git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1060667 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 387 insertions, 1 deletions

diff --git a/qpid/doc/book/src/Programming-In-Apache-Qpid.xml b/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
index 51d5ea179c..f4c82ac748 100644
--- a/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
+++ b/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
@@ -2909,7 +2909,7 @@ destination.topicExchange = amq.topic
         </table>
       </section>
       
-      <section>
+      <section id="section-jms-connection-url">
         <title>Connection URLs</title>
         <para>
 	  In JNDI properties, a Connection URL specifies properties for a connection. The format for a Connection URL is:
@@ -3403,6 +3403,392 @@ log4j.appender.console.layout.ConversionPattern=%t %d %p [%c{4}] %m%n
 
     </section>
 
+    <section>
+      <title>Configuring the JMS Client</title>
+
+      <para>The Qpid JMS Client allows several configuration options to customize it's behaviour at different levels of granualarity.</para>
+      
+      <itemizedlist>
+        <listitem>
+          <para>
+            JVM level using JVM arguments : Configuration that affects all connections, sessions, consumers and producers created within that JVM.
+	      </para>
+          <para>Ex. <varname>-Dmax_prefetch=1000</varname> property specifies the message credits to use.</para> 
+        </listitem>
+
+        <listitem>
+          <para>
+            Connection level using Connection/Broker properties : Affects the respective connection and sessions, consumers and produces created by that connection.
+	      </para>
+          <para>Ex. <varname>amqp://guest:guest@test/test?max_prefetch='1000'
+    &amp;brokerlist='tcp://localhost:5672'
+</varname> property specifies the message credits to use. This overrides any value specified via the JVM argument <varname>max_prefetch</varname>.</para> 
+          <para>Please refer to the <xref linkend="section-jms-connection-url"/> section for a complete list of all properties and how to use them.</para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Destination level using Addressing options : Affects the producer(s) and consumer(s) created using the respective destination.
+	      </para>
+          <para>Ex. <varname>my-queue; {create: always, link:{capacity: 10}}</varname>, where <varname>capacity</varname> option specifies the message credits to use. This overrides any connection level configuration.</para> 
+          <para>Please refer to the <xref linkend="section-addresses"/> section for a complete understanding of addressing and it's various options.</para>
+        </listitem>
+      </itemizedlist>
+ 
+<para>Some of these config options are available at all three levels (Ex. <varname>max_prefetch</varname>), while others are available only at JVM or connection level.</para>
+
+      <section>
+        <title>Qpid JVM Arguments</title>
+
+          <table >
+            <title>Config Options For Connection Behaviour</title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>qpid.amqp.version</entry>
+	              <entry>string</entry>
+	              <entry>0-10</entry>
+                  <entry>Sets the AMQP version to be used - currently supports one of {0-8,0-9,0-91,0-10}</entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.heartbeat</entry>
+	              <entry>int</entry>
+	              <entry>120 (secs)</entry>
+                  <entry>The heartbeat interval in seconds. Two consective misssed heartbeats will result in the connection timing out.<para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+
+	            <row>
+	              <entry>ignore_setclientID</entry>
+	              <entry>boolean</entry>
+	              <entry>false</entry>
+                  <entry>If a client ID is specified in the connection URL it's used or else an ID is generated. If an ID is specified after it's been set Qpid will throw an exception. <para>Setting this property to 'true' will disable that check and allow you to set a client ID of your choice later on.</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+
+          <table >
+            <title>Config Options For Session Behaviour</title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>qpid.session.command_limit</entry>
+	              <entry>int</entry>
+	              <entry>65536</entry>
+                  <entry>Limits the # of unacked commands</entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.session.byte_limit</entry>
+	              <entry>int</entry>
+	              <entry>1048576</entry>
+                  <entry>Limits the # of unacked commands in terms of bytes</entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.use_legacy_map_message</entry>
+	              <entry>boolean</entry>
+	              <entry>false</entry>
+                  <entry><para>If set will use the old map message encoding. By default the Map messages are encoded using the 0-10 map encoding.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+          <table >
+            <title>Config Options For Consumer Behaviour</title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>max_prefetch</entry>
+	              <entry>int</entry>
+	              <entry>500</entry>
+                  <entry>Maximum number of messages to credits. <para>This could also be set per connection (see connection paramters) or per destination (see the <varname>capacity</varname> option under link properties in addressing).</para></entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.session.max_ack_delay</entry>
+	              <entry>long</entry>
+	              <entry>1000 (ms)</entry>
+                  <entry><para>Timer interval to flush message acks in buffer when using AUTO_ACK and DUPS_OK.</para> <para>When using the above ack modes, message acks are batched and sent if one of the following conditions are met (which ever happens first).
+                            <itemizedlist>
+                                    <listitem>When the ack timer fires.</listitem>          
+                                    <listitem>if un_acked_msg_count > max_prefetch/2.</listitem>          
+                            </itemizedlist>
+                        </para>
+                        <para>The ack timer can be disabled by setting it to 0.</para>
+                  </entry>
+                </row>
+
+	            <row>
+	              <entry>sync_ack</entry>
+	              <entry>boolean</entry>
+	              <entry>false</entry>
+                  <entry><para>If set, each message will be acknowledged synchronously. When using AUTO_ACK mode, you need to set this to "true", in order to get the correct behaviour as described by the JMS spec.</para><para>This is set to false by default for performance reasons, therefore by default AUTO_ACK behaves similar to DUPS_OK.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+          <table >
+            <title>Config Options For Producer Behaviour</title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <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 could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+          <table >
+            <title>Config Options For Threading</title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>qpid.thread_factory</entry>
+	              <entry>string</entry>
+	              <entry>org.apache.qpid.thread.DefaultThreadFactory</entry>
+                  <entry><para>Specifies the thread factory to use.</para><para>If using a real time JVM, you need to set the above property to <varname>org.apache.qpid.thread.RealtimeThreadFactory</varname>.</para></entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.rt_thread_priority</entry>
+	              <entry>int</entry>
+	              <entry>20</entry>
+                  <entry><para>Specifies the priority (1-99) for Real time threads created by the real time thread factory.</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+          <table >
+            <title>Config Options For I/O</title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>qpid.transport</entry>
+	              <entry>string</entry>
+	              <entry>org.apache.qpid.transport.network.io.IoNetworkTransport</entry>
+                  <entry><para>The transport implementation to be used.</para><para>A user could specify an alternative transport mechanism that implements the <varname>org.apache.qpid.transport.network.NetworkTransport</varname> interface.</para></entry>
+                </row>
+
+	            <row>
+	              <entry>amqj.tcp_nodelay</entry>
+	              <entry>boolean</entry>
+	              <entry>false</entry>
+                  <entry><para>Sets the TCP_NODELAY property of the underlying socket.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+          <table >
+            <title>Config Options For Security</title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>qpid.sasl_mechs</entry>
+	              <entry>string</entry>
+	              <entry>PLAIN</entry>
+                  <entry><para>The SASL mechanism to be used. More than one could be specified as a comma separated list.</para><para>We currently support the following mechanisms {PLAIN | GSSAPI | EXTERNAL}.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.sasl_protocol</entry>
+	              <entry>string</entry>
+	              <entry>AMQP</entry>
+                  <entry><para>When using GSSAPI as the SASL mechanism, <varname>sasl_protocol</varname> must be set to the principal for the qpidd broker, e.g. <varname>qpidd</varname>.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.sasl_server_name</entry>
+	              <entry>string</entry>
+	              <entry>localhost</entry>
+                  <entry><para>When using GSSAPI as the SASL mechanism, <varname>sasl_server</varname> must be set to the host for the SASL server, e.g. <varname>example.com</varname>.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+          <table>
+            <title>Config Options For Security - Standard JVM properties needed when using GSSAPI as the SASL mechanism.<footnote>Please refer to the Java security documentation for a complete understanding of the above properties.</footnote></title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>javax.security.auth.useSubjectCredsOnly</entry>
+	              <entry>boolean</entry>
+	              <entry>true</entry>
+                  <entry><para>If set to 'false', forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread.</para></entry>
+                </row>
+
+	            <row>
+	              <entry>java.security.auth.login.config</entry>
+	              <entry>string</entry>
+	              <entry></entry>
+                  <entry><para>Specifies the jass configuration file.</para><para><varname>Ex-Djava.security.auth.login.config=myjas.conf</varname>
+</para><para>Here is the sample myjas.conf JASS configuration file: <programlisting><![CDATA[
+
+    com.sun.security.jgss.initiate {
+        com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
+    };
+
+]]></programlisting></para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+          <table>
+            <title>Config Options For Security - Using SSL for securing connections or using EXTERNAL as the SASL mechanism.</title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>qpid.ssl_timeout</entry>
+	              <entry>long</entry>
+	              <entry>60000</entry>
+                  <entry><para>Timeout value used by the Java SSL engine when waiting on operations.</para></entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.ssl.keyStoreCertType</entry>
+	              <entry>string</entry>
+	              <entry>SunX509</entry>
+                  <entry><para>The certificate type.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+
+	            <row>
+	              <entry>qpid.ssl.trustStoreCertType</entry>
+	              <entry>string</entry>
+	              <entry>SunX509</entry>
+                  <entry><para>The certificate type.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+
+          <table>
+            <title>Config Options For Security - Standard JVM properties needed when Using SSL for securing connections or using EXTERNAL as the SASL mechanism.<footnote>Qpid allows you to have per connection key and trust stores if required. If specified per connection, the JVM arguments are ignored.</footnote></title>
+            <tgroup cols="3">
+              <thead>
+	            <row>
+	              <entry>Property Name</entry>
+	              <entry>Type</entry>
+	              <entry>Default Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+	            <row>
+	              <entry>javax.net.ssl.keyStore</entry>
+	              <entry>string</entry>
+	              <entry>jvm default</entry>
+                  <entry><para>Specifies the key store path.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+
+                <row>
+	              <entry>javax.net.ssl.keyStorePassword</entry>
+	              <entry>string</entry>
+	              <entry>jvm default</entry>
+                  <entry><para>Specifies the key store password.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+
+	            <row>
+	              <entry>javax.net.ssl.trustStore</entry>
+	              <entry>string</entry>
+	              <entry>jvm default</entry>
+                  <entry><para>Specifies the trust store path.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+
+                <row>
+	              <entry>javax.net.ssl.trustStorePassword</entry>
+	              <entry>string</entry>
+	              <entry>jvm default</entry>
+                  <entry><para>Specifies the trust store password.</para><para>This could also be set per connection as well (see connection paramters).</para></entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+     </section>
+    </section>
+
   </chapter>
 
   <chapter id="QpidWCF">