Tue Oct 21 18:22:06 2008
@@ -68,6 +68,26 @@
<title>Migrating Client Code</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
+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
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>
<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>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
+ 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>