ZOOKEEPER-263. document connection host:port as comma separated list in forrest

docs (pat via breed)


git-svn-id: https://svn.apache.org/repos/asf/hadoop/zookeeper/trunk@738317 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -72,6 +72,8 @@ and runping via mahadev)
   ZOOKEEPER-268.  tostring on jute generated objects can cause NPE. (pat via mahadev)
 
   ZOOKEEPER-267.  java client incorrectly generating syncdisconnected event when in disconnected state. (pat via breed)
+
+  ZOOKEEPER-263. document connection host:port as comma separated list in forrest docs (pat via breed)
  
 IMPROVEMENTS:
    

docs/zookeeperProgrammers.html

@@ -733,6 +733,15 @@ document.write("Last Published: " + document.lastModified);
 <a name="N101A5"></a><a name="ch_zkSessions"></a>
 <h2 class="h3">ZooKeeper Sessions</h2>
 <div class="section">
+<p>To create a client session the application code must provide
+    a string containing a comma separated list of host:port pairs,
+    each corresponding to a ZooKeeper server (e.g. "127.0.0.1:4545" or
+    "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"). The ZooKeeper
+    client library will pick an arbitrary server and try to connect to
+    it. If this connection fails, or if the client becomes
+    disconnected from the server for any reason, the client will
+    automatically try the next server in the list, until a connection
+    is (re-)established.</p>
 <p>When a client gets a handle to the ZooKeeper service,
     ZooKeeper creates a ZooKeeper session, represented as a 64-bit
     number, that it assigns to the client. If the client connects to a
@@ -771,7 +780,7 @@ document.write("Last Published: " + document.lastModified);
 </div>
 
   
-<a name="N101B8"></a><a name="ch_zkWatches"></a>
+<a name="N101BB"></a><a name="ch_zkWatches"></a>
 <h2 class="h3">ZooKeeper Watches</h2>
 <div class="section">
 <p>All of the read operations in ZooKeeper - <strong>getData()</strong>, <strong>getChildren()</strong>, and <strong>exists()</strong> - have the option of setting a watch as a
@@ -848,7 +857,7 @@ document.write("Last Published: " + document.lastModified);
     general this all occurs transparently. There is one case where a watch
     may be missed: a watch for the existance of a znode not yet created will
     be missed if the znode is created and deleted while disconnected.</p>
-<a name="N101EE"></a><a name="sc_WatchGuarantees"></a>
+<a name="N101F1"></a><a name="sc_WatchGuarantees"></a>
 <h3 class="h4">What ZooKeeper Guarantees about Watches</h3>
 <p>With regard to watches, ZooKeeper maintains these
       guarantees:</p>
@@ -883,7 +892,7 @@ document.write("Last Published: " + document.lastModified);
 </li>
       
 </ul>
-<a name="N10213"></a><a name="sc_WatchRememberThese"></a>
+<a name="N10216"></a><a name="sc_WatchRememberThese"></a>
 <h3 class="h4">Things to Remember about Watches</h3>
 <ul>
         
@@ -942,7 +951,7 @@ document.write("Last Published: " + document.lastModified);
 </div>
 
   
-<a name="N1023F"></a><a name="sc_ZooKeeperAccessControl"></a>
+<a name="N10242"></a><a name="sc_ZooKeeperAccessControl"></a>
 <h2 class="h3">ZooKeeper access control using ACLs</h2>
 <div class="section">
 <p>ZooKeeper uses ACLs to control access to its znodes (the
@@ -971,7 +980,7 @@ document.write("Last Published: " + document.lastModified);
     example, the pair <em>(ip:19.22.0.0/16, READ)</em>
     gives the <em>READ</em> permission to any clients with
     an IP address that starts with 19.22.</p>
-<a name="N10266"></a><a name="sc_ACLPermissions"></a>
+<a name="N10269"></a><a name="sc_ACLPermissions"></a>
 <h3 class="h4">ACL Permissions</h3>
 <p>ZooKeeper supports the following permissions:</p>
 <ul>
@@ -1027,7 +1036,7 @@ document.write("Last Published: " + document.lastModified);
       node, but nothing more. (The problem is, if you want to call
       zoo_exists() on a node that doesn't exist, there is no
       permission to check.)</p>
-<a name="N102BC"></a><a name="sc_BuiltinACLSchemes"></a>
+<a name="N102BF"></a><a name="sc_BuiltinACLSchemes"></a>
 <h4>Builtin ACL Schemes</h4>
 <p>ZooKeeeper has the following built in schemes:</p>
 <ul>
@@ -1088,7 +1097,7 @@ document.write("Last Published: " + document.lastModified);
 
       
 </ul>
-<a name="N10312"></a><a name="ZooKeeper+C+client+API"></a>
+<a name="N10315"></a><a name="ZooKeeper+C+client+API"></a>
 <h4>ZooKeeper C client API</h4>
 <p>The following constants are provided by the ZooKeeper C
       library:</p>
@@ -1310,7 +1319,7 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N10429"></a><a name="ch_zkGuarantees"></a>
+<a name="N1042C"></a><a name="ch_zkGuarantees"></a>
 <h2 class="h3">Consistency Guarantees</h2>
 <div class="section">
 <p>ZooKeeper is a high performance, scalable service. Both reads and
@@ -1436,12 +1445,12 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N10490"></a><a name="ch_bindings"></a>
+<a name="N10493"></a><a name="ch_bindings"></a>
 <h2 class="h3">Bindings</h2>
 <div class="section">
 <p>The ZooKeeper client libraries come in two languages: Java and C.
     The following sections describe these.</p>
-<a name="N10499"></a><a name="Java+Binding"></a>
+<a name="N1049C"></a><a name="Java+Binding"></a>
 <h3 class="h4">Java Binding</h3>
 <p>There are two packages that make up the ZooKeeper Java binding:
       <strong>org.apache.zookeeper</strong> and <strong>org.apache.zookeeper.data</strong>. The rest of the
@@ -1508,7 +1517,7 @@ int main(int argc, char argv) {
       (SESSION_EXPIRED and AUTH_FAILED), the ZooKeeper object becomes invalid,
       the two threads shut down, and any further ZooKeeper calls throw
       errors.</p>
-<a name="N104E2"></a><a name="C+Binding"></a>
+<a name="N104E5"></a><a name="C+Binding"></a>
 <h3 class="h4">C Binding</h3>
 <p>The C binding has a single-threaded and multi-threaded library.
       The multi-threaded library is easiest to use and is most similar to the
@@ -1525,7 +1534,7 @@ int main(int argc, char argv) {
       (i.e. FreeBSD 4.x). In all other cases, application developers should
       link with zookeeper_mt, as it includes support for both Sync and Async
       API.</p>
-<a name="N104F1"></a><a name="Installation"></a>
+<a name="N104F4"></a><a name="Installation"></a>
 <h4>Installation</h4>
 <p>If you're building the client from a check-out from the Apache
         repository, follow the steps outlined below. If you're building from a
@@ -1656,7 +1665,7 @@ int main(int argc, char argv) {
 </li>
         
 </ol>
-<a name="N1059A"></a><a name="Using+the+C+Client"></a>
+<a name="N1059D"></a><a name="Using+the+C+Client"></a>
 <h4>Using the C Client</h4>
 <p>You can test your client by running a ZooKeeper server (see
         instructions on the project wiki page on how to run it) and connecting
@@ -1714,7 +1723,7 @@ int main(int argc, char argv) {
 </div>
 
    
-<a name="N105E0"></a><a name="ch_guideToZkOperations"></a>
+<a name="N105E3"></a><a name="ch_guideToZkOperations"></a>
 <h2 class="h3">Building Blocks: A Guide to ZooKeeper Operations</h2>
 <div class="section">
 <p>This section surveys all the operations a developer can perform
@@ -1732,28 +1741,28 @@ int main(int argc, char argv) {
 </li>
     
 </ul>
-<a name="N105F4"></a><a name="sc_errorsZk"></a>
+<a name="N105F7"></a><a name="sc_errorsZk"></a>
 <h3 class="h4">Handling Errors</h3>
 <p>Both the Java and C client bindings may report errors. The Java client binding does so by throwing KeeperException, calling code() on the exception will return the specific error code. The C client binding returns an error code as defined in the enum ZOO_ERRORS. API callbacks indicate result code for both language bindings. See the API documentation (javadoc for Java, doxygen for C) for full details on the possible errors and their meaning.</p>
-<a name="N105FE"></a><a name="sc_connectingToZk"></a>
+<a name="N10601"></a><a name="sc_connectingToZk"></a>
 <h3 class="h4">Connecting to ZooKeeper</h3>
 <p></p>
-<a name="N10607"></a><a name="sc_readOps"></a>
+<a name="N1060A"></a><a name="sc_readOps"></a>
 <h3 class="h4">Read Operations</h3>
 <p></p>
-<a name="N10610"></a><a name="sc_writeOps"></a>
+<a name="N10613"></a><a name="sc_writeOps"></a>
 <h3 class="h4">Write Operations</h3>
 <p></p>
-<a name="N10619"></a><a name="sc_handlingWatches"></a>
+<a name="N1061C"></a><a name="sc_handlingWatches"></a>
 <h3 class="h4">Handling Watches</h3>
 <p></p>
-<a name="N10622"></a><a name="sc_miscOps"></a>
+<a name="N10625"></a><a name="sc_miscOps"></a>
 <h3 class="h4">Miscelleaneous ZooKeeper Operations</h3>
 <p></p>
 </div>
 
   
-<a name="N1062C"></a><a name="ch_programStructureWithExample"></a>
+<a name="N1062F"></a><a name="ch_programStructureWithExample"></a>
 <h2 class="h3">Program Structure, with Simple Example</h2>
 <div class="section">
 <p>
@@ -1762,7 +1771,7 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N10637"></a><a name="ch_gotchas"></a>
+<a name="N1063A"></a><a name="ch_gotchas"></a>
 <h2 class="h3">Gotchas: Common Problems and Troubleshooting</h2>
 <div class="section">
 <p>So now you know ZooKeeper. It's fast, simple, your application

src/c/include/zookeeper.h

@@ -280,8 +280,8 @@ typedef void (*watcher_fn)(zhandle_t *zh, int type,
  * to that handle. Session establishment is asynchronous, meaning that the
  * session should not be considered established until (and unless) an
  * event of state ZOO_CONNECTED_STATE is received.
- * \param host the host name to connect to. This may be a comma separated list
- *   of different hosts.
+ * \param host comma separated host:port pairs, each corresponding to a zk
+ *   server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
  * \param fn the global watcher callback function. When notifications are
  *   triggered this function will be invoked.
  * \param clientid the id of a previously established session that this

src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml

@@ -358,6 +358,16 @@
   <section id="ch_zkSessions">
     <title>ZooKeeper Sessions</title>
 
+    <para>To create a client session the application code must provide
+    a string containing a comma separated list of host:port pairs,
+    each corresponding to a ZooKeeper server (e.g. "127.0.0.1:4545" or
+    "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"). The ZooKeeper
+    client library will pick an arbitrary server and try to connect to
+    it. If this connection fails, or if the client becomes
+    disconnected from the server for any reason, the client will
+    automatically try the next server in the list, until a connection
+    is (re-)established.</para>
+
     <para>When a client gets a handle to the ZooKeeper service,
     ZooKeeper creates a ZooKeeper session, represented as a 64-bit
     number, that it assigns to the client. If the client connects to a

src/java/main/org/apache/zookeeper/ZooKeeper.java

@@ -317,7 +317,24 @@ public class ZooKeeper {
     protected final ClientCnxn cnxn;
 
     /**
-     * @see ZooKeeper(String, int, Watcher, long, byte[])
+     * To create a client(ZooKeeper) object, the application needs to pass a
+     * string containing a comma separated list of host:port pairs, each 
+     * corresponding to a ZooKeeper server.
+     * <p>
+     * The client object will pick an arbitrary server and try to connect to it.
+     * If failed, it will try the next one in the list, until a connection is
+     * established, or all the servers have been tried.
+     *
+     * @param host
+     *            comma separated host:port pairs, each corresponding to a zk
+     *            server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
+     * @param sessionTimeout
+     *            session timeout in milliseconds
+     * @param watcher
+     *            a watcher object which will be notified of state changes, may
+     *            also be notified for node events
+     *
+     * @throws IOException in cases of network failure
      */
     public ZooKeeper(String host, int sessionTimeout, Watcher watcher)
             throws IOException {
@@ -330,8 +347,8 @@ public class ZooKeeper {
 
     /**
      * To create a client(ZooKeeper) object, the application needs to pass a
-     * string containing a list of host:port pairs, each corresponding to a
-     * ZooKeeper server.
+     * string containing a comma separated list of host:port pairs, each
+     * corresponding to a ZooKeeper server.
      * <p>
      * The client object will pick an arbitrary server and try to connect to it.
      * If failed, it will try the next one in the list, until a connection is
@@ -345,7 +362,7 @@ public class ZooKeeper {
      *
      * @param host
      *            comma separated host:port pairs, each corresponding to a zk
-     *            server. eg. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
+     *            server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"
      * @param sessionTimeout
      *            session timeout in milliseconds
      * @param watcher
@@ -356,8 +373,7 @@ public class ZooKeeper {
      * @param sessionPasswd
      *            password for this session
      *
-     * @throws IOException
-     *             in cases of network failure
+     * @throws IOException in cases of network failure
      */
     public ZooKeeper(String host, int sessionTimeout, Watcher watcher,
             long sessionId, byte[] sessionPasswd) throws IOException {