Author: mahadev Date: Wed Jan 28 00:46:59 2009 New Revision: 738325 URL: http://svn.apache.org/viewvc?rev=738325&view=rev Log: ZOOKEEPER-253. documentation of DataWatcher state transition is misleading regarding auto watch reset on reconnect. (phunt via mahadev)
Modified: hadoop/zookeeper/trunk/CHANGES.txt hadoop/zookeeper/trunk/docs/javaExample.html hadoop/zookeeper/trunk/docs/javaExample.pdf hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/javaExample.xml Modified: hadoop/zookeeper/trunk/CHANGES.txt URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/CHANGES.txt?rev=738325&r1=738324&r2=738325&view=diff ============================================================================== --- hadoop/zookeeper/trunk/CHANGES.txt (original) +++ hadoop/zookeeper/trunk/CHANGES.txt Wed Jan 28 00:46:59 2009 @@ -120,6 +120,9 @@ ZOOKEEPER-210. Require Java 6. (phunt via breed) ZOOKEEPER-177. needed: docs for JMX (phunt via mahadev) + + ZOOKEEPER-253. documentation of DataWatcher state transition is misleading +regarding auto watch reset on reconnect. (phunt via mahadev) Release 3.0.0 - 2008-10-21 Modified: hadoop/zookeeper/trunk/docs/javaExample.html URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/javaExample.html?rev=738325&r1=738324&r2=738325&view=diff ============================================================================== --- hadoop/zookeeper/trunk/docs/javaExample.html (original) +++ hadoop/zookeeper/trunk/docs/javaExample.html Wed Jan 28 00:46:59 2009 @@ -231,11 +231,11 @@ </li> <li> -<p> a znode, by name</p> +<p>then name of a znode - the one to be watched</p> </li> <li> -<p> an executable with arguments.</p> +<p>an executable with arguments.</p> </li> </ul> </li> @@ -319,8 +319,7 @@ </p> <pre class="code"> public class Executor implements Watcher, Runnable, DataMonitor.DataMonitorListener { -... - </pre> +...</pre> <p>The <strong>Watcher</strong> interface is defined by the ZooKeeper Java API. ZooKeeper uses it to communicate back to its container. It supports only one method, <span class="codefrag command">process()</span>, and ZooKeeper uses it to communciates generic events that the main thread would be intersted in, such as the state of the ZooKeeper connection or the ZooKeeper session.The Executor @@ -516,8 +515,10 @@ // connection has changed switch (event.getState()) { case SyncConnected: - // Everything is happy. Lets kick things off - // again by checking the existence of the znode + // In this particular example we don't need to do anything + // here - watches are automatically re-registered with + // server and any watches triggered while the client was + // disconnected will be delivered (in order of course) break; case Expired: // It's all over @@ -537,9 +538,14 @@ } </pre> <p> -If the client-side ZooKeeper libraries can reestablish the communication channel to ZooKeeper, DataMonitor simply kicks -everything off again with the call to <span class="codefrag command">ZooKeeper.exists()</span>. -If it gets an event for a znode, it calls <span class="codefrag command">ZooKeeper.exists()</span> to find out what has changed. +If the client-side ZooKeeper libraries can re-establish the +communication channel (SyncConnected event) to ZooKeeper before +session expiration (Expired event) all of the session's watches will +automatically be re-established with the server (auto-reset of watches +is new in ZooKeeper 3.0.0). See <a href="zookeeperProgrammers.html#ch_zkWatches">ZooKeeper Watches</a> +in the programmer guide for more on this. A bit lower down in this +function, when DataMonitor gets an event for a znode, it calls +<span class="codefrag command">ZooKeeper.exists()</span> to find out what has changed. </p> </div> @@ -779,8 +785,10 @@ // connection has changed switch (event.getState()) { case SyncConnected: - // Everything is happy. Lets kick things off - // again by checking the existence of the znode + // In this particular example we don't need to do anything + // here - watches are automatically re-registered with + // server and any watches triggered while the client was + // disconnected will be delivered (in order of course) break; case Expired: // It's all over Modified: hadoop/zookeeper/trunk/docs/javaExample.pdf URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/javaExample.pdf?rev=738325&r1=738324&r2=738325&view=diff ============================================================================== Binary files - no diff available. Modified: hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/javaExample.xml URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/javaExample.xml?rev=738325&r1=738324&r2=738325&view=diff ============================================================================== --- hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/javaExample.xml (original) +++ hadoop/zookeeper/trunk/src/docs/src/documentation/content/xdocs/javaExample.xml Wed Jan 28 00:46:59 2009 @@ -54,8 +54,8 @@ <itemizedlist><listitem><para>It takes as parameters:</para> <itemizedlist> <listitem><para>the address of the ZooKeeper service</para></listitem> - <listitem> <para> a znode, by name</para></listitem> - <listitem><para> an executable with arguments.</para></listitem></itemizedlist></listitem> + <listitem> <para>then name of a znode - the one to be watched</para></listitem> + <listitem><para>an executable with arguments.</para></listitem></itemizedlist></listitem> <listitem><para>It fetches the data associated with the znode and starts the executable.</para></listitem> <listitem><para>If the znode changes, the client refetches the contents and restarts the executable.</para></listitem> <listitem><para>If the znode disappears, the client kills the executable.</para></listitem></itemizedlist> @@ -134,8 +134,7 @@ <programlisting> public class Executor implements Watcher, Runnable, DataMonitor.DataMonitorListener { -... - </programlisting> +...</programlisting> <para>The <emphasis role="bold">Watcher</emphasis> interface is defined by the ZooKeeper Java API. ZooKeeper uses it to communicate back to its container. It supports only one method, <command>process()</command>, and ZooKeeper uses @@ -334,8 +333,10 @@ // connection has changed switch (event.getState()) { case SyncConnected: - // Everything is happy. Lets kick things off - // again by checking the existence of the znode + // In this particular example we don't need to do anything + // here - watches are automatically re-registered with + // server and any watches triggered while the client was + // disconnected will be delivered (in order of course) break; case Expired: // It's all over @@ -355,9 +356,15 @@ } </programlisting> <para> -If the client-side ZooKeeper libraries can reestablish the communication channel to ZooKeeper, DataMonitor simply kicks -everything off again with the call to <command>ZooKeeper.exists()</command>. -If it gets an event for a znode, it calls <command>ZooKeeper.exists()</command> to find out what has changed. +If the client-side ZooKeeper libraries can re-establish the +communication channel (SyncConnected event) to ZooKeeper before +session expiration (Expired event) all of the session's watches will +automatically be re-established with the server (auto-reset of watches +is new in ZooKeeper 3.0.0). See <ulink +url="zookeeperProgrammers.html#ch_zkWatches">ZooKeeper Watches</ulink> +in the programmer guide for more on this. A bit lower down in this +function, when DataMonitor gets an event for a znode, it calls +<command>ZooKeeper.exists()</command> to find out what has changed. </para> </section> @@ -586,8 +593,10 @@ // connection has changed switch (event.getState()) { case SyncConnected: - // Everything is happy. Lets kick things off - // again by checking the existence of the znode + // In this particular example we don't need to do anything + // here - watches are automatically re-registered with + // server and any watches triggered while the client was + // disconnected will be delivered (in order of course) break; case Expired: // It's all over