You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zookeeper.apache.org by ph...@apache.org on 2008/09/26 20:09:26 UTC
svn commit: r699442 - in /hadoop/zookeeper/trunk: ./ docs/
src/docs/src/documentation/content/xdocs/ src/java/main/org/apache/zookeeper/
src/java/test/org/apache/zookeeper/test/
Author: phunt
Date: Fri Sep 26 11:09:25 2008
New Revision: 699442
URL: http://svn.apache.org/viewvc?rev=699442&view=rev
Log:
ZOOKEEPER-21. Improve zk ctor/watcher (state transition) docs
Modified:
hadoop/zookeeper/trunk/CHANGES.txt
hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html
hadoop/zookeeper/trunk/docs/zookeeperProgrammers.pdf
hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientCnxn.java
hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientWatchManager.java
hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/Watcher.java
hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java
hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeperMain.java
hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/AsyncTest.java
hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientBase.java
hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientTest.java
hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/WatcherTest.java
Modified: hadoop/zookeeper/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/CHANGES.txt?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/CHANGES.txt (original)
+++ hadoop/zookeeper/trunk/CHANGES.txt Fri Sep 26 11:09:25 2008
@@ -14,6 +14,8 @@
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)
Modified: hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html (original)
+++ hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html Fri Sep 26 11:09:25 2008
@@ -458,8 +458,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
- <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>
Modified: hadoop/zookeeper/trunk/docs/zookeeperProgrammers.pdf
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperProgrammers.pdf?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
Binary files - no diff available.
Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml (original)
+++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml Fri Sep 26 11:09:25 2008
@@ -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>
Modified: hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientCnxn.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientCnxn.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientCnxn.java (original)
+++ hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientCnxn.java Fri Sep 26 11:09:25 2008
@@ -45,8 +45,6 @@
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;
Modified: hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientWatchManager.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientWatchManager.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientWatchManager.java (original)
+++ hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ClientWatchManager.java Fri Sep 26 11:09:25 2008
@@ -20,9 +20,6 @@
import java.util.Set;
-import org.apache.zookeeper.Watcher.Event.EventType;
-import org.apache.zookeeper.Watcher.Event.KeeperState;
-
/**
*/
public interface ClientWatchManager {
Modified: hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/Watcher.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/Watcher.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/Watcher.java (original)
+++ hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/Watcher.java Fri Sep 26 11:09:25 2008
@@ -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
Modified: hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java (original)
+++ hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeper.java Fri Sep 26 11:09:25 2008
@@ -52,24 +52,13 @@
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 @@
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 @@
/* (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 @@
childWatches.clear();
}
}
-
+
Set<Watcher> watchers = null;
-
+
switch (type) {
case None:
result.add(defaultWatcher);
@@ -192,7 +181,7 @@
LOG.error(msg);
throw new RuntimeException(msg);
}
-
+
result.addAll(watchers);
return result;
}
@@ -268,12 +257,46 @@
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 @@
}
/**
- * 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 @@
* 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 @@
return response.getPath();
}
- /**
+ /**
* The Asynchronous version of create. The request doesn't actually until
* the asynchronous callback is called.
*
@@ -686,7 +716,7 @@
* 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
Modified: hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeperMain.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeperMain.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeperMain.java (original)
+++ hadoop/zookeeper/trunk/src/java/main/org/apache/zookeeper/ZooKeeperMain.java Fri Sep 26 11:09:25 2008
@@ -23,13 +23,12 @@
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.
Modified: hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/AsyncTest.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/AsyncTest.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/AsyncTest.java (original)
+++ hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/AsyncTest.java Fri Sep 26 11:09:25 2008
@@ -29,19 +29,18 @@
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;
Modified: hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientBase.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientBase.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientBase.java (original)
+++ hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientBase.java Fri Sep 26 11:09:25 2008
@@ -32,11 +32,10 @@
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;
Modified: hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientTest.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientTest.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientTest.java (original)
+++ hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/ClientTest.java Fri Sep 26 11:09:25 2008
@@ -29,10 +29,10 @@
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.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);
Modified: hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/WatcherTest.java
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/WatcherTest.java?rev=699442&r1=699441&r2=699442&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/WatcherTest.java (original)
+++ hadoop/zookeeper/trunk/src/java/test/org/apache/zookeeper/test/WatcherTest.java Fri Sep 26 11:09:25 2008
@@ -25,15 +25,13 @@
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 {