qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From g...@apache.org
Subject svn commit: r961669 - /qpid/trunk/qpid/doc/book/src/Programming-In-Apache-Qpid.xml
Date Thu, 08 Jul 2010 09:31:11 GMT
Author: gsim
Date: Thu Jul  8 09:31:11 2010
New Revision: 961669

URL: http://svn.apache.org/viewvc?rev=961669&view=rev
Log:
Removed some sections not directly relevant to API; restructured a little as a consequence

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=961669&r1=961668&r2=961669&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 Jul  8 09:31:11 2010
@@ -1849,16 +1849,15 @@ sender.setCapacity(100);
 
     </section>
 
-
     <section>
-      <title>Reliability</title>
-      <para>The Qpid Messaging API supports automatic reconnect, guaranteed delivery
via persistent messages, and acknowledged message transfer. This section shows how programs
can take advantage of these features.</para>
-      <section>
-	<title>Reconnect</title>
-	<para>Connections in the Qpid Messaging API support automatic
-	reconnect if a connection is lost. This is controlled using
-	connection options. The following example shows how to use
-	connection options in C++ and Python.</para>
+      <title>Connection Options</title>
+
+      <para>
+        Aspects of the connections behaviour can be controlled through
+        specifying connection options. For example, connections can be
+        configured to automatically reconnect if the connection to a
+        broker is lost.
+      </para>
 
 	<example>
 	  <title>Specifying Connection Options in C++ and Python</title>
@@ -1902,32 +1901,71 @@ try:
   !!! SNIP !!!
   ]]></programlisting>
 
-	  <para>See the reference documentation for details on how to set
-	  these on connections for each language.</para>
+	  <para>See the reference documentation for details in each language.</para>
 	</example>
 
-	<para>The following table lists the connection options that control the reconnect
behaviour.</para>
+	<para>The following table lists the supported connection options.</para>
 
 	<table pgwide="1">
-	  <title>Reconnect Options</title>
+	  <title>Connection Options</title>
 	  <tgroup cols="3">
 	    <thead>
 	      <colspec colnum="1" colwidth="1*"/>
 	      <colspec colnum="2" colwidth="1*"/>
 	      <colspec colnum="3" colwidth="3*"/>
 	      <row>
-		<entry>option</entry>
-		<entry>value</entry>
+		<entry>option name</entry>
+		<entry>value type</entry>
 		<entry>semantics</entry>
 	      </row>
 	    </thead>
 	    <tbody>
+
+	      <row>
+		<entry>
+		  username
+		</entry>
+		<entry>
+		  string
+		</entry>
+		<entry>
+		  The username to use when authenticating to the broker.
+		</entry>
+	      </row>
+	      <row>
+		<entry>
+		  password
+		</entry>
+		<entry>
+		  string
+		</entry>
+		<entry>
+		  The password to use when authenticating to the broker.
+		</entry>
+	      </row>
+	      <row>
+		<entry>
+		  sasl-mechanism
+		</entry>
+		<entry>
+		  string
+		</entry>
+		<entry>
+		  The specific SASL mechanism to use when
+		  authenticating to the broker. In c++ only a single
+		  value can be specified at present. In python the
+		  value can be a space separated list in order of
+		  preference.
+		</entry>
+	      </row>
+
+
 	      <row>
 		<entry>
 		  reconnect
 		</entry>
 		<entry>
-		  True, False
+		  boolean
 		</entry>
 		<entry>
 		  Transparently reconnect if the connection is lost.
@@ -1938,7 +1976,7 @@ try:
 		  reconnect_timeout
 		</entry>
 		<entry>
-		  N
+		  integer
 		</entry>
 		<entry>
 		  Total number of seconds to continue reconnection attempts before giving up and raising
an exception.
@@ -1949,7 +1987,7 @@ try:
 		  reconnect_limit
 		</entry>
 		<entry>
-		  N
+		  integer
 		</entry>
 		<entry>
 		  Maximum number of reconnection attempts before giving up and raising an exception.
@@ -1960,7 +1998,7 @@ try:
 		  reconnect_interval_min
 		</entry>
 		<entry>
-		  N
+		  integer representing time in seconds
 		</entry>
 		<entry>
 		  Minimum number of seconds between reconnection attempts. The first reconnection attempt
is made immediately; if that fails, the first reconnection delay is set to the value of <literal>reconnect_interval_min</literal>;
if that attempt fails, the reconnect interval increases exponentially until a reconnection
attempt succeeds or <literal>reconnect_interval_max</literal> is reached.
@@ -1971,7 +2009,7 @@ try:
 		  reconnect_interval_max
 		</entry>
 		<entry>
-		  N
+		  integer representing time in seconds
 		</entry>
 		<entry>
 		  Maximum reconnect interval.
@@ -1982,7 +2020,7 @@ try:
 		  reconnect_interval
 		</entry>
 		<entry>
-		  N
+		  integer representing time in seconds
 		</entry>
 		<entry>
 		  Sets both <literal>reconnection_interval_min</literal> and <literal>reconnection_interval_max</literal>
to the same value.
@@ -1991,41 +2029,11 @@ try:
 	    </tbody>
 	  </tgroup>
 	</table>
-      </section>
-      <section>
-	<title>Guaranteed Delivery</title>
-
-	<para>If a queue is durable, the queue survives a messaging
-	broker crash, as well as any durable messages that have been
-	placed on the queue. These messages will be recovered for
-	delivery to subscribers when the messaging broker is
-	restarted. Guaranteed delivery requires a persistence module,
-	such as the one available
-	from <ulink url="http://QpidComponents.org">QpidComponents.org</ulink>.</para>
-
-	<example>
-	  <title>Guaranteed Delivery</title>
-
-	  <para>C++:</para>
-
-	  <programlisting><![CDATA[
-Sender sender = session.createSender("durable-queue");
-
-Message message("Hello world!");
-message.setDurable(true);
-
-sender.send(message);
-]]></programlisting>
-<!--
-	  <para>Python:</para>
--->
-	</example>
-
-      </section>
 
+    </section>
 
-      <section>
-	<title>Reliability Options in Senders and Receivers</title>
+    <section>
+      <title>Reliability</title>
 
 	<para>When creating a sender or a receiver, you can specify a reliability option in
the address string. For instance, the following specifies <literal>at-least-once</literal>
as the reliability mode for a sender:</para>
 
@@ -2108,102 +2116,6 @@ try:
 	</example>
       </section>
 
-    </section>
-
-
-    <section>
-      <title>Security</title>
-
-      <para>Qpid provides authentication, rule-based authorization, encryption, and
digital signing.</para>
-
-      <para>Authentication is done using Simple Authentication and
-      Security Layer (SASL) to authenticate client connections to the
-      broker. SASL is a framework that supports a variety of
-      authentication methods. For secure applications, we suggest
-      CRAM-MD5, DIGEST-MD5, or GSSAPI (Kerberos). The ANONYMOUS method
-      is not secure. The PLAIN method is secure only when used
-      together with SSL.</para>
-
-      <para>To enable Kerberos in a client, set the <varname>sasl-mechanism</varname>
connection option to <literal>GSSAPI</literal>:</para>
-
-
-      <programlisting>
-Connection connection(broker);
-connection.setOption("sasl-mechanism", "GSSAPI");
-try {
-    connection.open();
-    ...
-      </programlisting>
-
-      <para>For Kerberos authentication, if the user running the
-      program is already authenticated, e.g. using
-      <command>kinit</command>, there is no need to supply a user name
-      or password. If you are using another form of authentication, or are not already authenticated
with Kerberos, you can supply these as connection options:</para>
-
-      <programlisting>
-connection.setOption("username", "mick");
-connection.setOption("password", "pa$$word");
-      </programlisting>
-
-      <para>Encryption and signing are done using SSL (they can also be done using
SASL, but SSL provides stronger encryption). To enable SSL, set the <varname>protocol</varname>
connection option to <literal>ssl</literal>:</para>
-
-      <programlisting>
-connection.setOption("protocol", "ssl");
-      </programlisting>
-
-      <para>Use the following environment variables to configure the SSL client:</para>
-
-      <table>
-	<title>SSL Client Environment Variables for C++ clients</title>
-	<tgroup align="left" cols="2" colsep="1" rowsep="1">
-	  <colspec colname="c1"></colspec>
-	  <colspec colname="c2"></colspec>
-	  <thead>
-	    <row>
-	      <entry align="center" nameend="c2" namest="c1">
-		SSL Client Options for C++ clients
-	      </entry>
-	    </row>
-	  </thead>
-	  <tbody>
-	    <row>
-	      <entry>
-		<command>SSL_USE_EXPORT_POLICY</command>
-	      </entry>
-	      <entry>
-		Use NSS export policy
-	      </entry>
-	    </row>
-	    <row>
-	      <entry>
-		<command>SSL_CERT_PASSWORD_FILE <replaceable>PATH</replaceable></command>
-	      </entry>
-	      <entry>
-		File containing password to use for accessing certificate database
-	      </entry>
-	    </row>
-	    <row>
-	      <entry>
-		<command>SSL_CERT_DB <replaceable>PATH</replaceable></command>
-	      </entry>
-	      <entry>
-		Path to directory containing certificate database
-	      </entry>
-	    </row>
-	    <row>
-	      <entry>
-		<command>SSL_CERT_NAME <replaceable>NAME</replaceable></command>
-	      </entry>
-	      <entry>
-		Name of the certificate to use. When SSL client authentication is enabled, a certificate
name should normally be provided.
-	      </entry>
-	    </row>
-	  </tbody>
-	</tgroup>
-      </table>
-
-    </section>
-
     <section>
       <title>Transactions</title>
 



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


Mime
View raw message