ZOOKEEPER-243. add SEQUENCE flag documentation to the programming guide. (patrick hunt via mahadev)

git-svn-id: https://svn.apache.org/repos/asf/hadoop/zookeeper/trunk@724917 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -55,6 +55,9 @@ IMPROVEMENTS:
    ZOOKEEPER-64. Log system env information when initializing server and
 client (pat via mahadev)
 
+   ZOOKEEPER-243. add SEQUENCE flag documentation to the programming guide.
+(patrick hunt via mahadev)
+
 Release 3.0.0 - 2008-10-21
 
 Non-backward compatible changes:

docs/zookeeperProgrammers.html

@@ -201,7 +201,7 @@ document.write("Last Published: " + document.lastModified);
 <a href="#Ephemeral+Nodes">Ephemeral Nodes</a>
 </li>
 <li>
-<a href="#Unique+Naming">Unique Naming</a>
+<a href="#Sequence+Nodes+--+Unique+Naming">Sequence Nodes -- Unique Naming</a>
 </li>
 </ul>
 </li>
@@ -308,7 +308,7 @@ document.write("Last Published: " + document.lastModified);
     services. It contains conceptual and practical information.</p>
 <p>The first four sections of this guide present higher level
     discussions of various ZooKeeper concepts. These are necessary both for an
-    understanding of how Zookeeper works as well how to work with it. It does
+    understanding of how ZooKeeper works as well how to work with it. It does
     not contain source code, but it does assume a familiarity with the
     problems associated with distributed computing. The sections in this first
     group are:</p>
@@ -496,28 +496,34 @@ document.write("Last Published: " + document.lastModified);
         the watch and then clear the watch. When a watch triggers, ZooKeeper
         sends the client a notification. More information about watches can be
         found in the section 
-	    <a href="#ch_zkWatches">ZooKeeper Watches</a>.
-        <em>[tbd]</em>
-</p>
-<a name="N100DA"></a><a name="Data+Access"></a>
+	    <a href="#ch_zkWatches">ZooKeeper Watches</a>.</p>
+<a name="N100D8"></a><a name="Data+Access"></a>
 <h4>Data Access</h4>
 <p>The data stored at each znode in a namespace is read and written
         atomically. Reads get all the data bytes associated with a znode and a
         write replaces all the data. Each node has an Access Control List
         (ACL) that restricts who can do what.</p>
-<a name="N100E4"></a><a name="Ephemeral+Nodes"></a>
+<a name="N100E2"></a><a name="Ephemeral+Nodes"></a>
 <h4>Ephemeral Nodes</h4>
 <p>ZooKeeper also has the notion of ephemeral nodes. These znodes
         exists as long as the session that created the znode is active. When
         the session ends the znode is deleted. Because of this behavior
         ephemeral znodes are not allowed to have children.</p>
-<a name="N100EE"></a><a name="Unique+Naming"></a>
-<h4>Unique Naming</h4>
-<p>Finally you create a znode, you can request that ZooKeeper
-        append a monotonicly increasing counter be appended to the path name
-        of the znode to be requested. This counter is unique to the parent
-        znode.</p>
-<a name="N100F9"></a><a name="sc_timeInZk"></a>
+<a name="N100EC"></a><a name="Sequence+Nodes+--+Unique+Naming"></a>
+<h4>Sequence Nodes -- Unique Naming</h4>
+<p>When creating a znode you can also request that
+        ZooKeeper append a monotonicly increasing counter to the end
+        of path. This counter is unique to the parent znode. The
+        counter has a format of %010d -- that is 10 digits with 0
+        (zero) padding (the counter is formatted in this way to
+        simplify sorting), i.e. "&lt;path&gt;0000000001". See
+        <a href="recipes.html#sc_recipes_Queues">Queue
+        Recipe</a> for an example use of this feature. Note: the
+        counter used to store the next sequence number is a signed int
+        (4bytes) maintained by the parent node, the counter will
+        overflow when incremented beyond 2147483647 (resulting in a
+        name "&lt;path&gt;-2147483647").</p>
+<a name="N100FB"></a><a name="sc_timeInZk"></a>
 <h3 class="h4">Time in ZooKeeper</h3>
 <p>ZooKeeper tracks time multiple ways:</p>
 <ul>
@@ -586,7 +592,7 @@ document.write("Last Published: " + document.lastModified);
 </li>
       
 </ul>
-<a name="N10131"></a><a name="sc_zkStatStructure"></a>
+<a name="N10133"></a><a name="sc_zkStatStructure"></a>
 <h3 class="h4">ZooKeeper Stat Structure</h3>
 <p>The Stat structure for each znode in ZooKeeper is made up of the
       following fields:</p>
@@ -721,7 +727,7 @@ document.write("Last Published: " + document.lastModified);
 </div>
 
   
-<a name="N101A3"></a><a name="ch_zkSessions"></a>
+<a name="N101A5"></a><a name="ch_zkSessions"></a>
 <h2 class="h3">ZooKeeper Sessions</h2>
 <div class="section">
 <p>When a client gets a handle to the ZooKeeper service, ZooKeeper
@@ -749,7 +755,7 @@ document.write("Last Published: " + document.lastModified);
 </div>
 
   
-<a name="N101B3"></a><a name="ch_zkWatches"></a>
+<a name="N101B5"></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
@@ -826,7 +832,7 @@ document.write("Last Published: " + document.lastModified);
     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="N101E9"></a><a name="sc_WatchGuarantees"></a>
+<a name="N101EB"></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>
@@ -861,7 +867,7 @@ document.write("Last Published: " + document.lastModified);
 </li>
       
 </ul>
-<a name="N1020E"></a><a name="sc_WatchRememberThese"></a>
+<a name="N10210"></a><a name="sc_WatchRememberThese"></a>
 <h3 class="h4">Things to Remember about Watches</h3>
 <ul>
         
@@ -920,7 +926,7 @@ document.write("Last Published: " + document.lastModified);
 </div>
 
   
-<a name="N1023A"></a><a name="sc_ZooKeeperAccessControl"></a>
+<a name="N1023C"></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
@@ -949,7 +955,7 @@ document.write("Last Published: " + document.lastModified);
     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="N10261"></a><a name="sc_ACLPermissions"></a>
+<a name="N10263"></a><a name="sc_ACLPermissions"></a>
 <h3 class="h4">ACL Permissions</h3>
 <p>ZooKeeper supports the following permissions:</p>
 <ul>
@@ -1005,7 +1011,7 @@ document.write("Last Published: " + document.lastModified);
       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="N102B7"></a><a name="sc_BuiltinACLSchemes"></a>
+<a name="N102B9"></a><a name="sc_BuiltinACLSchemes"></a>
 <h4>Builtin ACL Schemes</h4>
 <p>ZooKeeeper has the following built in schemes:</p>
 <ul>
@@ -1066,7 +1072,7 @@ document.write("Last Published: " + document.lastModified);
 
       
 </ul>
-<a name="N1030D"></a><a name="ZooKeeper+C+client+API"></a>
+<a name="N1030F"></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>
@@ -1277,7 +1283,7 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N10433"></a><a name="ch_zkGuarantees"></a>
+<a name="N10435"></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
@@ -1403,12 +1409,12 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N1049A"></a><a name="ch_bindings"></a>
+<a name="N1049C"></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="N104A3"></a><a name="Java+Binding"></a>
+<a name="N104A5"></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
@@ -1475,7 +1481,7 @@ int main(int argc, char argv) {
       (SESSION_EXPIRED and AUTH_FAILED), the ZooKeeper object becomes invalid,
       the two threads shut down, and any further ZooKeeper calls throw
       errors.</p>
-<a name="N104EC"></a><a name="C+Binding"></a>
+<a name="N104EE"></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
@@ -1492,7 +1498,7 @@ int main(int argc, char argv) {
       (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="N104FB"></a><a name="Installation"></a>
+<a name="N104FD"></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
@@ -1623,7 +1629,7 @@ int main(int argc, char argv) {
 </li>
         
 </ol>
-<a name="N105A4"></a><a name="Using+the+C+Client"></a>
+<a name="N105A6"></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
@@ -1681,7 +1687,7 @@ int main(int argc, char argv) {
 </div>
 
    
-<a name="N105EA"></a><a name="ch_guideToZkOperations"></a>
+<a name="N105EC"></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
@@ -1699,25 +1705,25 @@ int main(int argc, char argv) {
 </li>
     
 </ul>
-<a name="N105FE"></a><a name="sc_connectingToZk"></a>
+<a name="N10600"></a><a name="sc_connectingToZk"></a>
 <h3 class="h4">Connecting to ZooKeeper</h3>
 <p></p>
-<a name="N10607"></a><a name="sc_readOps"></a>
+<a name="N10609"></a><a name="sc_readOps"></a>
 <h3 class="h4">Read Operations</h3>
 <p></p>
-<a name="N10610"></a><a name="sc_writeOps"></a>
+<a name="N10612"></a><a name="sc_writeOps"></a>
 <h3 class="h4">Write Operations</h3>
 <p></p>
-<a name="N10619"></a><a name="sc_handlingWatches"></a>
+<a name="N1061B"></a><a name="sc_handlingWatches"></a>
 <h3 class="h4">Handling Watches</h3>
 <p></p>
-<a name="N10622"></a><a name="sc_miscOps"></a>
+<a name="N10624"></a><a name="sc_miscOps"></a>
 <h3 class="h4">Miscelleaneous ZooKeeper Operations</h3>
 <p></p>
 </div>
 
   
-<a name="N1062C"></a><a name="ch_programStructureWithExample"></a>
+<a name="N1062E"></a><a name="ch_programStructureWithExample"></a>
 <h2 class="h3">Program Structure, with Simple Example</h2>
 <div class="section">
 <p>
@@ -1726,7 +1732,7 @@ int main(int argc, char argv) {
 </div>
 
   
-<a name="N10637"></a><a name="ch_gotchas"></a>
+<a name="N10639"></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

src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml

@@ -38,7 +38,7 @@
     <abstract>
       <para>This guide contains detailed information about creating
       distributed applications that use ZooKeeper. It discusses the basic
-      operations Zookeeper supports, and how these can be used to build
+      operations ZooKeeper supports, and how these can be used to build
       higher-level abstractions. It contains solutions to common tasks, a
       troubleshooting guide, and links to other information.</para>
 
@@ -55,7 +55,7 @@
 
     <para>The first four sections of this guide present higher level
     discussions of various ZooKeeper concepts. These are necessary both for an
-    understanding of how Zookeeper works as well how to work with it. It does
+    understanding of how ZooKeeper works as well how to work with it. It does
     not contain source code, but it does assume a familiarity with the
     problems associated with distributed computing. The sections in this first
     group are:</para>
@@ -192,8 +192,7 @@
         the watch and then clear the watch. When a watch triggers, ZooKeeper
         sends the client a notification. More information about watches can be
         found in the section 
-	    <ulink url="#ch_zkWatches">ZooKeeper Watches</ulink>.
-        <emphasis>[tbd]</emphasis></para>
+	    <ulink url="#ch_zkWatches">ZooKeeper Watches</ulink>.</para>
       </section>
 
       <section>
@@ -215,12 +214,20 @@
       </section>
 
       <section>
-        <title>Unique Naming</title>
-
-        <para>Finally you create a znode, you can request that ZooKeeper
-        append a monotonicly increasing counter be appended to the path name
-        of the znode to be requested. This counter is unique to the parent
-        znode.</para>
+        <title>Sequence Nodes -- Unique Naming</title>
+
+        <para>When creating a znode you can also request that
+        ZooKeeper append a monotonicly increasing counter to the end
+        of path. This counter is unique to the parent znode. The
+        counter has a format of %010d -- that is 10 digits with 0
+        (zero) padding (the counter is formatted in this way to
+        simplify sorting), i.e. "&lt;path&gt;0000000001". See
+        <ulink url="recipes.html#sc_recipes_Queues">Queue
+        Recipe</ulink> for an example use of this feature. Note: the
+        counter used to store the next sequence number is a signed int
+        (4bytes) maintained by the parent node, the counter will
+        overflow when incremented beyond 2147483647 (resulting in a
+        name "&lt;path&gt;-2147483647").</para>
       </section>
     </section>