Author: rajith
Date: Wed Jan 19 03:14:13 2011
New Revision: 1060667
URL: http://svn.apache.org/viewvc?rev=1060667&view=rev
Log:
Added a new section titled "Configuring the JMS Client".
Most of the properties added here are applicable to the 0-10 client.
Modified:
qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
Modified: qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml?rev=1060667&r1=1060666&r2=1060667&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml (original)
+++ qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml Wed Jan 19
03:14:13 2011
@@ -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.Conversion
</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'
+ &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">
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
