ZOOKEEPER-21. Improve zk ctor/watcher (state transition) docs

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

CHANGES.txt

@@ -14,6 +14,8 @@ Backward compatibile changes:
 
   BUGFIXES: 
 
+  ZOOKEEPER-21. Improve zk ctor/watcher (state transition) docs (phunt)
+
   ZOOKEEPER-142. Provide Javadoc as to the maximum size of the data byte 
   array that may be stored within a znode (Jakob Homan via phunt)
 

docs/zookeeperProgrammers.html

@@ -458,8 +458,7 @@ document.write("Last Published: " + document.lastModified);
         the watch and then clear the watch. When a watch triggers, ZooKeeper
         sends the client a notification. More information about watches can be
         found in the section 
-	<a href="recipes.html#sc_recipes_Locks">
-	Zookeeper Watches</a>.
+	    <a href="#ch_zkWatches">Zookeeper Watches</a>.
         <remark>[tbd: fix this link] [tbd: Ben there is note from to emphasize
         that "it is queued". What is "it" and is what we have here
         sufficient?]</remark>

docs/zookeeperProgrammers.pdf

@@ -368,8 +368,7 @@ endobj
 /Rect [ 293.292 191.365 388.92 179.365 ]
 /C [ 0 0 0 ]
 /Border [ 0 0 0 ]
-/A << /URI (recipes.html#sc_recipes_Locks)
-/S /URI >>
+/A 46 0 R
 /H /I
 >>
 endobj
@@ -1078,64 +1077,64 @@ endobj
 xref
 0 135
 0000000000 65535 f 
-0000046286 00000 n 
-0000046436 00000 n 
-0000046529 00000 n 
+0000046242 00000 n 
+0000046392 00000 n 
+0000046485 00000 n 
 0000000015 00000 n 
 0000000071 00000 n 
 0000001157 00000 n 
 0000001277 00000 n 
 0000001400 00000 n 
-0000046681 00000 n 
+0000046637 00000 n 
 0000001535 00000 n 
-0000046744 00000 n 
+0000046700 00000 n 
 0000001672 00000 n 
-0000046808 00000 n 
+0000046764 00000 n 
 0000001809 00000 n 
-0000046874 00000 n 
+0000046830 00000 n 
 0000001945 00000 n 
-0000046938 00000 n 
+0000046894 00000 n 
 0000002082 00000 n 
-0000047004 00000 n 
+0000046960 00000 n 
 0000002219 00000 n 
-0000047068 00000 n 
+0000047024 00000 n 
 0000002356 00000 n 
-0000047132 00000 n 
+0000047088 00000 n 
 0000002493 00000 n 
-0000047198 00000 n 
+0000047154 00000 n 
 0000002630 00000 n 
-0000047262 00000 n 
+0000047218 00000 n 
 0000002767 00000 n 
-0000047326 00000 n 
+0000047282 00000 n 
 0000002902 00000 n 
-0000047392 00000 n 
+0000047348 00000 n 
 0000003038 00000 n 
-0000047456 00000 n 
+0000047412 00000 n 
 0000003175 00000 n 
-0000047520 00000 n 
+0000047476 00000 n 
 0000003312 00000 n 
-0000047586 00000 n 
+0000047542 00000 n 
 0000003449 00000 n 
 0000006793 00000 n 
 0000006916 00000 n 
 0000007020 00000 n 
-0000047650 00000 n 
+0000047606 00000 n 
 0000007153 00000 n 
-0000047709 00000 n 
+0000047665 00000 n 
 0000007286 00000 n 
-0000047768 00000 n 
+0000047724 00000 n 
 0000007419 00000 n 
-0000047827 00000 n 
+0000047783 00000 n 
 0000007552 00000 n 
-0000047886 00000 n 
+0000047842 00000 n 
 0000007685 00000 n 
-0000047945 00000 n 
+0000047901 00000 n 
 0000007818 00000 n 
-0000048004 00000 n 
+0000047960 00000 n 
 0000007951 00000 n 
-0000048063 00000 n 
+0000048019 00000 n 
 0000008084 00000 n 
-0000048122 00000 n 
+0000048078 00000 n 
 0000008219 00000 n 
 0000008354 00000 n 
 0000008489 00000 n 
@@ -1143,75 +1142,75 @@ xref
 0000011418 00000 n 
 0000011541 00000 n 
 0000011568 00000 n 
-0000011750 00000 n 
-0000013748 00000 n 
-0000013856 00000 n 
-0000015437 00000 n 
-0000015545 00000 n 
-0000017981 00000 n 
-0000018089 00000 n 
-0000020259 00000 n 
-0000020367 00000 n 
-0000023037 00000 n 
-0000023160 00000 n 
-0000023187 00000 n 
-0000023353 00000 n 
-0000026314 00000 n 
-0000026437 00000 n 
-0000026471 00000 n 
-0000026649 00000 n 
-0000026811 00000 n 
-0000029501 00000 n 
-0000029609 00000 n 
-0000031992 00000 n 
-0000032100 00000 n 
-0000034135 00000 n 
-0000034258 00000 n 
-0000034285 00000 n 
-0000034420 00000 n 
-0000037128 00000 n 
-0000037236 00000 n 
-0000039480 00000 n 
-0000039603 00000 n 
-0000039651 00000 n 
-0000039861 00000 n 
-0000040056 00000 n 
-0000040261 00000 n 
-0000048181 00000 n 
-0000040421 00000 n 
-0000040698 00000 n 
-0000048235 00000 n 
-0000040881 00000 n 
-0000048302 00000 n 
-0000041039 00000 n 
-0000048367 00000 n 
-0000041235 00000 n 
-0000048434 00000 n 
-0000041455 00000 n 
-0000041648 00000 n 
-0000041868 00000 n 
-0000042115 00000 n 
-0000042332 00000 n 
-0000042585 00000 n 
-0000042920 00000 n 
-0000043213 00000 n 
-0000043454 00000 n 
-0000043654 00000 n 
-0000043830 00000 n 
-0000048501 00000 n 
-0000044030 00000 n 
-0000048568 00000 n 
-0000044218 00000 n 
-0000044428 00000 n 
-0000044819 00000 n 
-0000045152 00000 n 
-0000045506 00000 n 
-0000045620 00000 n 
-0000045731 00000 n 
-0000045843 00000 n 
-0000045952 00000 n 
-0000046059 00000 n 
-0000046176 00000 n 
+0000011706 00000 n 
+0000013704 00000 n 
+0000013812 00000 n 
+0000015393 00000 n 
+0000015501 00000 n 
+0000017937 00000 n 
+0000018045 00000 n 
+0000020215 00000 n 
+0000020323 00000 n 
+0000022993 00000 n 
+0000023116 00000 n 
+0000023143 00000 n 
+0000023309 00000 n 
+0000026270 00000 n 
+0000026393 00000 n 
+0000026427 00000 n 
+0000026605 00000 n 
+0000026767 00000 n 
+0000029457 00000 n 
+0000029565 00000 n 
+0000031948 00000 n 
+0000032056 00000 n 
+0000034091 00000 n 
+0000034214 00000 n 
+0000034241 00000 n 
+0000034376 00000 n 
+0000037084 00000 n 
+0000037192 00000 n 
+0000039436 00000 n 
+0000039559 00000 n 
+0000039607 00000 n 
+0000039817 00000 n 
+0000040012 00000 n 
+0000040217 00000 n 
+0000048137 00000 n 
+0000040377 00000 n 
+0000040654 00000 n 
+0000048191 00000 n 
+0000040837 00000 n 
+0000048258 00000 n 
+0000040995 00000 n 
+0000048323 00000 n 
+0000041191 00000 n 
+0000048390 00000 n 
+0000041411 00000 n 
+0000041604 00000 n 
+0000041824 00000 n 
+0000042071 00000 n 
+0000042288 00000 n 
+0000042541 00000 n 
+0000042876 00000 n 
+0000043169 00000 n 
+0000043410 00000 n 
+0000043610 00000 n 
+0000043786 00000 n 
+0000048457 00000 n 
+0000043986 00000 n 
+0000048524 00000 n 
+0000044174 00000 n 
+0000044384 00000 n 
+0000044775 00000 n 
+0000045108 00000 n 
+0000045462 00000 n 
+0000045576 00000 n 
+0000045687 00000 n 
+0000045799 00000 n 
+0000045908 00000 n 
+0000046015 00000 n 
+0000046132 00000 n 
 trailer
 <<
 /Size 135
@@ -1219,5 +1218,5 @@ trailer
 /Info 4 0 R
 >>
 startxref
-48634
+48590
 %%EOF

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

@@ -194,8 +194,7 @@
         the watch and then clear the watch. When a watch triggers, ZooKeeper
         sends the client a notification. More information about watches can be
         found in the section 
-	<ulink url="recipes.html#sc_recipes_Locks">
-	Zookeeper Watches</ulink>.
+	    <ulink url="#ch_zkWatches">Zookeeper Watches</ulink>.
         <remark>[tbd: fix this link] [tbd: Ben there is note from to emphasize
         that "it is queued". What is "it" and is what we have here
         sufficient?]</remark></para>

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

@@ -45,8 +45,6 @@ import org.apache.zookeeper.AsyncCallback.StatCallback;
 import org.apache.zookeeper.AsyncCallback.StringCallback;
 import org.apache.zookeeper.AsyncCallback.VoidCallback;
 import org.apache.zookeeper.Watcher.Event;
-import org.apache.zookeeper.Watcher.Event.EventType;
-import org.apache.zookeeper.Watcher.Event.KeeperState;
 import org.apache.zookeeper.ZooDefs.OpCode;
 import org.apache.zookeeper.ZooKeeper.States;
 import org.apache.zookeeper.ZooKeeper.WatchRegistration;

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

@@ -20,9 +20,6 @@ package org.apache.zookeeper;
 
 import java.util.Set;
 
-import org.apache.zookeeper.Watcher.Event.EventType;
-import org.apache.zookeeper.Watcher.Event.KeeperState;
-
 /**
  */
 public interface ClientWatchManager {

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

@@ -18,8 +18,6 @@
 
 package org.apache.zookeeper;
 
-import org.apache.zookeeper.proto.WatcherEvent;
-
 /**
  * This interface specifies the public interface an event handler class must
  * implement. A ZooKeeper client will get various events from the ZooKeepr

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

@@ -52,24 +52,13 @@ import org.apache.zookeeper.proto.SetDataRequest;
 import org.apache.zookeeper.proto.SetDataResponse;
 import org.apache.zookeeper.proto.SyncRequest;
 import org.apache.zookeeper.proto.SyncResponse;
-import org.apache.zookeeper.proto.WatcherEvent;
 import org.apache.zookeeper.server.DataTree;
-import org.apache.zookeeper.Watcher.Event.EventType;
-import org.apache.zookeeper.Watcher.Event.KeeperState;
 
 /**
  * This is the main class of ZooKeeper client library. To use a ZooKeeper
  * service, an application must first instantiate an object of ZooKeeper class.
  * All the iterations will be done by calling the methods of ZooKeeper class.
  * <p>
- * 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; a sessionTimeout; and an object of Watcher type.
- * <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.
- * <p>
  * Once a connection to a server is established, a session ID is assigned to the
  * client. The client will send heart beats to the server periodically to keep
  * the session valid.
@@ -109,10 +98,10 @@ public class ZooKeeper {
     private static final Logger LOG = Logger.getLogger(ZooKeeper.class);
 
     private final ZKWatchManager watchManager = new ZKWatchManager();
-    
+
     /**
      * Manage watchers & handle events generated by the ClientCnxn object.
-     * 
+     *
      * We are implementing this as a nested class of ZooKeeper so that
      * the public methods will not be exposed as part of the ZooKeeper client
      * API.
@@ -128,10 +117,10 @@ public class ZooKeeper {
         /* (non-Javadoc)
          * @see org.apache.zookeeper.ClientWatchManager#materialize(Event.KeeperState, Event.EventType, java.lang.String)
          */
-        public Set<Watcher> materialize(Watcher.Event.KeeperState state, 
+        public Set<Watcher> materialize(Watcher.Event.KeeperState state,
                                         Watcher.Event.EventType type, String path) {
             Set<Watcher> result = new HashSet<Watcher>();
-            
+
             // clear the watches if we are not connected
 
             if (state != Watcher.Event.KeeperState.SyncConnected) {
@@ -152,9 +141,9 @@ public class ZooKeeper {
                     childWatches.clear();
                 }
             }
-    
+
             Set<Watcher> watchers = null;
-    
+
             switch (type) {
             case None:
                 result.add(defaultWatcher);
@@ -192,7 +181,7 @@ public class ZooKeeper {
                 LOG.error(msg);
                 throw new RuntimeException(msg);
             }
-    
+
             result.addAll(watchers);
             return result;
         }
@@ -268,12 +257,46 @@ public class ZooKeeper {
 
     protected ClientCnxn cnxn;
 
+    /**
+     * @see ZooKeeper(String, int, Watcher, long, byte[])
+     */
     public ZooKeeper(String host, int sessionTimeout, Watcher watcher)
             throws IOException {
         watchManager.defaultWatcher = watcher;
         cnxn = new ClientCnxn(host, sessionTimeout, this, watchManager);
     }
 
+    /**
+     * 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.
+     * <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.
+     * <p>
+     * Use {@link #getSessionId} and {@link #getSessionPasswd} on an established
+     * client connection, these values must be passed as sessionId and
+     * sessionPasswd respectively if reconnecting. Otherwise, if not
+     * reconnecting, use the other constructor which does not require these
+     * parameters.
+     *
+     * @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"
+     * @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
+     * @param sessionId
+     *            specific session id to use if reconnecting
+     * @param sessionPasswd
+     *            password for this session
+     *
+     * @throws IOException
+     *             in cases of network failure
+     */
     public ZooKeeper(String host, int sessionTimeout, Watcher watcher,
             long sessionId, byte[] sessionPasswd) throws IOException {
         watchManager.defaultWatcher = watcher;
@@ -282,16 +305,23 @@ public class ZooKeeper {
     }
 
     /**
-     * The session id for this ZooKeeper client instance. The value returned
-     * is not valid until the client connects to a server and may change
-     * after a re-connect.
-     * 
+     * The session id for this ZooKeeper client instance. The value returned is
+     * not valid until the client connects to a server and may change after a
+     * re-connect.
+     *
      * @return current session id
      */
     public long getSessionId() {
         return cnxn.getSessionId();
     }
 
+    /**
+     * The session password for this ZooKeeper client instance. The value
+     * returned is not valid until the client connects to a server and may
+     * change after a re-connect.
+     *
+     * @return current session password
+     */
     public byte[] getSessionPasswd() {
         return cnxn.getSessionPasswd();
     }
@@ -363,7 +393,7 @@ public class ZooKeeper {
      * watches on the path left by exists calls, and the watches on the parent
      * of the node by getChildren calls.
      * <p>
-     * The maximum allowable size of the data array is 1 MB (1,048,576 bytes). 
+     * The maximum allowable size of the data array is 1 MB (1,048,576 bytes).
      * Arrays larger than this will cause a KeeperExecption to be thrown.
      *
      * @param path
@@ -402,7 +432,7 @@ public class ZooKeeper {
         return response.getPath();
     }
 
-	/**
+    /**
      * The Asynchronous version of create. The request doesn't actually until
      * the asynchronous callback is called.
      *
@@ -686,7 +716,7 @@ public class ZooKeeper {
      * A KeeperException with error code KeeperException.BadVersion will be
      * thrown if the given version does not match the node's version.
      * <p>
-     * The maximum allowable size of the data array is 1 MB (1,048,576 bytes). 
+     * The maximum allowable size of the data array is 1 MB (1,048,576 bytes).
      * Arrays larger than this will cause a KeeperExecption to be thrown.
      *
      * @param path

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

@@ -23,13 +23,12 @@ import java.io.InputStreamReader;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.List;
+
+import org.apache.zookeeper.AsyncCallback.DataCallback;
+import org.apache.zookeeper.ZooDefs.Ids;
 import org.apache.zookeeper.data.ACL;
 import org.apache.zookeeper.data.Id;
 import org.apache.zookeeper.data.Stat;
-import org.apache.zookeeper.proto.WatcherEvent;
-import org.apache.zookeeper.AsyncCallback.DataCallback;
-import org.apache.zookeeper.ZooDefs.Ids;
-import org.apache.zookeeper.CreateMode;
 
 /**
  * The command line client to ZooKeeper.

src/java/test/org/apache/zookeeper/test/AsyncTest.java

@@ -29,19 +29,18 @@ import java.util.concurrent.TimeUnit;
 import junit.framework.TestCase;
 
 import org.apache.log4j.Logger;
+import org.apache.zookeeper.CreateMode;
 import org.apache.zookeeper.KeeperException;
+import org.apache.zookeeper.WatchedEvent;
 import org.apache.zookeeper.Watcher;
-import org.apache.zookeeper.Watcher.Event.EventType;
-import org.apache.zookeeper.Watcher.Event.KeeperState;
 import org.apache.zookeeper.ZooKeeper;
 import org.apache.zookeeper.AsyncCallback.DataCallback;
 import org.apache.zookeeper.AsyncCallback.StringCallback;
 import org.apache.zookeeper.AsyncCallback.VoidCallback;
 import org.apache.zookeeper.KeeperException.Code;
+import org.apache.zookeeper.Watcher.Event.KeeperState;
 import org.apache.zookeeper.ZooDefs.Ids;
-import org.apache.zookeeper.CreateMode;
 import org.apache.zookeeper.data.Stat;
-import org.apache.zookeeper.WatchedEvent;
 import org.junit.After;
 import org.junit.Before;
 import org.junit.Test;

src/java/test/org/apache/zookeeper/test/ClientBase.java

@@ -32,11 +32,10 @@ import junit.framework.TestCase;
 
 import org.apache.log4j.Logger;
 import org.apache.zookeeper.KeeperException;
-import org.apache.zookeeper.Watcher.Event.EventType;
-import org.apache.zookeeper.Watcher.Event.KeeperState;
+import org.apache.zookeeper.WatchedEvent;
 import org.apache.zookeeper.Watcher;
 import org.apache.zookeeper.ZooKeeper;
-import org.apache.zookeeper.WatchedEvent;
+import org.apache.zookeeper.Watcher.Event.KeeperState;
 import org.apache.zookeeper.server.NIOServerCnxn;
 import org.apache.zookeeper.server.ServerStats;
 import org.apache.zookeeper.server.SyncRequestProcessor;

src/java/test/org/apache/zookeeper/test/ClientTest.java

@@ -29,10 +29,10 @@ import java.util.concurrent.TimeUnit;
 import org.apache.log4j.Logger;
 import org.apache.zookeeper.CreateMode;
 import org.apache.zookeeper.KeeperException;
+import org.apache.zookeeper.WatchedEvent;
 import org.apache.zookeeper.ZooKeeper;
 import org.apache.zookeeper.KeeperException.Code;
 import org.apache.zookeeper.KeeperException.InvalidACLException;
-import org.apache.zookeeper.Watcher.Event;
 import org.apache.zookeeper.Watcher.Event.EventType;
 import org.apache.zookeeper.Watcher.Event.KeeperState;
 import org.apache.zookeeper.ZooDefs.Ids;
@@ -40,8 +40,8 @@ import org.apache.zookeeper.ZooDefs.Perms;
 import org.apache.zookeeper.data.ACL;
 import org.apache.zookeeper.data.Id;
 import org.apache.zookeeper.data.Stat;
-import org.apache.zookeeper.WatchedEvent;
 import org.junit.Test;
+
 public class ClientTest extends ClientBase {
     protected static final Logger LOG = Logger.getLogger(ClientTest.class);
 

src/java/test/org/apache/zookeeper/test/WatcherTest.java

@@ -25,15 +25,13 @@ import java.util.concurrent.TimeUnit;
 import org.apache.log4j.Logger;
 import org.apache.zookeeper.CreateMode;
 import org.apache.zookeeper.KeeperException;
+import org.apache.zookeeper.WatchedEvent;
 import org.apache.zookeeper.ZooKeeper;
 import org.apache.zookeeper.AsyncCallback.StatCallback;
 import org.apache.zookeeper.AsyncCallback.VoidCallback;
 import org.apache.zookeeper.Watcher.Event;
-import org.apache.zookeeper.Watcher.Event.EventType;
-import org.apache.zookeeper.Watcher.Event.KeeperState;
 import org.apache.zookeeper.ZooDefs.Ids;
 import org.apache.zookeeper.data.Stat;
-import org.apache.zookeeper.WatchedEvent;
 import org.junit.Test;
 
 public class WatcherTest extends ClientBase {