Tue Oct 21 18:22:06 2008
@@ -68,6 +68,26 @@
 <title>Migrating Client Code</title>
+<title>Watch Management</title>
+In previous releases of ZooKeeper any watches registered by clients were lost 
if the client lost a connection to a ZooKeeper server.
+This meant that developers had to track watches they were interested in and 
reregister them if a session disconnect event was recieved.
+In this release the client library tracks watches that a client has registered 
and reregisters the watches when a connection is made to a new server.
+Applications that still manually reregister interest should continue working 
properly as long as they are able to handle unsolicited watches.
+For example, an old application may register a watch for /foo and /goo, lose 
the connection, and reregister only /goo.
+As long as the application is able to recieve a notification for /foo, 
(probably ignoring it) the applications does not to be changes.
+One caveat to the watch management: it is possible to miss an event for the 
creation and deletion of a znode if watching for creation and both the create 
and delete happens while the client is disconnected from ZooKeeper.
+This release also allows clients to specify call specific watch functions.
+This gives the developer the ability to modularize logic in different watch 
functions rather than cramming everything in the watch function attached to the 
ZooKeeper handle.
+Call specific watch functions receive all session events for as long as they 
are active, but will only receive the watch callbacks for which they are 
 <title>Java API</title>

 Tue Oct 21 18:22:06 2008
@@ -433,11 +433,13 @@
     <para>Watches are maintained locally at the ZooKeeper server to which the
     client is connected. This allows watches to be light weight to set,
-    maintain, and dispatch. It also means if a client connects to a different
-    server, the new server is not going to know about its watches. So, when a
-    client gets a disconnect event, it must consider that an implicit trigger
-    of all watches. When a client reconnects to a new server, the client
-    should re-set any watches that it is still interested in.</para>
+    maintain, and dispatch. When a client connects to a new server, the watch
+    will be triggered for any session events. Watches will not be received
+    while disconnected from a server. When a client reconnects, any previously
+    registered watches will be reregistered and triggered if needed. In
+    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.</para>
     <section id="sc_WatchGuarantees">
       <title>What ZooKeeper Guarantees about Watches</title>
@@ -493,10 +495,23 @@
+          <para>A watch object, or function/context pair, will only be
+          triggered once for a given notification. For example, if the same
+          watch object is registered for an exists and a getData call for the
+          same file and that file is then deleted, the watch object would
+          only be invoked once with the deletion notification for the file.
+          </para>
+        </listitem>
+      </itemizedlist>
+      <itemizedlist>
+        <listitem>
           <para>When you disconnect from a server (for example, when the
-          server fails), all of the watches you have registered are lost, so
-          you should treat this case as if all your watches were
-          triggered.</para>
+          server fails), you will not get any watches until the connection
+          is reestablished. For this reason session events are sent to all
+          outstanding watch handlers. Use session events to go into a safe
+          mode: you will not be receiving events while disconnected, so your
+          process should act conservatively in that mode.</para>
@@ -1080,13 +1095,10 @@
         <para>If you are using watches, you must look for the connected watch
-        event. When a ZooKeeper client disconnects from a server, all the
-        watches are removed, so a client must treat the disconnect event as an
-        implicit trigger of watches. The easiest way to deal with this is to
-        act like the connected watch event is a watch trigger for all your
-        watches. The connected event makes a better trigger than the
-        disconnected event because you can access ZooKeeper and reestablish
-        watches when you are connected.</para>
+        event. When a ZooKeeper client disconnects from a server, you will
+        not receive notification of changes until reconnected. If you are
+        watching for a znode to come into existance, you will miss the event
+        if the znode is created and deleted while you are disconnected.</para>

Reply via email to