diff options
author | Rajith Muditha Attapattu <rajith@apache.org> | 2011-01-19 03:14:13 +0000 |
---|---|---|
committer | Rajith Muditha Attapattu <rajith@apache.org> | 2011-01-19 03:14:13 +0000 |
commit | 555771de4a3b75516979b1220c140fccabdba549 (patch) | |
tree | 1825ea5486cc853f02d7b7c7ad1ca1d04052da31 /qpid/doc | |
parent | b4462bef74f9dfedf726f4eed29f9463825e2d7b (diff) | |
download | qpid-python-555771de4a3b75516979b1220c140fccabdba549.tar.gz |
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
Diffstat (limited to 'qpid/doc')
-rw-r--r-- | qpid/doc/book/src/Programming-In-Apache-Qpid.xml | 388 |
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' + &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"> |