Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/releasenotes.xml URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/releasenotes.xml?rev=706834&r1=706833&r2=706834&view=diff ============================================================================== --- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/releasenotes.xml (original) +++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/releasenotes.xml Tue Oct 21 18:22:06 2008 @@ -68,6 +68,26 @@ <title>Migrating Client Code</title> <section> +<title>Watch Management</title> + +<para> +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. +</para> + +<para> +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 registered. +</para> +</section> + +<section> <title>Java API</title> <orderedlist>
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=706834&r1=706833&r2=706834&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 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 @@ <itemizedlist> <listitem> + <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> </listitem> </itemizedlist> </section> @@ -1080,13 +1095,10 @@ <orderedlist> <listitem> <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> </listitem> <listitem>