qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rob...@apache.org
Subject svn commit: r1743909 - /qpid/java/trunk/doc/jms-client-0-10/src/docbkx/JMS-Client-0-10-Book.xml
Date Sun, 15 May 2016 14:49:49 GMT
Author: robbie
Date: Sun May 15 14:49:49 2016
New Revision: 1743909

URL: http://svn.apache.org/viewvc?rev=1743909&view=rev
Log:
QPID-7265: add jndi section back under the configuring section

Modified:
    qpid/java/trunk/doc/jms-client-0-10/src/docbkx/JMS-Client-0-10-Book.xml

Modified: qpid/java/trunk/doc/jms-client-0-10/src/docbkx/JMS-Client-0-10-Book.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/jms-client-0-10/src/docbkx/JMS-Client-0-10-Book.xml?rev=1743909&r1=1743908&r2=1743909&view=diff
==============================================================================
--- qpid/java/trunk/doc/jms-client-0-10/src/docbkx/JMS-Client-0-10-Book.xml (original)
+++ qpid/java/trunk/doc/jms-client-0-10/src/docbkx/JMS-Client-0-10-Book.xml Sun May 15 14:49:49
2016
@@ -378,6 +378,510 @@ destination.topicExchange = amq.topic <c
 
       <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>
 
+
+
+    <!-- begin JNDI section -->
+    <section xml:id="QpidJNDI">
+      <title>Apache Qpid JNDI Properties for AMQP Messaging</title>
+
+
+      <para>
+	Apache Qpid defines JNDI properties that can be used to specify JMS Connections and Destinations.
Here is a typical JNDI properties file:
+      </para>
+
+      <example>
+	<title>JNDI Properties File</title>
+	<programlisting>
+java.naming.factory.initial
+= org.apache.qpid.jndi.PropertiesFileInitialContextFactory
+
+# connectionfactory.[jndiname] = [ConnectionURL]
+connectionfactory.qpidConnectionfactory
+= amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'
+# destination.[jndiname] = [address_string]
+destination.topicExchange = amq.topic
+	</programlisting>
+      </example>
+
+      <para>The following sections describe the JNDI properties that Qpid uses.</para>
+
+
+      <section>
+        <title>JNDI Properties for Apache Qpid</title>
+        <para>
+	  Apache Qpid supports the properties shown in the following table:
+        </para>
+        <table>
+	  <title>JNDI Properties supported by Apache Qpid</title>
+	  <tgroup cols="2">
+	    <thead>
+	      <row>
+	        <entry>
+		  Property
+	        </entry>
+	        <entry>
+		  Purpose
+	        </entry>
+	      </row>
+	    </thead>
+	    <tbody>
+	      <row>
+	        <entry>
+		  connectionfactory.&lt;jndiname&gt;
+	        </entry>
+	        <entry>
+		  <para>
+		    The Connection URL that the connection factory uses to perform connections.
+		  </para>
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  queue.&lt;jndiname&gt;
+	        </entry>
+	        <entry>
+		  <para>
+		    A JMS queue, which is implemented as an amq.direct exchange in Apache Qpid.
+		  </para>
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  topic.&lt;jndiname&gt;
+	        </entry>
+	        <entry>
+		  <para>
+		    A JMS topic, which is implemented as an amq.topic exchange in Apache Qpid.
+		  </para>
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  destination.&lt;jndiname&gt;
+	        </entry>
+	        <entry>
+		  <para>
+		    Can be used for defining all amq destinations,
+		    queues, topics and header matching, using an
+		    address string.
+
+		    <footnote><para>Binding URLs, which were used in
+		    earlier versions of the Qpid Java JMS client, can
+		    still be used instead of address
+		    strings.</para></footnote>
+		  </para>
+	        </entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+        </table>
+      </section>
+
+      <section xml: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:
+        </para>
+
+        <programlisting>amqp://[&lt;user&gt;:&lt;pass&gt;@][&lt;clientid&gt;]&lt;virtualhost&gt;[?&lt;option&gt;='&lt;value&gt;'[&amp;&lt;option&gt;='&lt;value&gt;']]
+        </programlisting>
+        <para>
+	  For instance, the following Connection URL specifies a user name, a password, a client
ID, a virtual host ("test"), a broker list with a single broker, and a TCP host with the host
name <quote>localhost</quote> using port 5672:
+        </para>
+
+        <programlisting>amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672'
+        </programlisting>
+        <para>
+	  Apache Qpid supports the following properties in Connection URLs:
+        </para>
+        <table pgwide="1">
+	  <title>Connection URL Properties</title>
+	  <tgroup cols="3">
+	    <thead>
+	      <row>
+	        <entry>
+		  Option
+	        </entry>
+	        <entry>
+		  Type
+	        </entry>
+	        <entry>
+		  Description
+	        </entry>
+	      </row>
+	    </thead>
+	    <tbody>
+	      <row>
+	        <entry>
+		  brokerlist
+	        </entry>
+	        <entry>
+		  see below
+	        </entry>
+	        <entry>
+		  List of one or more broker addresses.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  maxprefetch
+	        </entry>
+	        <entry>
+		  integer
+	        </entry>
+	        <entry>
+		  <para>
+                    The maximum number of pre-fetched messages per consumer. If not specified,
default value of 500 is used.
+		  </para>
+		  <para>
+                    Note: You can also set the default per-consumer prefetch value on a client-wide
basis by configuring the client using <link linkend="client-jvm-properties">Java system
properties.</link>
+		  </para>
+	        </entry>
+	      </row>
+	      <row>
+	        <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>
+	      </row>
+	      <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>
+	        <entry>
+		  use_legacy_map_msg_format
+	        </entry>
+	        <entry>
+		  Boolean
+	        </entry>
+	        <entry>
+		  If you are using JMS Map messages and deploying a new client with any JMS client older
than 0.8 release, you must set this to true to ensure the older clients can understand the
map message encoding.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  failover
+	        </entry>
+	        <entry>
+		  {'singlebroker' | 'roundrobin' | 'failover_exchange' | 'nofailover' | '&lt;class&gt;'}
+	        </entry>
+	        <entry>
+		  <para>
+		    This option controls failover behaviour.  The method <literal>singlebroker</literal>
uses only the first broker in the list,
+		    <literal>roundrobin</literal> will try each broker given in the broker
list until a connection is established,
+		    <literal>failover_exchange</literal> connects to the initial broker given
in the broker URL and will receive membership updates
+		    via the failover exchange. <literal>nofailover</literal> disables all retry
and failover logic.  Any other value is interpreted as a
+		    classname which must implement the <literal>org.apache.qpid.jms.failover.FailoverMethod</literal>
interface.
+		  </para>
+		  <para>
+		    The broker list options <literal>retries</literal> and <literal>connectdelay</literal>
(described below) determine the number of times a
+		    connection to a broker will be retried and the the length of time to wait between successive
connection attempts before moving on to
+		    the next broker in the list. The failover option <literal>cyclecount</literal>
controls the number of times to loop through the list of
+		    available brokers before finally giving up.
+		  </para>
+		  <para>
+		    Defaults to <literal>roundrobin</literal> if the brokerlist contains multiple
brokers, or <literal>singlebroker</literal> otherwise.
+		  </para>
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		        ssl
+	        </entry>
+	        <entry>
+		        boolean
+	        </entry>
+	        <entry>
+	            <para>
+	                If <literal>ssl='true'</literal>, use SSL for all broker connections.
Overrides any per-broker settings in the brokerlist (see below) entries. If not specified,
the brokerlist entry for each given broker is used to determine whether SSL is used.
+	            </para>
+	            <para>
+	                Introduced in version 0.22.
+	            </para>
+	        </entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+        </table>
+        <para>
+	  Broker lists are specified using a URL in this format:
+        </para>
+
+        <programlisting>brokerlist=&lt;transport&gt;://&lt;host&gt;[:&lt;port&gt;](?&lt;param&gt;='&lt;value&gt;')(&amp;&lt;param&gt;='&lt;value&gt;')*</programlisting>
+        <para>
+	  For instance, this is a typical broker list:
+        </para>
+
+        <programlisting>brokerlist='tcp://localhost:5672'
+        </programlisting>
+
+	<para>
+	  A broker list can contain more than one broker address; if so, the connection is made
to the first broker in the list that is available. In general, it is better to use the failover
exchange when using multiple brokers, since it allows applications to fail over if a broker
goes down.
+	</para>
+
+	<example>
+	  <title>Broker Lists</title>
+	  <para>A broker list can specify properties to be used when connecting to the broker,
such as security options. This broker list specifies options for a Kerberos connection using
GSSAPI:</para>
+	  <programlisting>
+amqp://guest:guest@test/test?sync_ack='true'
+&amp;brokerlist='tcp://ip1:5672?sasl_mechs='GSSAPI''
+	  </programlisting>
+
+	  <para>This broker list specifies SSL options:</para>
+
+	  <programlisting>
+amqp://guest:guest@test/test?sync_ack='true'
+&amp;brokerlist='tcp://ip1:5672?ssl='true'&amp;ssl_cert_alias='cert1''
+	  </programlisting>
+
+	  <para>
+	    This broker list specifies two brokers using the connectdelay and retries broker options.
It also illustrates the failover connection URL
+	    property.
+	  </para>
+
+	  <programlisting>
+amqp://guest:guest@/test?failover='roundrobin?cyclecount='2''
+&amp;brokerlist='tcp://ip1:5672?retries='5'&amp;connectdelay='2000';tcp://ip2:5672?retries='5'&amp;connectdelay='2000''
+	  </programlisting>
+	</example>
+
+	<para>The following broker list options are supported.</para>
+
+        <table pgwide="1">
+	  <title>Broker List Options</title>
+	  <tgroup cols="3">
+	    <thead>
+	      <row>
+	        <entry>
+		  Option
+	        </entry>
+	        <entry>
+		  Type
+	        </entry>
+	        <entry>
+		  Description
+	        </entry>
+	      </row>
+	    </thead>
+	    <tbody>
+	      <row>
+	        <entry>
+		  heartbeat
+	        </entry>
+	        <entry>
+		  integer
+	        </entry>
+	        <entry>
+		  Frequency of heartbeat messages (in seconds). A value of 0 disables heartbeating. <para>For
compatibility
+                  with old client configuration, option <varname>idle_timeout</varname>
(in milliseconds) is also supported.</para>
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  sasl_mechs
+	        </entry>
+	        <entry>
+		  --
+	        </entry>
+	        <entry>
+		  For secure applications, we suggest CRAM-MD5,
+		  DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not
+		  secure. The PLAIN method is secure only when used
+		  together with SSL. For Kerberos, sasl_mechs must be
+		  set to GSSAPI, sasl_protocol must be set to the
+		  principal for the qpidd broker, e.g. qpidd/, and
+		  sasl_server must be set to the host for the SASL
+		  server, e.g. sasl.com.  SASL External is supported
+		  using SSL certification, e.g.
+		  <literal>ssl='true'&amp;sasl_mechs='EXTERNAL'</literal>
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  sasl_encryption
+	        </entry>
+	        <entry>
+		  Boolean
+	        </entry>
+	        <entry>
+		  If <literal>sasl_encryption='true'</literal>, the JMS client attempts to
negotiate a security layer with the broker using GSSAPI to encrypt the connection. Note that
for this to happen, GSSAPI must be selected as the sasl_mech.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  sasl_protocol
+	        </entry>
+	        <entry>
+		  --
+	        </entry>
+	        <entry>
+		  Used only for
+		  Kerberos. <literal>sasl_protocol</literal> must be
+		  set to the principal for the qpidd broker,
+		  e.g. <literal>qpidd/</literal>
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  sasl_server
+	        </entry>
+	        <entry>
+		  --
+	        </entry>
+	        <entry>
+		  For Kerberos, sasl_mechs must be set to GSSAPI,
+		  sasl_server must be set to the host for the SASL
+		  server, e.g. <literal>sasl.com</literal>.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  trust_store
+	        </entry>
+	        <entry>
+		  --
+	        </entry>
+	        <entry>
+		  path to trust store
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  trust_store_password
+	        </entry>
+	        <entry>
+		        --
+	        </entry>
+	        <entry>
+		  Trust store password
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  key_store
+	        </entry>
+	        <entry>
+		        --
+	        </entry>
+	        <entry>
+		  path to key store
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  key_store_password
+	        </entry>
+	        <entry>
+		  --
+	        </entry>
+	        <entry>
+		  key store password
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  ssl
+	        </entry>
+	        <entry>
+		  Boolean
+	        </entry>
+	        <entry>
+	            <para>If <literal>ssl='true'</literal>, the JMS client will
encrypt the connection to this broker using SSL.</para>
+
+	            <para>This can also be set/overridden for all brokers using the <link
linkend="section-jms-connection-url">Connection URL</link> options.</para>
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  ssl_verify_hostname
+	        </entry>
+	        <entry>
+		  Boolean
+	        </entry>
+	        <entry>
+		  When using SSL you can enable hostname verification
+		  by using <literal>ssl_verify_hostname='true'</literal> in the broker
+		  URL.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  ssl_cert_alias
+	        </entry>
+	        <entry>
+		        --
+	        </entry>
+	        <entry>
+		  If multiple certificates are present in the keystore, the alias will be used to extract
the correct certificate.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  retries
+	        </entry>
+	        <entry>
+		  integer
+	        </entry>
+	        <entry>
+		  The number of times to retry connection to each broker in the broker list. Defaults to
1.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  connectdelay
+	        </entry>
+	        <entry>
+		  integer
+	        </entry>
+	        <entry>
+		  Length of time (in milliseconds) to wait before attempting to reconnect. Defaults to
0.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  connecttimeout
+	        </entry>
+	        <entry>
+		  integer
+	        </entry>
+	        <entry>
+		  Length of time (in milliseconds) to wait for the socket connection to succeed. A value
of 0 represents an infinite timeout, i.e. the connection attempt will block until established
or an error occurs.  Defaults to 30000.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  tcp_nodelay
+	        </entry>
+	        <entry>
+		  Boolean
+	        </entry>
+	        <entry>
+		  If <literal>tcp_nodelay='true'</literal>, TCP packet
+		  batching is disabled. Defaults to true since Qpid 0.14.
+	        </entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</table>
+      </section>
+    </section>
+    <!-- end JNDI section -->
+
+
+
       <section xml:id="client-jvm-properties">
         <title>Qpid JVM Arguments</title>
 



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message