ZOOKEEPER-269. connectionloss- add more documentation to detail. (phunt and flavio via mahadev)

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

CHANGES.txt

@@ -128,6 +128,9 @@ IMPROVEMENTS:
    ZOOKEEPER-253. documentation of DataWatcher state transition is misleading
 regarding auto watch reset on reconnect. (phunt via mahadev)
 
+   ZOOKEEPER-269. connectionloss- add more documentation to detail. (phunt and
+flavio via mahadev)
+
 Release 3.0.0 - 2008-10-21
 
 Non-backward compatible changes:

docs/zookeeperProgrammers.html

@@ -780,10 +780,31 @@ document.write("Last Published: " + document.lastModified);
     still active. The timing of the PING is conservative enough to
     ensure reasonable time to detect a dead connection and reconnect
     to a new server.</p>
+<p>
+      Once a connection to the server is successfully established
+      (connected) there are basically two cases where the client lib generates
+      connectionloss (the result code in c binding, exception in Java -- see 
+      the API documentation for binding specific details) when either a synchronous or
+      asynchronous operation is performed and one of the following holds:
+    </p>
+<ol>
+      
+<li>
+<p>The application calls an operation on a session that is no
+      longer alive/valid</p>
+</li>
+      
+<li>
+<p>The ZooKeeper client disconnects from a server when there
+      are pending operations to that server, i.e., there is a pending asynchronous call.
+      </p>
+</li>
+    
+</ol>
 </div>
 
   
-<a name="N101BB"></a><a name="ch_zkWatches"></a>
+<a name="N101C9"></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
@@ -860,7 +881,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="N101F1"></a><a name="sc_WatchGuarantees"></a>
+<a name="N101FF"></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>
@@ -895,7 +916,7 @@ document.write("Last Published: " + document.lastModified);
 </li>
       
 </ul>
-<a name="N10216"></a><a name="sc_WatchRememberThese"></a>
+<a name="N10224"></a><a name="sc_WatchRememberThese"></a>
 <h3 class="h4">Things to Remember about Watches</h3>
 <ul>
         
@@ -954,7 +975,7 @@ document.write("Last Published: " + document.lastModified);
 </div>
 
   
-<a name="N10242"></a><a name="sc_ZooKeeperAccessControl"></a>
+<a name="N10250"></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
@@ -983,7 +1004,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="N10269"></a><a name="sc_ACLPermissions"></a>
+<a name="N10277"></a><a name="sc_ACLPermissions"></a>
 <h3 class="h4">ACL Permissions</h3>
 <p>ZooKeeper supports the following permissions:</p>
 <ul>
@@ -1039,7 +1060,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="N102BF"></a><a name="sc_BuiltinACLSchemes"></a>
+<a name="N102CD"></a><a name="sc_BuiltinACLSchemes"></a>
 <h4>Builtin ACL Schemes</h4>
 <p>ZooKeeeper has the following built in schemes:</p>
 <ul>
@@ -1100,7 +1121,7 @@ document.write("Last Published: " + document.lastModified);
 
       
 </ul>
-<a name="N10315"></a><a name="ZooKeeper+C+client+API"></a>
+<a name="N10323"></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>
@@ -1322,7 +1343,7 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N1042C"></a><a name="ch_zkGuarantees"></a>
+<a name="N1043A"></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
@@ -1448,12 +1469,12 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N10493"></a><a name="ch_bindings"></a>
+<a name="N104A1"></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="N1049C"></a><a name="Java+Binding"></a>
+<a name="N104AA"></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
@@ -1520,7 +1541,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="N104E5"></a><a name="C+Binding"></a>
+<a name="N104F3"></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
@@ -1537,7 +1558,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="N104F4"></a><a name="Installation"></a>
+<a name="N10502"></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
@@ -1668,7 +1689,7 @@ int main(int argc, char argv) {
 </li>
         
 </ol>
-<a name="N1059D"></a><a name="Using+the+C+Client"></a>
+<a name="N105AB"></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
@@ -1726,7 +1747,7 @@ int main(int argc, char argv) {
 </div>
 
    
-<a name="N105E3"></a><a name="ch_guideToZkOperations"></a>
+<a name="N105F1"></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
@@ -1744,28 +1765,28 @@ int main(int argc, char argv) {
 </li>
     
 </ul>
-<a name="N105F7"></a><a name="sc_errorsZk"></a>
+<a name="N10605"></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="N10601"></a><a name="sc_connectingToZk"></a>
+<a name="N1060F"></a><a name="sc_connectingToZk"></a>
 <h3 class="h4">Connecting to ZooKeeper</h3>
 <p></p>
-<a name="N1060A"></a><a name="sc_readOps"></a>
+<a name="N10618"></a><a name="sc_readOps"></a>
 <h3 class="h4">Read Operations</h3>
 <p></p>
-<a name="N10613"></a><a name="sc_writeOps"></a>
+<a name="N10621"></a><a name="sc_writeOps"></a>
 <h3 class="h4">Write Operations</h3>
 <p></p>
-<a name="N1061C"></a><a name="sc_handlingWatches"></a>
+<a name="N1062A"></a><a name="sc_handlingWatches"></a>
 <h3 class="h4">Handling Watches</h3>
 <p></p>
-<a name="N10625"></a><a name="sc_miscOps"></a>
+<a name="N10633"></a><a name="sc_miscOps"></a>
 <h3 class="h4">Miscelleaneous ZooKeeper Operations</h3>
 <p></p>
 </div>
 
   
-<a name="N1062F"></a><a name="ch_programStructureWithExample"></a>
+<a name="N1063D"></a><a name="ch_programStructureWithExample"></a>
 <h2 class="h3">Program Structure, with Simple Example</h2>
 <div class="section">
 <p>
@@ -1774,7 +1795,7 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N1063A"></a><a name="ch_gotchas"></a>
+<a name="N10648"></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/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml

@@ -406,6 +406,23 @@
     still active. The timing of the PING is conservative enough to
     ensure reasonable time to detect a dead connection and reconnect
     to a new server.</para>
+
+    <para>
+      Once a connection to the server is successfully established
+      (connected) there are basically two cases where the client lib generates
+      connectionloss (the result code in c binding, exception in Java -- see 
+      the API documentation for binding specific details) when either a synchronous or
+      asynchronous operation is performed and one of the following holds:
+    </para>
+
+    <orderedlist>
+      <listitem><para>The application calls an operation on a session that is no
+      longer alive/valid</para></listitem>
+      <listitem><para>The ZooKeeper client disconnects from a server when there
+      are pending operations to that server, i.e., there is a pending asynchronous call.
+      </para></listitem>
+    </orderedlist>
+
   </section>
 
   <section id="ch_zkWatches">