Author: mahadev
Date: Thu Jun 25 22:42:42 2009
New Revision: 788539
URL: http://svn.apache.org/viewvc?rev=788539&view=rev
Log:
ZOOKEEPER-264. docs should include a state transition diagram for client state
(breed via mahadev)
Added:
hadoop/zookeeper/trunk/docs/images/state_dia.jpg (with props)
hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.dia
(with props)
hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.jpg
(with props)
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
Modified: hadoop/zookeeper/trunk/CHANGES.txt
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/CHANGES.txt?rev=788539&r1=788538&r2=788539&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/CHANGES.txt (original)
+++ hadoop/zookeeper/trunk/CHANGES.txt Thu Jun 25 22:42:42 2009
@@ -240,6 +240,9 @@
ZOOKEEPER-327. document effects (latency) of storing large amounts of data
in znodes. (breed via mahadev)
+ ZOOKEEPER-264. docs should include a state transition diagram for client
+state (breed via mahadev)
+
NEW FEATURES:
ZOOKEEPER-371. jdiff documentation included in build/release (giri via phunt)
Added: hadoop/zookeeper/trunk/docs/images/state_dia.jpg
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/images/state_dia.jpg?rev=788539&view=auto
==============================================================================
Binary file - no diff available.
Propchange: hadoop/zookeeper/trunk/docs/images/state_dia.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html?rev=788539&r1=788538&r2=788539&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html (original)
+++ hadoop/zookeeper/trunk/docs/zookeeperProgrammers.html Thu Jun 25 22:42:42
2009
@@ -771,7 +771,18 @@
<a name="N101A8"></a><a name="ch_zkSessions"></a>
<h2 class="h3">ZooKeeper Sessions</h2>
<div class="section">
-<p>To create a client session the application code must provide
+<p>A ZooKeeper client establishes a session with the ZooKeeper
+ service by creating a handle to the service using a language
+ binding. Once created, the handle starts of in the CONNECTING state
+ and the client library tries to connect to one of the servers that
+ make up the ZooKeeper service at which point it switches to the
+ CONNECTED state. During normal operation will be in one of these
+ two states. If an unrecoverable error occurs, such as session
+ expiration or authentication failure, or if the application explicitly
+ closes the handle, the handle will move to the CLOSED state.
+ The following figure shows the possible state transitions of a
+ ZooKeeper client:</p>
+<img alt="" src="images/state_dia.jpg"><p>To create a client session the
application code must provide
a connection string containing a comma separated list of host:port pairs,
each corresponding to a ZooKeeper server (e.g. "127.0.0.1:4545" or
"127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"). The ZooKeeper
@@ -856,7 +867,7 @@
</div>
-<a name="N101D2"></a><a name="ch_zkWatches"></a>
+<a name="N101D9"></a><a name="ch_zkWatches"></a>
<h2 class="h3">ZooKeeper Watches</h2>
<div class="section">
<p>All of the read operations in ZooKeeper - <strong>getData()</strong>,
<strong>getChildren()</strong>, and <strong>exists()</strong> - have the option
of setting a watch as a
@@ -939,7 +950,7 @@
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.</p>
-<a name="N10208"></a><a name="sc_WatchGuarantees"></a>
+<a name="N1020F"></a><a name="sc_WatchGuarantees"></a>
<h3 class="h4">What ZooKeeper Guarantees about Watches</h3>
<p>With regard to watches, ZooKeeper maintains these
guarantees:</p>
@@ -974,7 +985,7 @@
</li>
</ul>
-<a name="N1022D"></a><a name="sc_WatchRememberThese"></a>
+<a name="N10234"></a><a name="sc_WatchRememberThese"></a>
<h3 class="h4">Things to Remember about Watches</h3>
<ul>
@@ -1033,7 +1044,7 @@
</div>
-<a name="N10259"></a><a name="sc_ZooKeeperAccessControl"></a>
+<a name="N10260"></a><a name="sc_ZooKeeperAccessControl"></a>
<h2 class="h3">ZooKeeper access control using ACLs</h2>
<div class="section">
<p>ZooKeeper uses ACLs to control access to its znodes (the
@@ -1068,7 +1079,7 @@
example, the pair <em>(ip:19.22.0.0/16, READ)</em>
gives the <em>READ</em> permission to any clients with
an IP address that starts with 19.22.</p>
-<a name="N1028C"></a><a name="sc_ACLPermissions"></a>
+<a name="N10293"></a><a name="sc_ACLPermissions"></a>
<h3 class="h4">ACL Permissions</h3>
<p>ZooKeeper supports the following permissions:</p>
<ul>
@@ -1124,7 +1135,7 @@
node, but nothing more. (The problem is, if you want to call
zoo_exists() on a node that doesn't exist, there is no
permission to check.)</p>
-<a name="N102E2"></a><a name="sc_BuiltinACLSchemes"></a>
+<a name="N102E9"></a><a name="sc_BuiltinACLSchemes"></a>
<h4>Builtin ACL Schemes</h4>
<p>ZooKeeeper has the following built in schemes:</p>
<ul>
@@ -1173,7 +1184,7 @@
</ul>
-<a name="N10326"></a><a name="ZooKeeper+C+client+API"></a>
+<a name="N1032D"></a><a name="ZooKeeper+C+client+API"></a>
<h4>ZooKeeper C client API</h4>
<p>The following constants are provided by the ZooKeeper C
library:</p>
@@ -1395,7 +1406,7 @@
</div>
-<a name="N1043D"></a><a name="sc_ZooKeeperPluggableAuthentication"></a>
+<a name="N10444"></a><a name="sc_ZooKeeperPluggableAuthentication"></a>
<h2 class="h3">Pluggable ZooKeeper authentication</h2>
<div class="section">
<p>ZooKeeper runs in a variety of different environments with
@@ -1481,7 +1492,7 @@
</div>
-<a name="N104A9"></a><a name="ch_zkGuarantees"></a>
+<a name="N104B0"></a><a name="ch_zkGuarantees"></a>
<h2 class="h3">Consistency Guarantees</h2>
<div class="section">
<p>ZooKeeper is a high performance, scalable service. Both reads and
@@ -1607,12 +1618,12 @@
</div>
-<a name="N10510"></a><a name="ch_bindings"></a>
+<a name="N10517"></a><a name="ch_bindings"></a>
<h2 class="h3">Bindings</h2>
<div class="section">
<p>The ZooKeeper client libraries come in two languages: Java and C.
The following sections describe these.</p>
-<a name="N10519"></a><a name="Java+Binding"></a>
+<a name="N10520"></a><a name="Java+Binding"></a>
<h3 class="h4">Java Binding</h3>
<p>There are two packages that make up the ZooKeeper Java binding:
<strong>org.apache.zookeeper</strong> and
<strong>org.apache.zookeeper.data</strong>. The rest of the
@@ -1679,7 +1690,7 @@
(SESSION_EXPIRED and AUTH_FAILED), the ZooKeeper object becomes invalid.
On a close, the two threads shut down and any further access on zookeeper
handle is undefined behavior and should be avoided. </p>
-<a name="N10562"></a><a name="C+Binding"></a>
+<a name="N10569"></a><a name="C+Binding"></a>
<h3 class="h4">C Binding</h3>
<p>The C binding has a single-threaded and multi-threaded library.
The multi-threaded library is easiest to use and is most similar to the
@@ -1696,7 +1707,7 @@
(i.e. FreeBSD 4.x). In all other cases, application developers should
link with zookeeper_mt, as it includes support for both Sync and Async
API.</p>
-<a name="N10571"></a><a name="Installation"></a>
+<a name="N10578"></a><a name="Installation"></a>
<h4>Installation</h4>
<p>If you're building the client from a check-out from the Apache
repository, follow the steps outlined below. If you're building from a
@@ -1827,7 +1838,7 @@
</li>
</ol>
-<a name="N1061A"></a><a name="Using+the+C+Client"></a>
+<a name="N10621"></a><a name="Using+the+C+Client"></a>
<h4>Using the C Client</h4>
<p>You can test your client by running a ZooKeeper server (see
instructions on the project wiki page on how to run it) and connecting
@@ -1885,7 +1896,7 @@
</div>
-<a name="N10660"></a><a name="ch_guideToZkOperations"></a>
+<a name="N10667"></a><a name="ch_guideToZkOperations"></a>
<h2 class="h3">Building Blocks: A Guide to ZooKeeper Operations</h2>
<div class="section">
<p>This section surveys all the operations a developer can perform
@@ -1903,28 +1914,28 @@
</li>
</ul>
-<a name="N10674"></a><a name="sc_errorsZk"></a>
+<a name="N1067B"></a><a name="sc_errorsZk"></a>
<h3 class="h4">Handling Errors</h3>
<p>Both the Java and C client bindings may report errors. The Java client
binding does so by throwing KeeperException, calling code() on the exception
will return the specific error code. The C client binding returns an error code
as defined in the enum ZOO_ERRORS. API callbacks indicate result code for both
language bindings. See the API documentation (javadoc for Java, doxygen for C)
for full details on the possible errors and their meaning.</p>
-<a name="N1067E"></a><a name="sc_connectingToZk"></a>
+<a name="N10685"></a><a name="sc_connectingToZk"></a>
<h3 class="h4">Connecting to ZooKeeper</h3>
<p></p>
-<a name="N10687"></a><a name="sc_readOps"></a>
+<a name="N1068E"></a><a name="sc_readOps"></a>
<h3 class="h4">Read Operations</h3>
<p></p>
-<a name="N10690"></a><a name="sc_writeOps"></a>
+<a name="N10697"></a><a name="sc_writeOps"></a>
<h3 class="h4">Write Operations</h3>
<p></p>
-<a name="N10699"></a><a name="sc_handlingWatches"></a>
+<a name="N106A0"></a><a name="sc_handlingWatches"></a>
<h3 class="h4">Handling Watches</h3>
<p></p>
-<a name="N106A2"></a><a name="sc_miscOps"></a>
+<a name="N106A9"></a><a name="sc_miscOps"></a>
<h3 class="h4">Miscelleaneous ZooKeeper Operations</h3>
<p></p>
</div>
-<a name="N106AC"></a><a name="ch_programStructureWithExample"></a>
+<a name="N106B3"></a><a name="ch_programStructureWithExample"></a>
<h2 class="h3">Program Structure, with Simple Example</h2>
<div class="section">
<p>
@@ -1933,7 +1944,7 @@
</div>
-<a name="N106B7"></a><a name="ch_gotchas"></a>
+<a name="N106BE"></a><a name="ch_gotchas"></a>
<h2 class="h3">Gotchas: Common Problems and Troubleshooting</h2>
<div class="section">
<p>So now you know ZooKeeper. It's fast, simple, your application
Modified: hadoop/zookeeper/trunk/docs/zookeeperProgrammers.pdf
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/docs/zookeeperProgrammers.pdf?rev=788539&r1=788538&r2=788539&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=788539&r1=788538&r2=788539&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
Thu Jun 25 22:42:42 2009
@@ -373,6 +373,24 @@
<section id="ch_zkSessions">
<title>ZooKeeper Sessions</title>
+ <para>A ZooKeeper client establishes a session with the ZooKeeper
+ service by creating a handle to the service using a language
+ binding. Once created, the handle starts of in the CONNECTING state
+ and the client library tries to connect to one of the servers that
+ make up the ZooKeeper service at which point it switches to the
+ CONNECTED state. During normal operation will be in one of these
+ two states. If an unrecoverable error occurs, such as session
+ expiration or authentication failure, or if the application explicitly
+ closes the handle, the handle will move to the CLOSED state.
+ The following figure shows the possible state transitions of a
+ ZooKeeper client:</para>
+
+ <mediaobject id="fg_states" >
+ <imageobject>
+ <imagedata fileref="images/state_dia.jpg"/>
+ </imageobject>
+ </mediaobject>
+
<para>To create a client session the application code must provide
a connection string containing a comma separated list of host:port pairs,
each corresponding to a ZooKeeper server (e.g. "127.0.0.1:4545" or
Added:
hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.dia
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.dia?rev=788539&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.dia
------------------------------------------------------------------------------
svn:executable = *
Propchange:
hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.dia
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.jpg
URL:
http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.jpg?rev=788539&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.jpg
------------------------------------------------------------------------------
svn:executable = *
Propchange:
hadoop/zookeeper/trunk/src/docs/src/documentation/resources/images/state_dia.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
