Return-Path: 
 <commits-return-15995-apmail-qpid-commits-archive=qpid.apache.org@qpid.apache.org>
X-Original-To: apmail-qpid-commits-archive@www.apache.org
Delivered-To: apmail-qpid-commits-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id 0605E7A16
	for <apmail-qpid-commits-archive@www.apache.org>;
 Thu,  1 Dec 2011 22:33:11 +0000 (UTC)
Received: (qmail 7756 invoked by uid 500); 1 Dec 2011 22:33:10 -0000
Delivered-To: apmail-qpid-commits-archive@qpid.apache.org
Received: (qmail 7736 invoked by uid 500); 1 Dec 2011 22:33:10 -0000
Mailing-List: contact commits-help@qpid.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:commits-help@qpid.apache.org>
List-Unsubscribe: <mailto:commits-unsubscribe@qpid.apache.org>
List-Post: <mailto:commits@qpid.apache.org>
List-Id: <commits.qpid.apache.org>
Reply-To: dev@qpid.apache.org
Delivered-To: mailing list commits@qpid.apache.org
Received: (qmail 7729 invoked by uid 99); 1 Dec 2011 22:33:10 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 01 Dec 2011 22:33:10 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=5.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 01 Dec 2011 22:33:09 +0000
Received: from eris.apache.org (localhost [127.0.0.1])
	by eris.apache.org (Postfix) with ESMTP id 44D5E23888FD
	for <commits@qpid.apache.org>; Thu,  1 Dec 2011 22:32:49 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1209282 -
 /qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
Date: Thu, 01 Dec 2011 22:32:49 -0000
To: commits@qpid.apache.org
From: kwall@apache.org
X-Mailer: svnmailer-1.0.8-patched
Message-Id: <20111201223249.44D5E23888FD@eris.apache.org>

Author: kwall
Date: Thu Dec  1 22:32:47 2011
New Revision: 1209282

URL: http://svn.apache.org/viewvc?rev=1209282&view=rev
Log:
QPID-3631: Document missing broker properties

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=1209282&r1=1209281&r2=1209282&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 Thu Dec  1 22:32:47 2011
@@ -3009,7 +3009,7 @@ destination.topicExchange = amq.topic
 		  see below
 	        </entry>
 	        <entry>
-		  The broker to use for this connection. In the current release, precisely one broker must be specified.
+		  List of one or more broker addresses.
 	        </entry>
 	      </row>
 	      <row>
@@ -3061,11 +3061,25 @@ destination.topicExchange = amq.topic
 		  failover
 	        </entry>
 	        <entry>
-           {'roundrobin' | 'failover_exchange'}
+           {'singlebroker' | 'roundrobin' | 'failover_exchange' | 'nofailover' | '&lt;class&gt;'}
 	        </entry>
 	        <entry>
-          If roundrobin is selected it will try each broker given in the broker list.
-          If failover_exchange is selected it connects to the initial broker given in the broker URL and will receive membership updates via the failover exchange.
+	            <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>
 	    </tbody>
@@ -3075,7 +3089,7 @@ destination.topicExchange = amq.topic
 	  Broker lists are specified using a URL in this format:
         </para>
 
-        <programlisting>brokerlist=&lt;transport&gt;://&lt;host&gt;[:&lt;port&gt;](?&lt;param>=&lt;value>)?(&amp;&lt;param>=&lt;value>)*</programlisting>
+        <programlisting>brokerlist=&lt;transport&gt;://&lt;host&gt;[:&lt;port&gt;](?&lt;param>='&lt;value>')(&amp;&lt;param>='&lt;value>')*</programlisting>
         <para>
 	  For instance, this is a typical broker list:
         </para>
@@ -3092,14 +3106,25 @@ destination.topicExchange = amq.topic
 	<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><![CDATA[
 amqp://guest:guest@test/test?sync_ack='true'
-    &brokerlist='tcp://ip1:5672?sasl_mechs='GSSAPI'
+    &brokerlist='tcp://ip1:5672?sasl_mechs='GSSAPI''
 	]]></programlisting>
 
 	<para>This broker list specifies SSL options:</para>
 
 	<programlisting><![CDATA[
 amqp://guest:guest@test/test?sync_ack='true'
-   &brokerlist='tcp://ip1:5672?ssl='true'&ssl_cert_alias='cert1'
+   &brokerlist='tcp://ip1:5672?ssl='true'&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><![CDATA[
+
+amqp://guest:guest@/test?failover='roundrobin?cyclecount='2''
+   &brokerlist='tcp://ip1:5672?retries='5'&connectdelay='2000';tcp://ip2:5672?retries='5'&connectdelay='2000''
 	]]></programlisting>
 	</example>
 
@@ -3166,29 +3191,6 @@ amqp://guest:guest@test/test?sync_ack='t
 	      </row>
 	      <row>
 	        <entry>
-		  ssl
-	        </entry>
-	        <entry>
-		  Boolean
-	        </entry>
-	        <entry>
-		  If <literal>ssl='true'</literal>, the JMS client will encrypt the connection using SSL.
-	        </entry>
-	      </row>
-	      <row>
-	        <entry>
-		  tcp_nodelay
-	        </entry>
-	        <entry>
-		  Boolean
-	        </entry>
-	        <entry>
-		  If <literal>tcp_nodelay='true'</literal>, TCP packet
-		  batching is disabled.
-	        </entry>
-	      </row>
-	      <row>
-	        <entry>
 		  sasl_protocol
 	        </entry>
 	        <entry>
@@ -3222,7 +3224,7 @@ amqp://guest:guest@test/test?sync_ack='t
 		  --
 	        </entry>
 	        <entry>
-		  path to Keberos trust store
+		  path to trust store
 	        </entry>
 	      </row>
 	      <row>
@@ -3232,7 +3234,7 @@ amqp://guest:guest@test/test?sync_ack='t
 	        <entry>
 	        </entry>
 	        <entry>
-		  Kerberos trust store password
+		  Trust store password
 	        </entry>
 	      </row>
 	      <row>
@@ -3242,7 +3244,7 @@ amqp://guest:guest@test/test?sync_ack='t
 	        <entry>
 	        </entry>
 	        <entry>
-		  path to Kerberos key store
+		  path to key store
 	        </entry>
 	      </row>
 	      <row>
@@ -3253,7 +3255,18 @@ amqp://guest:guest@test/test?sync_ack='t
 		  --
 	        </entry>
 	        <entry>
-		  Kerberos key store password
+		  key store password
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  ssl
+	        </entry>
+	        <entry>
+		  Boolean
+	        </entry>
+	        <entry>
+		  If <literal>ssl='true'</literal>, the JMS client will encrypt the connection using SSL.
 	        </entry>
 	      </row>
 	      <row>
@@ -3265,7 +3278,7 @@ amqp://guest:guest@test/test?sync_ack='t
 	        </entry>
 	        <entry>
 		  When using SSL you can enable hostname verification
-		  by using "ssl_verify_hostname=true" in the broker
+		  by using <literal>ssl_verify_hostname='true'</literal> in the broker
 		  URL.
 	        </entry>
 	      </row>
@@ -3280,6 +3293,51 @@ amqp://guest:guest@test/test?sync_ack='t
           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 to wait before attempting to reconnect (in milliseconds). Defaults to 0.
+	        </entry>
+	      </row>
+	      <row>
+	        <entry>
+		  connecttimeout
+	        </entry>
+	        <entry>
+		  integer
+	        </entry>
+	        <entry>
+		  Length of time to wait for the connection to succeed (in milliseconds).  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.
+	        </entry>
+	      </row>
 	    </tbody>
 	  </tgroup>
 	</table>
@@ -3367,10 +3425,7 @@ import javax.jms.MapMessage;
 import javax.jms.MessageProducer;
 import javax.jms.Session;
 
-import org.apache.qpid.client.AMQAnyDestination;
-import org.apache.qpid.client.AMQConnection;
-
-import edu.emory.mathcs.backport.java.util.Arrays;
+import java.util.Arrays;
 
 // !!! SNIP !!!
 



---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org