You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zookeeper.apache.org by an...@apache.org on 2018/07/04 13:11:31 UTC
[11/12] zookeeper git commit: ZOOKEEPER-3022: MAVEN MIGRATION 3.4 -
Iteration 1 - docs, it
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/c1efa954/src/docs/src/documentation/content/xdocs/bookkeeperStarted.xml
----------------------------------------------------------------------
diff --git a/src/docs/src/documentation/content/xdocs/bookkeeperStarted.xml b/src/docs/src/documentation/content/xdocs/bookkeeperStarted.xml
deleted file mode 100644
index 74f6f7e..0000000
--- a/src/docs/src/documentation/content/xdocs/bookkeeperStarted.xml
+++ /dev/null
@@ -1,208 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
-"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
-<article id="bk_GettStartedGuide">
- <title>BookKeeper Getting Started Guide</title>
-
- <articleinfo>
- <legalnotice>
- <para>Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License. You may
- obtain a copy of the License at <ulink
- url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>.</para>
-
- <para>Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an "AS IS"
- BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied. See the License for the specific language governing permissions
- and limitations under the License.</para>
- </legalnotice>
-
- <abstract>
- <para>This guide contains detailed information about using BookKeeper
- for logging. It discusses the basic operations BookKeeper supports,
- and how to create logs and perform basic read and write operations on these
- logs.</para>
- </abstract>
- </articleinfo>
- <section id="bk_GettingStarted">
- <title>Getting Started: Setting up BookKeeper to write logs.</title>
-
- <para>This document contains information to get you started quickly with
- BookKeeper. It is aimed primarily at developers willing to try it out, and
- contains simple installation instructions for a simple BookKeeper installation
- and a simple programming example. For further programming detail, please refer to
- <ulink url="bookkeeperProgrammer.html">BookKeeper Programmer's Guide</ulink>.
- </para>
-
- <section id="bk_Prerequisites">
- <title>Pre-requisites</title>
- <para>See <ulink url="bookkeeperConfig.html#bk_sysReq">
- System Requirements</ulink> in the Admin guide.</para>
- </section>
-
- <section id="bk_Download">
- <title>Download</title>
- <para> BookKeeper is distributed along with ZooKeeper. To get a ZooKeeper distribution,
- download a recent
- <ulink url="http://zookeeper.apache.org/releases.html">
- stable</ulink> release from one of the Apache Download
- Mirrors.</para>
- </section>
-
- <section id="bk_localBK">
- <title>LocalBookKeeper</title>
- <para> Under org.apache.bookkeeper.util, you'll find a java program
- called LocalBookKeeper.java that sets you up to run BookKeeper on a
- single machine. This is far from ideal from a performance perspective,
- but the program is useful for both test and educational purposes.
- </para>
- </section>
-
- <section id="bk_setupBookies">
- <title>Setting up bookies</title>
- <para> If you're bold and you want more than just running things locally, then
- you'll need to run bookies in different servers. You'll need at least three bookies
- to start with.
- </para>
-
- <para>
- For each bookie, we need to execute a command like the following:
- </para>
-
- <para><computeroutput>
- java -cp .:./zookeeper-<version>-bookkeeper.jar:./zookeeper-<version>.jar\
- :lib/slf4j-api-1.6.1.jar:lib/slf4j-log4j12-1.6.1.jar:lib/log4j-1.2.15.jar -Dlog4j.configuration=log4j.properties\
- org.apache.bookkeeper.proto.BookieServer 3181 127.0.0.1:2181 /path_to_log_device/\
- /path_to_ledger_device/
- </computeroutput></para>
-
- <para> "/path_to_log_device/" and "/path_to_ledger_device/" are different paths. Also, port 3181
- is the port that a bookie listens on for connection requests from clients. 127.0.0.1:2181 is the hostname:port
- for the ZooKeeper server. In this example, the standalone ZooKeeper server is running locally on port 2181.
- If we had multiple ZooKeeper servers, this parameter would be a comma separated list of all the hostname:port
- values corresponding to them.
- </para>
- </section>
-
- <section id="bk_setupZK">
- <title>Setting up ZooKeeper</title>
- <para> ZooKeeper stores metadata on behalf of BookKeeper clients and bookies. To get a minimal
- ZooKeeper installation to work with BookKeeper, we can set up one server running in
- standalone mode. Once we have the server running, we need to create a few znodes:
- </para>
-
- <orderedlist>
- <listitem>
- <para><computeroutput>
- /ledgers
- </computeroutput></para>
- </listitem>
-
- <listitem>
- <para><computeroutput>
- /ledgers/available
- </computeroutput></para>
- </listitem>
-
- <listitem>
- <para> For each bookie, we add one znode such that the name of the znode is the
- concatenation of the machine name and the port number that the bookie is
- listening on. For example, if a bookie is running on bookie.foo.com an is listening
- on port 3181, we add a znode
- <computeroutput>/ledgers/available/bookie.foo.com:3181</computeroutput>.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="bk_example">
- <title>Example</title>
- <para>
- In the following excerpt of code, we:
- </para>
-
- <orderedlist>
- <listitem>
- <para>
- Create a ledger;
- </para>
- </listitem>
-
- <listitem>
- <para>
- Write to the ledger;
- </para>
- </listitem>
-
- <listitem>
- <para>
- Close the ledger;
- </para>
- </listitem>
-
- <listitem>
- <para>
- Open the same ledger for reading;
- </para>
- </listitem>
-
- <listitem>
- <para>
- Read from the ledger;
- </para>
- </listitem>
-
- <listitem>
- <para>
- Close the ledger again;
- </para>
- </listitem>
- </orderedlist>
-
- <programlisting>
-LedgerHandle lh = bkc.createLedger(ledgerPassword);
-ledgerId = lh.getId();
-ByteBuffer entry = ByteBuffer.allocate(4);
-
-for(int i = 0; i < 10; i++){
- entry.putInt(i);
- entry.position(0);
- entries.add(entry.array());
- lh.addEntry(entry.array());
-}
-lh.close();
-lh = bkc.openLedger(ledgerId, ledgerPassword);
-
-Enumeration<LedgerEntry> ls = lh.readEntries(0, 9);
-int i = 0;
-while(ls.hasMoreElements()){
- ByteBuffer origbb = ByteBuffer.wrap(
- entries.get(i++));
- Integer origEntry = origbb.getInt();
- ByteBuffer result = ByteBuffer.wrap(
- ls.nextElement().getEntry());
-
- Integer retrEntry = result.getInt();
-}
-lh.close();
- </programlisting>
- </section>
- </section>
-</article>
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/c1efa954/src/docs/src/documentation/content/xdocs/bookkeeperStream.xml
----------------------------------------------------------------------
diff --git a/src/docs/src/documentation/content/xdocs/bookkeeperStream.xml b/src/docs/src/documentation/content/xdocs/bookkeeperStream.xml
deleted file mode 100644
index 9db605a..0000000
--- a/src/docs/src/documentation/content/xdocs/bookkeeperStream.xml
+++ /dev/null
@@ -1,331 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
-"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
-<article id="bk_Stream">
- <title>Streaming with BookKeeper</title>
-
- <articleinfo>
- <legalnotice>
- <para>Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License. You may
- obtain a copy of the License at <ulink
- url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>.</para>
-
- <para>Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an "AS IS"
- BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied. See the License for the specific language governing permissions
- and limitations under the License.</para>
- </legalnotice>
-
- <abstract>
- <para>This guide contains detailed information about using how to stream bytes
- on top of BookKeeper. It essentially motivates and discusses the basic stream
- operations currently supported.</para>
- </abstract>
- </articleinfo>
- <section id="bk_StreamSummary">
- <title>Summary</title>
-
- <para>
- When using the BookKeeper API, an application has to split the data to write into entries, each
- entry being a byte array. This is natural for many applications. For example, when using BookKeeper
- for write-ahead logging, an application typically wants to write the modifications corresponding
- to a command or a transaction. Some other applications, however, might not have a natural boundary
- for entries, and may prefer to write and read streams of bytes. This is exactly the purpose of the
- stream API we have implemented on top of BookKeeper.
- </para>
-
- <para>
- The stream API is implemented in the package <computeroutput>Streaming</computeroutput>, and it contains two main classes: <computeroutput>LedgerOutputStream</computeroutput> and
- <computeroutput>LedgerInputStream</computeroutput>. The class names are indicative of what they do.
- </para>
- </section>
-
- <section id="bk_LedgerOutputStream">
- <title>Writing a stream of bytes</title>
- <para>
- Class <computeroutput>LedgerOutputStream</computeroutput> implements two constructors and five public methods:
- </para>
-
- <para>
- <computeroutput>
- public LedgerOutputStream(LedgerHandle lh)
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>lh</computeroutput> is a ledger handle for a previously created and open ledger.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <computeroutput>
- public LedgerOutputStream(LedgerHandle lh, int size)
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>lh</computeroutput> is a ledger handle for a previously created and open ledger.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <computeroutput>size</computeroutput> is the size of the byte buffer to store written bytes before flushing.
- </para>
- </listitem>
- </itemizedlist>
-
-
- <para>
- <emphasis role="bold">Closing a stream.</emphasis> This call closes the stream by flushing the write buffer.
- </para>
- <para>
- <computeroutput>
- public void close()
- </computeroutput>
- </para>
-
- <para>
- which has no parameters.
- </para>
-
- <para>
- <emphasis role="bold">Flushing a stream.</emphasis> This call essentially flushes the write buffer.
- </para>
- <para>
- <computeroutput>
- public synchronized void flush()
- </computeroutput>
- </para>
-
- <para>
- which has no parameters.
- </para>
-
- <para>
- <emphasis role="bold">Writing bytes.</emphasis> There are three calls for writing bytes to a stream.
- </para>
-
- <para>
- <computeroutput>
- public synchronized void write(byte[] b)
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>b</computeroutput> is an array of bytes to write.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <computeroutput>
- public synchronized void write(byte[] b, int off, int len)
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>b</computeroutput> is an array of bytes to write.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <computeroutput>off</computeroutput> is a buffer offset.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <computeroutput>len</computeroutput> is the length to write.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <computeroutput>
- public synchronized void write(int b)
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>b</computeroutput> contains a byte to write. The method writes the least significant byte of the integer four bytes.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="bk_LedgerInputStream">
- <title>Reading a stream of bytes</title>
-
- <para>
- Class <computeroutput>LedgerOutputStream</computeroutput> implements two constructors and four public methods:
- </para>
-
- <para>
- <computeroutput>
- public LedgerInputStream(LedgerHandle lh)
- throws BKException, InterruptedException
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>lh</computeroutput> is a ledger handle for a previously created and open ledger.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <computeroutput>
- public LedgerInputStream(LedgerHandle lh, int size)
- throws BKException, InterruptedException
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>lh</computeroutput> is a ledger handle for a previously created and open ledger.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <computeroutput>size</computeroutput> is the size of the byte buffer to store bytes that the application
- will eventually read.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <emphasis role="bold">Closing.</emphasis> There is one call to close an input stream, but the call
- is currently empty and the application is responsible for closing the ledger handle.
- </para>
- <para>
- <computeroutput>
- public void close()
- </computeroutput>
- </para>
-
- <para>
- which has no parameters.
- </para>
-
- <para>
- <emphasis role="bold">Reading.</emphasis> There are three calls to read from the stream.
- </para>
- <para>
- <computeroutput>
- public synchronized int read()
- throws IOException
- </computeroutput>
- </para>
-
- <para>
- which has no parameters.
- </para>
-
- <para>
- <computeroutput>
- public synchronized int read(byte[] b)
- throws IOException
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>b</computeroutput> is a byte array to write to.
- </para>
- </listitem>
- </itemizedlist>
-
-
- <para>
- <computeroutput>
- public synchronized int read(byte[] b, int off, int len)
- throws IOException
- </computeroutput>
- </para>
-
- <para>
- where:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <computeroutput>b</computeroutput> is a byte array to write to.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <computeroutput>off</computeroutput> is an offset for byte array <computeroutput>b</computeroutput>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <computeroutput>len</computeroutput> is the length in bytes to write to <computeroutput>b</computeroutput>.
- </para>
- </listitem>
- </itemizedlist>
-
-
- </section>
- </article>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/c1efa954/src/docs/src/documentation/content/xdocs/index.xml
----------------------------------------------------------------------
diff --git a/src/docs/src/documentation/content/xdocs/index.xml b/src/docs/src/documentation/content/xdocs/index.xml
deleted file mode 100644
index 8ed4702..0000000
--- a/src/docs/src/documentation/content/xdocs/index.xml
+++ /dev/null
@@ -1,98 +0,0 @@
-<?xml version="1.0"?>
-<!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
-
-<document>
-
- <header>
- <title>ZooKeeper: Because Coordinating Distributed Systems is a Zoo</title>
- </header>
-
- <body>
- <p>ZooKeeper is a high-performance coordination service for
- distributed applications. It exposes common services - such as
- naming, configuration management, synchronization, and group
- services - in a simple interface so you don't have to write them
- from scratch. You can use it off-the-shelf to implement
- consensus, group management, leader election, and presence
- protocols. And you can build on it for your own, specific needs.
- </p>
-
- <p>
- The following documents describe concepts and procedures to get
- you started using ZooKeeper. If you have more questions, please
- ask the <a href="ext:lists">mailing list</a> or browse the
- archives.
- </p>
- <ul>
-
- <li><strong>ZooKeeper Overview</strong><p>Technical Overview Documents for Client Developers, Adminstrators, and Contributors</p>
- <ul><li><a href="zookeeperOver.html">Overview</a> - a bird's eye view of ZooKeeper, including design concepts and architecture</li>
- <li><a href="zookeeperStarted.html">Getting Started</a> - a tutorial-style guide for developers to install, run, and program to ZooKeeper</li>
- <li><a href="ext:relnotes">Release Notes</a> - new developer and user facing features, improvements, and incompatibilities</li>
- </ul>
- </li>
-
- <li><strong>Developers</strong><p> Documents for Developers using the ZooKeeper Client API</p>
- <ul>
- <li><a href="ext:api/index">API Docs</a> - the technical reference to ZooKeeper Client APIs</li>
- <li><a href="zookeeperProgrammers.html">Programmer's Guide</a> - a client application developer's guide to ZooKeeper</li>
- <li><a href="javaExample.html">ZooKeeper Java Example</a> - a simple Zookeeper client appplication, written in Java</li>
- <li><a href="zookeeperTutorial.html">Barrier and Queue Tutorial</a> - sample implementations of barriers and queues</li>
- <li><a href="recipes.html">ZooKeeper Recipes</a> - higher level solutions to common problems in distributed applications</li>
- </ul>
- </li>
-
- <li><strong>Administrators & Operators</strong> <p> Documents for Administrators and Operations Engineers of ZooKeeper Deployments</p>
- <ul>
- <li><a href="zookeeperAdmin.html">Administrator's Guide</a> - a guide for system administrators and anyone else who might deploy ZooKeeper</li>
- <li><a href="zookeeperQuotas.html">Quota Guide</a> - a guide for system administrators on Quotas in ZooKeeper. </li>
- <li><a href="zookeeperJMX.html">JMX</a> - how to enable JMX in ZooKeeper</li>
- <li><a href="zookeeperHierarchicalQuorums.html">Hierarchical quorums</a></li>
- <li><a href="zookeeperObservers.html">Observers</a> - non-voting ensemble members that easily improve ZooKeeper's scalability</li>
- </ul>
- </li>
-
- <li><strong>Contributors</strong><p> Documents for Developers Contributing to the ZooKeeper Open Source Project</p>
- <ul>
- <li><a href="zookeeperInternals.html">ZooKeeper Internals</a> - assorted topics on the inner workings of ZooKeeper</li>
- </ul>
- </li>
-
- <li><strong>Miscellaneous ZooKeeper Documentation</strong>
- <ul>
- <li><a href="ext:wiki">Wiki</a></li>
- <li><a href="ext:faq">FAQ</a></li>
- </ul>
- </li>
-
- <li><strong>BookKeeper Documentation</strong>
- <p> BookKeeper is a highly-available system that implements high-performance write-ahead logging. It uses ZooKeeper for metadata,
- which is the main reason for being a ZooKeeper contrib.
- </p>
- <ul>
- <li><a href="bookkeeperOverview.html">henn, what's it again?</a></li>
- <li><a href="bookkeeperStarted.html">Ok, now how do I try it out</a></li>
- <li><a href="bookkeeperProgrammer.html">Awesome, but how do I integrate it with my app?</a></li>
- <li><a href="bookkeeperStream.html">Can I stream bytes instead of entries?</a></li>
- </ul>
- </li>
- </ul>
- </body>
-
-</document>
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/c1efa954/src/docs/src/documentation/content/xdocs/javaExample.xml
----------------------------------------------------------------------
diff --git a/src/docs/src/documentation/content/xdocs/javaExample.xml b/src/docs/src/documentation/content/xdocs/javaExample.xml
deleted file mode 100644
index c992282..0000000
--- a/src/docs/src/documentation/content/xdocs/javaExample.xml
+++ /dev/null
@@ -1,663 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
-"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
-<article id="ar_JavaExample">
- <title>ZooKeeper Java Example</title>
-
- <articleinfo>
- <legalnotice>
- <para>Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License. You may
- obtain a copy of the License at <ulink
- url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>.</para>
-
- <para>Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an "AS IS"
- BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied. See the License for the specific language governing permissions
- and limitations under the License.</para>
- </legalnotice>
-
- <abstract>
- <para>This article contains sample Java code for a simple watch client.</para>
-
- </abstract>
- </articleinfo>
-
- <section id="ch_Introduction">
- <title>A Simple Watch Client</title>
-
- <para>To introduce you to the ZooKeeper Java API, we develop here a very simple
- watch client. This ZooKeeper client watches a ZooKeeper node for changes
- and responds to by starting or stopping a program.</para>
-
- <section id="sc_requirements"><title>Requirements</title>
-
- <para>The client has four requirements:</para>
-
- <itemizedlist><listitem><para>It takes as parameters:</para>
- <itemizedlist>
- <listitem><para>the address of the ZooKeeper service</para></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>
-
- </section>
-
- <section id="sc_design">
- <title>Program Design</title>
-
- <para>Conventionally, ZooKeeper applications are broken into two units, one which maintains the connection,
- and the other which monitors data. In this application, the class called the <emphasis role="bold">Executor</emphasis>
- maintains the ZooKeeper connection, and the class called the <emphasis role="bold">DataMonitor</emphasis> monitors the data
- in the ZooKeeper tree. Also, Executor contains the main thread and contains the execution logic.
- It is responsible for what little user interaction there is, as well as interaction with the exectuable program you
- pass in as an argument and which the sample (per the requirements) shuts down and restarts, according to the
- state of the znode.</para>
-
- </section>
-
- </section>
-
- <section id="sc_executor"><title>The Executor Class</title>
- <para>The Executor object is the primary container of the sample application. It contains
- both the <emphasis role="bold">ZooKeeper</emphasis> object, <emphasis role="bold">DataMonitor</emphasis>, as described above in
- <xref linkend="sc_design"/>. </para>
-
- <programlisting>
- // from the Executor class...
-
- public static void main(String[] args) {
- if (args.length < 4) {
- System.err
- .println("USAGE: Executor hostPort znode filename program [args ...]");
- System.exit(2);
- }
- String hostPort = args[0];
- String znode = args[1];
- String filename = args[2];
- String exec[] = new String[args.length - 3];
- System.arraycopy(args, 3, exec, 0, exec.length);
- try {
- new Executor(hostPort, znode, filename, exec).run();
- } catch (Exception e) {
- e.printStackTrace();
- }
- }
-
- public Executor(String hostPort, String znode, String filename,
- String exec[]) throws KeeperException, IOException {
- this.filename = filename;
- this.exec = exec;
- zk = new ZooKeeper(hostPort, 3000, this);
- dm = new DataMonitor(zk, znode, null, this);
- }
-
- public void run() {
- try {
- synchronized (this) {
- while (!dm.dead) {
- wait();
- }
- }
- } catch (InterruptedException e) {
- }
- }
-</programlisting>
-
-
- <para>
- Recall that the Executor's job is to start and stop the executable whose name you pass in on the command line.
- It does this in response to events fired by the ZooKeeper object. As you can see in the code above, the Executor passes
- a reference to itself as the Watcher argument in the ZooKeeper constructor. It also passes a reference to itself
- as DataMonitorListener argument to the DataMonitor constructor. Per the Executor's definition, it implements both these
- interfaces:
- </para>
-
- <programlisting>
-public class Executor implements Watcher, Runnable, DataMonitor.DataMonitorListener {
-...</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
- 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
- in this example simply forwards those events down to the DataMonitor to decide what to do with them. It does this simply to illustrate
- the point that, by convention, the Executor or some Executor-like object "owns" the ZooKeeper connection, but it is free to delegate the events to other
- events to other objects. It also uses this as the default channel on which to fire watch events. (More on this later.)</para>
-
-<programlisting>
- public void process(WatchedEvent event) {
- dm.process(event);
- }
-</programlisting>
-
- <para>The <emphasis role="bold">DataMonitorListener</emphasis>
- interface, on the other hand, is not part of the the ZooKeeper API. It is a completely custom interface,
- designed for this sample application. The DataMonitor object uses it to communicate back to its container, which
- is also the the Executor object.The DataMonitorListener interface looks like this:</para>
- <programlisting>
-public interface DataMonitorListener {
- /**
- * The existence status of the node has changed.
- */
- void exists(byte data[]);
-
- /**
- * The ZooKeeper session is no longer valid.
- *
- * @param rc
- * the ZooKeeper reason code
- */
- void closing(int rc);
-}
-</programlisting>
- <para>This interface is defined in the DataMonitor class and implemented in the Executor class.
- When <command>Executor.exists()</command> is invoked,
- the Executor decides whether to start up or shut down per the requirements. Recall that the requires say to kill the executable when the
- znode ceases to <emphasis>exist</emphasis>. </para>
-
- <para>When <command>Executor.closing()</command>
- is invoked, the Executor decides whether or not to shut itself down in response to the ZooKeeper connection permanently disappearing.</para>
-
- <para>As you might have guessed, DataMonitor is the object that invokes
- these methods, in response to changes in ZooKeeper's state.</para>
-
- <para>Here are Executor's implementation of
- <command>DataMonitorListener.exists()</command> and <command>DataMonitorListener.closing</command>:
- </para>
- <programlisting>
-public void exists( byte[] data ) {
- if (data == null) {
- if (child != null) {
- System.out.println("Killing process");
- child.destroy();
- try {
- child.waitFor();
- } catch (InterruptedException e) {
- }
- }
- child = null;
- } else {
- if (child != null) {
- System.out.println("Stopping child");
- child.destroy();
- try {
- child.waitFor();
- } catch (InterruptedException e) {
- e.printStackTrace();
- }
- }
- try {
- FileOutputStream fos = new FileOutputStream(filename);
- fos.write(data);
- fos.close();
- } catch (IOException e) {
- e.printStackTrace();
- }
- try {
- System.out.println("Starting child");
- child = Runtime.getRuntime().exec(exec);
- new StreamWriter(child.getInputStream(), System.out);
- new StreamWriter(child.getErrorStream(), System.err);
- } catch (IOException e) {
- e.printStackTrace();
- }
- }
-}
-
-public void closing(int rc) {
- synchronized (this) {
- notifyAll();
- }
-}
-</programlisting>
-
-</section>
-<section id="sc_DataMonitor"><title>The DataMonitor Class</title>
-<para>
-The DataMonitor class has the meat of the ZooKeeper logic. It is mostly
-asynchronous and event driven. DataMonitor kicks things off in the constructor with:</para>
-<programlisting>
-public DataMonitor(ZooKeeper zk, String znode, Watcher chainedWatcher,
- DataMonitorListener listener) {
- this.zk = zk;
- this.znode = znode;
- this.chainedWatcher = chainedWatcher;
- this.listener = listener;
-
- // Get things started by checking if the node exists. We are going
- // to be completely event driven
- <emphasis role="bold">zk.exists(znode, true, this, null);</emphasis>
-}
-</programlisting>
-
-<para>The call to <command>ZooKeeper.exists()</command> checks for the existence of the znode,
-sets a watch, and passes a reference to itself (<command>this</command>)
-as the completion callback object. In this sense, it kicks things off, since the
-real processing happens when the watch is triggered.</para>
-
-<note>
-<para>Don't confuse the completion callback with the watch callback. The <command>ZooKeeper.exists()</command>
-completion callback, which happens to be the method <command>StatCallback.processResult()</command> implemented
-in the DataMonitor object, is invoked when the asynchronous <emphasis>setting of the watch</emphasis> operation
-(by <command>ZooKeeper.exists()</command>) completes on the server. </para>
-<para>
-The triggering of the watch, on the other hand, sends an event to the <emphasis>Executor</emphasis> object, since
-the Executor registered as the Watcher of the ZooKeeper object.</para>
-
-<para>As an aside, you might note that the DataMonitor could also register itself as the Watcher
-for this particular watch event. This is new to ZooKeeper 3.0.0 (the support of multiple Watchers). In this
-example, however, DataMonitor does not register as the Watcher.</para>
-</note>
-
-<para>When the <command>ZooKeeper.exists()</command> operation completes on the server, the ZooKeeper API invokes this completion callback on
-the client:</para>
-
-<programlisting>
-public void processResult(int rc, String path, Object ctx, Stat stat) {
- boolean exists;
- switch (rc) {
- case Code.Ok:
- exists = true;
- break;
- case Code.NoNode:
- exists = false;
- break;
- case Code.SessionExpired:
- case Code.NoAuth:
- dead = true;
- listener.closing(rc);
- return;
- default:
- // Retry errors
- zk.exists(znode, true, this, null);
- return;
- }
-
- byte b[] = null;
- if (exists) {
- try {
- <emphasis role="bold">b = zk.getData(znode, false, null);</emphasis>
- } catch (KeeperException e) {
- // We don't need to worry about recovering now. The watch
- // callbacks will kick off any exception handling
- e.printStackTrace();
- } catch (InterruptedException e) {
- return;
- }
- }
- if ((b == null && b != prevData)
- || (b != null && !Arrays.equals(prevData, b))) {
- <emphasis role="bold">listener.exists(b);</emphasis>
- prevData = b;
- }
-}
-</programlisting>
-
-<para>
-The code first checks the error codes for znode existence, fatal errors, and
-recoverable errors. If the file (or znode) exists, it gets the data from the znode, and
-then invoke the exists() callback of Executor if the state has changed. Note,
-it doesn't have to do any Exception processing for the getData call because it
-has watches pending for anything that could cause an error: if the node is deleted
-before it calls <command>ZooKeeper.getData()</command>, the watch event set by
-the <command>ZooKeeper.exists()</command> triggers a callback;
-if there is a communication error, a connection watch event fires when
-the connection comes back up.
-</para>
-
-<para>Finally, notice how DataMonitor processes watch events: </para>
-<programlisting>
- public void process(WatchedEvent event) {
- String path = event.getPath();
- if (event.getType() == Event.EventType.None) {
- // We are are being told that the state of the
- // connection has changed
- switch (event.getState()) {
- case SyncConnected:
- // 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
- dead = true;
- listener.closing(KeeperException.Code.SessionExpired);
- break;
- }
- } else {
- if (path != null && path.equals(znode)) {
- // Something has changed on the node, let's find out
- zk.exists(znode, true, this, null);
- }
- }
- if (chainedWatcher != null) {
- chainedWatcher.process(event);
- }
- }
-</programlisting>
-<para>
-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>
-
-<section id="sc_completeSourceCode">
- <title>Complete Source Listings</title>
- <example id="eg_Executor_java"><title>Executor.java</title><programlisting>
-/**
- * A simple example program to use DataMonitor to start and
- * stop executables based on a znode. The program watches the
- * specified znode and saves the data that corresponds to the
- * znode in the filesystem. It also starts the specified program
- * with the specified arguments when the znode exists and kills
- * the program if the znode goes away.
- */
-import java.io.FileOutputStream;
-import java.io.IOException;
-import java.io.InputStream;
-import java.io.OutputStream;
-
-import org.apache.zookeeper.KeeperException;
-import org.apache.zookeeper.WatchedEvent;
-import org.apache.zookeeper.Watcher;
-import org.apache.zookeeper.ZooKeeper;
-
-public class Executor
- implements Watcher, Runnable, DataMonitor.DataMonitorListener
-{
- String znode;
-
- DataMonitor dm;
-
- ZooKeeper zk;
-
- String filename;
-
- String exec[];
-
- Process child;
-
- public Executor(String hostPort, String znode, String filename,
- String exec[]) throws KeeperException, IOException {
- this.filename = filename;
- this.exec = exec;
- zk = new ZooKeeper(hostPort, 3000, this);
- dm = new DataMonitor(zk, znode, null, this);
- }
-
- /**
- * @param args
- */
- public static void main(String[] args) {
- if (args.length < 4) {
- System.err
- .println("USAGE: Executor hostPort znode filename program [args ...]");
- System.exit(2);
- }
- String hostPort = args[0];
- String znode = args[1];
- String filename = args[2];
- String exec[] = new String[args.length - 3];
- System.arraycopy(args, 3, exec, 0, exec.length);
- try {
- new Executor(hostPort, znode, filename, exec).run();
- } catch (Exception e) {
- e.printStackTrace();
- }
- }
-
- /***************************************************************************
- * We do process any events ourselves, we just need to forward them on.
- *
- * @see org.apache.zookeeper.Watcher#process(org.apache.zookeeper.proto.WatcherEvent)
- */
- public void process(WatchedEvent event) {
- dm.process(event);
- }
-
- public void run() {
- try {
- synchronized (this) {
- while (!dm.dead) {
- wait();
- }
- }
- } catch (InterruptedException e) {
- }
- }
-
- public void closing(int rc) {
- synchronized (this) {
- notifyAll();
- }
- }
-
- static class StreamWriter extends Thread {
- OutputStream os;
-
- InputStream is;
-
- StreamWriter(InputStream is, OutputStream os) {
- this.is = is;
- this.os = os;
- start();
- }
-
- public void run() {
- byte b[] = new byte[80];
- int rc;
- try {
- while ((rc = is.read(b)) > 0) {
- os.write(b, 0, rc);
- }
- } catch (IOException e) {
- }
-
- }
- }
-
- public void exists(byte[] data) {
- if (data == null) {
- if (child != null) {
- System.out.println("Killing process");
- child.destroy();
- try {
- child.waitFor();
- } catch (InterruptedException e) {
- }
- }
- child = null;
- } else {
- if (child != null) {
- System.out.println("Stopping child");
- child.destroy();
- try {
- child.waitFor();
- } catch (InterruptedException e) {
- e.printStackTrace();
- }
- }
- try {
- FileOutputStream fos = new FileOutputStream(filename);
- fos.write(data);
- fos.close();
- } catch (IOException e) {
- e.printStackTrace();
- }
- try {
- System.out.println("Starting child");
- child = Runtime.getRuntime().exec(exec);
- new StreamWriter(child.getInputStream(), System.out);
- new StreamWriter(child.getErrorStream(), System.err);
- } catch (IOException e) {
- e.printStackTrace();
- }
- }
- }
-}
-</programlisting>
-
-</example>
-
-<example id="eg_DataMonitor_java">
- <title>DataMonitor.java</title>
- <programlisting>
-/**
- * A simple class that monitors the data and existence of a ZooKeeper
- * node. It uses asynchronous ZooKeeper APIs.
- */
-import java.util.Arrays;
-
-import org.apache.zookeeper.KeeperException;
-import org.apache.zookeeper.WatchedEvent;
-import org.apache.zookeeper.Watcher;
-import org.apache.zookeeper.ZooKeeper;
-import org.apache.zookeeper.AsyncCallback.StatCallback;
-import org.apache.zookeeper.KeeperException.Code;
-import org.apache.zookeeper.data.Stat;
-
-public class DataMonitor implements Watcher, StatCallback {
-
- ZooKeeper zk;
-
- String znode;
-
- Watcher chainedWatcher;
-
- boolean dead;
-
- DataMonitorListener listener;
-
- byte prevData[];
-
- public DataMonitor(ZooKeeper zk, String znode, Watcher chainedWatcher,
- DataMonitorListener listener) {
- this.zk = zk;
- this.znode = znode;
- this.chainedWatcher = chainedWatcher;
- this.listener = listener;
- // Get things started by checking if the node exists. We are going
- // to be completely event driven
- zk.exists(znode, true, this, null);
- }
-
- /**
- * Other classes use the DataMonitor by implementing this method
- */
- public interface DataMonitorListener {
- /**
- * The existence status of the node has changed.
- */
- void exists(byte data[]);
-
- /**
- * The ZooKeeper session is no longer valid.
- *
- * @param rc
- * the ZooKeeper reason code
- */
- void closing(int rc);
- }
-
- public void process(WatchedEvent event) {
- String path = event.getPath();
- if (event.getType() == Event.EventType.None) {
- // We are are being told that the state of the
- // connection has changed
- switch (event.getState()) {
- case SyncConnected:
- // 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
- dead = true;
- listener.closing(KeeperException.Code.SessionExpired);
- break;
- }
- } else {
- if (path != null && path.equals(znode)) {
- // Something has changed on the node, let's find out
- zk.exists(znode, true, this, null);
- }
- }
- if (chainedWatcher != null) {
- chainedWatcher.process(event);
- }
- }
-
- public void processResult(int rc, String path, Object ctx, Stat stat) {
- boolean exists;
- switch (rc) {
- case Code.Ok:
- exists = true;
- break;
- case Code.NoNode:
- exists = false;
- break;
- case Code.SessionExpired:
- case Code.NoAuth:
- dead = true;
- listener.closing(rc);
- return;
- default:
- // Retry errors
- zk.exists(znode, true, this, null);
- return;
- }
-
- byte b[] = null;
- if (exists) {
- try {
- b = zk.getData(znode, false, null);
- } catch (KeeperException e) {
- // We don't need to worry about recovering now. The watch
- // callbacks will kick off any exception handling
- e.printStackTrace();
- } catch (InterruptedException e) {
- return;
- }
- }
- if ((b == null && b != prevData)
- || (b != null && !Arrays.equals(prevData, b))) {
- listener.exists(b);
- prevData = b;
- }
- }
-}
-</programlisting>
-</example>
-</section>
-
-
-
-</article>
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/c1efa954/src/docs/src/documentation/content/xdocs/recipes.xml
----------------------------------------------------------------------
diff --git a/src/docs/src/documentation/content/xdocs/recipes.xml b/src/docs/src/documentation/content/xdocs/recipes.xml
deleted file mode 100644
index ead041b..0000000
--- a/src/docs/src/documentation/content/xdocs/recipes.xml
+++ /dev/null
@@ -1,637 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
-"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd">
-<article id="ar_Recipes">
- <title>ZooKeeper Recipes and Solutions</title>
-
- <articleinfo>
- <legalnotice>
- <para>Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License. You may
- obtain a copy of the License at <ulink
- url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>.</para>
-
- <para>Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an "AS IS"
- BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
- implied. See the License for the specific language governing permissions
- and limitations under the License.</para>
- </legalnotice>
-
- <abstract>
- <para>This guide contains pseudocode and guidelines for using Zookeeper to
- solve common problems in Distributed Application Coordination. It
- discusses such problems as event handlers, queues, and locks..</para>
-
- <para>$Revision: 1.6 $ $Date: 2008/09/19 03:46:18 $</para>
- </abstract>
- </articleinfo>
-
- <section id="ch_recipes">
- <title>A Guide to Creating Higher-level Constructs with ZooKeeper</title>
-
- <para>In this article, you'll find guidelines for using
- ZooKeeper to implement higher order functions. All of them are conventions
- implemented at the client and do not require special support from
- ZooKeeper. Hopfully the community will capture these conventions in client-side libraries
- to ease their use and to encourage standardization.</para>
-
- <para>One of the most interesting things about ZooKeeper is that even
- though ZooKeeper uses <emphasis>asynchronous</emphasis> notifications, you
- can use it to build <emphasis>synchronous</emphasis> consistency
- primitives, such as queues and locks. As you will see, this is possible
- because ZooKeeper imposes an overall order on updates, and has mechanisms
- to expose this ordering.</para>
-
- <para>Note that the recipes below attempt to employ best practices. In
- particular, they avoid polling, timers or anything else that would result
- in a "herd effect", causing bursts of traffic and limiting
- scalability.</para>
-
- <para>There are many useful functions that can be imagined that aren't
- included here - revocable read-write priority locks, as just one example.
- And some of the constructs mentioned here - locks, in particular -
- illustrate certain points, even though you may find other constructs, such
- as event handles or queues, a more practical means of performing the same
- function. In general, the examples in this section are designed to
- stimulate thought.</para>
-
-
- <section id="sc_outOfTheBox">
- <title>Out of the Box Applications: Name Service, Configuration, Group
- Membership</title>
-
- <para>Name service and configuration are two of the primary applications
- of ZooKeeper. These two functions are provided directly by the ZooKeeper
- API.</para>
-
- <para>Another function directly provided by ZooKeeper is <emphasis>group
- membership</emphasis>. The group is represented by a node. Members of the
- group create ephemeral nodes under the group node. Nodes of the members
- that fail abnormally will be removed automatically when ZooKeeper detects
- the failure.</para>
- </section>
-
- <section id="sc_recipes_eventHandles">
- <title>Barriers</title>
-
- <para>Distributed systems use <emphasis>barriers</emphasis>
- to block processing of a set of nodes until a condition is met
- at which time all the nodes are allowed to proceed. Barriers are
- implemented in ZooKeeper by designating a barrier node. The
- barrier is in place if the barrier node exists. Here's the
- pseudo code:</para>
-
- <orderedlist>
- <listitem>
- <para>Client calls the ZooKeeper API's <emphasis
- role="bold">exists()</emphasis> function on the barrier node, with
- <emphasis>watch</emphasis> set to true.</para>
- </listitem>
-
- <listitem>
- <para>If <emphasis role="bold">exists()</emphasis> returns false, the
- barrier is gone and the client proceeds</para>
- </listitem>
-
- <listitem>
- <para>Else, if <emphasis role="bold">exists()</emphasis> returns true,
- the clients wait for a watch event from ZooKeeper for the barrier
- node.</para>
- </listitem>
-
- <listitem>
- <para>When the watch event is triggered, the client reissues the
- <emphasis role="bold">exists( )</emphasis> call, again waiting until
- the barrier node is removed.</para>
- </listitem>
- </orderedlist>
-
- <section id="sc_doubleBarriers">
- <title>Double Barriers</title>
-
- <para>Double barriers enable clients to synchronize the beginning and
- the end of a computation. When enough processes have joined the barrier,
- processes start their computation and leave the barrier once they have
- finished. This recipe shows how to use a ZooKeeper node as a
- barrier.</para>
-
- <para>The pseudo code in this recipe represents the barrier node as
- <emphasis>b</emphasis>. Every client process <emphasis>p</emphasis>
- registers with the barrier node on entry and unregisters when it is
- ready to leave. A node registers with the barrier node via the <emphasis
- role="bold">Enter</emphasis> procedure below, it waits until
- <emphasis>x</emphasis> client process register before proceeding with
- the computation. (The <emphasis>x</emphasis> here is up to you to
- determine for your system.)</para>
-
- <informaltable colsep="0" frame="none" rowsep="0">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry align="center"><emphasis
- role="bold">Enter</emphasis></entry>
-
- <entry align="center"><emphasis
- role="bold">Leave</emphasis></entry>
- </row>
-
- <row>
- <entry align="left"><orderedlist>
- <listitem>
- <para>Create a name <emphasis><emphasis>n</emphasis> =
- <emphasis>b</emphasis>+“/”+<emphasis>p</emphasis></emphasis></para>
- </listitem>
-
- <listitem>
- <para>Set watch: <emphasis
- role="bold">exists(<emphasis>b</emphasis> + ‘‘/ready’’,
- true)</emphasis></para>
- </listitem>
-
- <listitem>
- <para>Create child: <emphasis role="bold">create(
- <emphasis>n</emphasis>, EPHEMERAL)</emphasis></para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">L = getChildren(b,
- false)</emphasis></para>
- </listitem>
-
- <listitem>
- <para>if fewer children in L than<emphasis>
- x</emphasis>, wait for watch event</para>
- </listitem>
-
- <listitem>
- <para>else <emphasis role="bold">create(b + ‘‘/ready’’,
- REGULAR)</emphasis></para>
- </listitem>
- </orderedlist></entry>
-
- <entry><orderedlist>
- <listitem>
- <para><emphasis role="bold">L = getChildren(b,
- false)</emphasis></para>
- </listitem>
-
- <listitem>
- <para>if no children, exit</para>
- </listitem>
-
- <listitem>
- <para>if <emphasis>p</emphasis> is only process node in
- L, delete(n) and exit</para>
- </listitem>
-
- <listitem>
- <para>if <emphasis>p</emphasis> is the lowest process
- node in L, wait on highest process node in L</para>
- </listitem>
-
- <listitem>
- <para>else <emphasis
- role="bold">delete(<emphasis>n</emphasis>) </emphasis>if
- still exists and wait on lowest process node in L</para>
- </listitem>
-
- <listitem>
- <para>goto 1</para>
- </listitem>
- </orderedlist></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>On entering, all processes watch on a ready node and
- create an ephemeral node as a child of the barrier node. Each process
- but the last enters the barrier and waits for the ready node to appear
- at line 5. The process that creates the xth node, the last process, will
- see x nodes in the list of children and create the ready node, waking up
- the other processes. Note that waiting processes wake up only when it is
- time to exit, so waiting is efficient.
- </para>
-
- <para>On exit, you can't use a flag such as <emphasis>ready</emphasis>
- because you are watching for process nodes to go away. By using
- ephemeral nodes, processes that fail after the barrier has been entered
- do not prevent correct processes from finishing. When processes are
- ready to leave, they need to delete their process nodes and wait for all
- other processes to do the same.</para>
-
- <para>Processes exit when there are no process nodes left as children of
- <emphasis>b</emphasis>. However, as an efficiency, you can use the
- lowest process node as the ready flag. All other processes that are
- ready to exit watch for the lowest existing process node to go away, and
- the owner of the lowest process watches for any other process node
- (picking the highest for simplicity) to go away. This means that only a
- single process wakes up on each node deletion except for the last node,
- which wakes up everyone when it is removed.</para>
- </section>
- </section>
-
- <section id="sc_recipes_Queues">
- <title>Queues</title>
-
- <para>Distributed queues are a common data structure. To implement a
- distributed queue in ZooKeeper, first designate a znode to hold the queue,
- the queue node. The distributed clients put something into the queue by
- calling create() with a pathname ending in "queue-", with the
- <emphasis>sequence</emphasis> and <emphasis>ephemeral</emphasis> flags in
- the create() call set to true. Because the <emphasis>sequence</emphasis>
- flag is set, the new pathnames will have the form
- _path-to-queue-node_/queue-X, where X is a monotonic increasing number. A
- client that wants to be removed from the queue calls ZooKeeper's <emphasis
- role="bold">getChildren( )</emphasis> function, with
- <emphasis>watch</emphasis> set to true on the queue node, and begins
- processing nodes with the lowest number. The client does not need to issue
- another <emphasis role="bold">getChildren( )</emphasis> until it exhausts
- the list obtained from the first <emphasis role="bold">getChildren(
- )</emphasis> call. If there are are no children in the queue node, the
- reader waits for a watch notification to check the queue again.</para>
-
- <note>
- <para>There now exists a Queue implementation in ZooKeeper
- recipes directory. This is distributed with the release --
- src/recipes/queue directory of the release artifact.
- </para>
- </note>
-
- <section id="sc_recipes_priorityQueues">
- <title>Priority Queues</title>
-
- <para>To implement a priority queue, you need only make two simple
- changes to the generic <ulink url="#sc_recipes_Queues">queue
- recipe</ulink> . First, to add to a queue, the pathname ends with
- "queue-YY" where YY is the priority of the element with lower numbers
- representing higher priority (just like UNIX). Second, when removing
- from the queue, a client uses an up-to-date children list meaning that
- the client will invalidate previously obtained children lists if a watch
- notification triggers for the queue node.</para>
- </section>
- </section>
-
- <section id="sc_recipes_Locks">
- <title>Locks</title>
-
- <para>Fully distributed locks that are globally synchronous, meaning at
- any snapshot in time no two clients think they hold the same lock. These
- can be implemented using ZooKeeeper. As with priority queues, first define
- a lock node.</para>
-
- <note>
- <para>There now exists a Lock implementation in ZooKeeper
- recipes directory. This is distributed with the release --
- src/recipes/lock directory of the release artifact.
- </para>
- </note>
-
- <para>Clients wishing to obtain a lock do the following:</para>
-
- <orderedlist>
- <listitem>
- <para>Call <emphasis role="bold">create( )</emphasis> with a pathname
- of "_locknode_/lock-" and the <emphasis>sequence</emphasis> and
- <emphasis>ephemeral</emphasis> flags set.</para>
- </listitem>
-
- <listitem>
- <para>Call <emphasis role="bold">getChildren( )</emphasis> on the lock
- node <emphasis>without</emphasis> setting the watch flag (this is
- important to avoid the herd effect).</para>
- </listitem>
-
- <listitem>
- <para>If the pathname created in step <emphasis
- role="bold">1</emphasis> has the lowest sequence number suffix, the
- client has the lock and the client exits the protocol.</para>
- </listitem>
-
- <listitem>
- <para>The client calls <emphasis role="bold">exists( )</emphasis> with
- the watch flag set on the path in the lock directory with the next
- lowest sequence number.</para>
- </listitem>
-
- <listitem>
- <para>if <emphasis role="bold">exists( )</emphasis> returns false, go
- to step <emphasis role="bold">2</emphasis>. Otherwise, wait for a
- notification for the pathname from the previous step before going to
- step <emphasis role="bold">2</emphasis>.</para>
- </listitem>
- </orderedlist>
-
- <para>The unlock protocol is very simple: clients wishing to release a
- lock simply delete the node they created in step 1.</para>
-
- <para>Here are a few things to notice:</para>
-
- <itemizedlist>
- <listitem>
- <para>The removal of a node will only cause one client to wake up
- since each node is watched by exactly one client. In this way, you
- avoid the herd effect.</para>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>There is no polling or timeouts.</para>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>Because of the way you implement locking, it is easy to see the
- amount of lock contention, break locks, debug locking problems,
- etc.</para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Shared Locks</title>
-
- <para>You can implement shared locks by with a few changes to the lock
- protocol:</para>
-
- <informaltable colsep="0" frame="none" rowsep="0">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry align="center"><emphasis role="bold">Obtaining a read
- lock:</emphasis></entry>
-
- <entry align="center"><emphasis role="bold">Obtaining a write
- lock:</emphasis></entry>
- </row>
-
- <row>
- <entry align="left"><orderedlist>
- <listitem>
- <para>Call <emphasis role="bold">create( )</emphasis> to
- create a node with pathname
- "<filename>_locknode_/read-</filename>". This is the
- lock node use later in the protocol. Make sure to set both
- the <emphasis>sequence</emphasis> and
- <emphasis>ephemeral</emphasis> flags.</para>
- </listitem>
-
- <listitem>
- <para>Call <emphasis role="bold">getChildren( )</emphasis>
- on the lock node <emphasis>without</emphasis> setting the
- <emphasis>watch</emphasis> flag - this is important, as it
- avoids the herd effect.</para>
- </listitem>
-
- <listitem>
- <para>If there are no children with a pathname starting
- with "<filename>write-</filename>" and having a lower
- sequence number than the node created in step <emphasis
- role="bold">1</emphasis>, the client has the lock and can
- exit the protocol. </para>
- </listitem>
-
- <listitem>
- <para>Otherwise, call <emphasis role="bold">exists(
- )</emphasis>, with <emphasis>watch</emphasis> flag, set on
- the node in lock directory with pathname staring with
- "<filename>write-</filename>" having the next lowest
- sequence number.</para>
- </listitem>
-
- <listitem>
- <para>If <emphasis role="bold">exists( )</emphasis>
- returns <emphasis>false</emphasis>, goto step <emphasis
- role="bold">2</emphasis>.</para>
- </listitem>
-
- <listitem>
- <para>Otherwise, wait for a notification for the pathname
- from the previous step before going to step <emphasis
- role="bold">2</emphasis></para>
- </listitem>
- </orderedlist></entry>
-
- <entry><orderedlist>
- <listitem>
- <para>Call <emphasis role="bold">create( )</emphasis> to
- create a node with pathname
- "<filename>_locknode_/write-</filename>". This is the
- lock node spoken of later in the protocol. Make sure to
- set both <emphasis>sequence</emphasis> and
- <emphasis>ephemeral</emphasis> flags.</para>
- </listitem>
-
- <listitem>
- <para>Call <emphasis role="bold">getChildren( )
- </emphasis> on the lock node <emphasis>without</emphasis>
- setting the <emphasis>watch</emphasis> flag - this is
- important, as it avoids the herd effect.</para>
- </listitem>
-
- <listitem>
- <para>If there are no children with a lower sequence
- number than the node created in step <emphasis
- role="bold">1</emphasis>, the client has the lock and the
- client exits the protocol.</para>
- </listitem>
-
- <listitem>
- <para>Call <emphasis role="bold">exists( ),</emphasis>
- with <emphasis>watch</emphasis> flag set, on the node with
- the pathname that has the next lowest sequence
- number.</para>
- </listitem>
-
- <listitem>
- <para>If <emphasis role="bold">exists( )</emphasis>
- returns <emphasis>false</emphasis>, goto step <emphasis
- role="bold">2</emphasis>. Otherwise, wait for a
- notification for the pathname from the previous step
- before going to step <emphasis
- role="bold">2</emphasis>.</para>
- </listitem>
- </orderedlist></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <note>
- <para>It might appear that this recipe creates a herd effect:
- when there is a large group of clients waiting for a read
- lock, and all getting notified more or less simultaneously
- when the "<filename>write-</filename>" node with the lowest
- sequence number is deleted. In fact. that's valid behavior:
- as all those waiting reader clients should be released since
- they have the lock. The herd effect refers to releasing a
- "herd" when in fact only a single or a small number of
- machines can proceed.
- </para>
- </note>
- </section>
-
- <section id="sc_recoverableSharedLocks">
- <title>Recoverable Shared Locks</title>
-
- <para>With minor modifications to the Shared Lock protocol, you make
- shared locks revocable by modifying the shared lock protocol:</para>
-
- <para>In step <emphasis role="bold">1</emphasis>, of both obtain reader
- and writer lock protocols, call <emphasis role="bold">getData(
- )</emphasis> with <emphasis>watch</emphasis> set, immediately after the
- call to <emphasis role="bold">create( )</emphasis>. If the client
- subsequently receives notification for the node it created in step
- <emphasis role="bold">1</emphasis>, it does another <emphasis
- role="bold">getData( )</emphasis> on that node, with
- <emphasis>watch</emphasis> set and looks for the string "unlock", which
- signals to the client that it must release the lock. This is because,
- according to this shared lock protocol, you can request the client with
- the lock give up the lock by calling <emphasis role="bold">setData()
- </emphasis> on the lock node, writing "unlock" to that node.</para>
-
- <para>Note that this protocol requires the lock holder to consent to
- releasing the lock. Such consent is important, especially if the lock
- holder needs to do some processing before releasing the lock. Of course
- you can always implement <emphasis>Revocable Shared Locks with Freaking
- Laser Beams</emphasis> by stipulating in your protocol that the revoker
- is allowed to delete the lock node if after some length of time the lock
- isn't deleted by the lock holder.</para>
- </section>
- </section>
-
- <section id="sc_recipes_twoPhasedCommit">
- <title>Two-phased Commit</title>
-
- <para>A two-phase commit protocol is an algorithm that lets all clients in
- a distributed system agree either to commit a transaction or abort.</para>
-
- <para>In ZooKeeper, you can implement a two-phased commit by having a
- coordinator create a transaction node, say "/app/Tx", and one child node
- per participating site, say "/app/Tx/s_i". When coordinator creates the
- child node, it leaves the content undefined. Once each site involved in
- the transaction receives the transaction from the coordinator, the site
- reads each child node and sets a watch. Each site then processes the query
- and votes "commit" or "abort" by writing to its respective node. Once the
- write completes, the other sites are notified, and as soon as all sites
- have all votes, they can decide either "abort" or "commit". Note that a
- node can decide "abort" earlier if some site votes for "abort".</para>
-
- <para>An interesting aspect of this implementation is that the only role
- of the coordinator is to decide upon the group of sites, to create the
- ZooKeeper nodes, and to propagate the transaction to the corresponding
- sites. In fact, even propagating the transaction can be done through
- ZooKeeper by writing it in the transaction node.</para>
-
- <para>There are two important drawbacks of the approach described above.
- One is the message complexity, which is O(n²). The second is the
- impossibility of detecting failures of sites through ephemeral nodes. To
- detect the failure of a site using ephemeral nodes, it is necessary that
- the site create the node.</para>
-
- <para>To solve the first problem, you can have only the coordinator
- notified of changes to the transaction nodes, and then notify the sites
- once coordinator reaches a decision. Note that this approach is scalable,
- but it's is slower too, as it requires all communication to go through the
- coordinator.</para>
-
- <para>To address the second problem, you can have the coordinator
- propagate the transaction to the sites, and have each site creating its
- own ephemeral node.</para>
- </section>
-
- <section id="sc_leaderElection">
- <title>Leader Election</title>
-
- <para>A simple way of doing leader election with ZooKeeper is to use the
- <emphasis role="bold">SEQUENCE|EPHEMERAL</emphasis> flags when creating
- znodes that represent "proposals" of clients. The idea is to have a znode,
- say "/election", such that each znode creates a child znode "/election/n_"
- with both flags SEQUENCE|EPHEMERAL. With the sequence flag, ZooKeeper
- automatically appends a sequence number that is greater that any one
- previously appended to a child of "/election". The process that created
- the znode with the smallest appended sequence number is the leader.
- </para>
-
- <para>That's not all, though. It is important to watch for failures of the
- leader, so that a new client arises as the new leader in the case the
- current leader fails. A trivial solution is to have all application
- processes watching upon the current smallest znode, and checking if they
- are the new leader when the smallest znode goes away (note that the
- smallest znode will go away if the leader fails because the node is
- ephemeral). But this causes a herd effect: upon of failure of the current
- leader, all other processes receive a notification, and execute
- getChildren on "/election" to obtain the current list of children of
- "/election". If the number of clients is large, it causes a spike on the
- number of operations that ZooKeeper servers have to process. To avoid the
- herd effect, it is sufficient to watch for the next znode down on the
- sequence of znodes. If a client receives a notification that the znode it
- is watching is gone, then it becomes the new leader in the case that there
- is no smaller znode. Note that this avoids the herd effect by not having
- all clients watching the same znode. </para>
-
- <para>Here's the pseudo code:</para>
-
- <para>Let ELECTION be a path of choice of the application. To volunteer to
- be a leader: </para>
-
- <orderedlist>
- <listitem>
- <para>Create znode z with path "ELECTION/n_" with both SEQUENCE and
- EPHEMERAL flags;</para>
- </listitem>
-
- <listitem>
- <para>Let C be the children of "ELECTION", and i be the sequence
- number of z;</para>
- </listitem>
-
- <listitem>
- <para>Watch for changes on "ELECTION/n_j", where j is the largest
- sequence number such that j < i and n_j is a znode in C;</para>
- </listitem>
- </orderedlist>
-
- <para>Upon receiving a notification of znode deletion: </para>
-
- <orderedlist>
- <listitem>
- <para>Let C be the new set of children of ELECTION; </para>
- </listitem>
-
- <listitem>
- <para>If z is the smallest node in C, then execute leader
- procedure;</para>
- </listitem>
-
- <listitem>
- <para>Otherwise, watch for changes on "ELECTION/n_j", where j is the
- largest sequence number such that j < i and n_j is a znode in C;
- </para>
- </listitem>
- </orderedlist>
-
- <para>Note that the znode having no preceding znode on the list of
- children does not imply that the creator of this znode is aware that it is
- the current leader. Applications may consider creating a separate znode
- to acknowledge that the leader has executed the leader procedure. </para>
- </section>
- </section>
-</article>
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/c1efa954/src/docs/src/documentation/content/xdocs/site.xml
----------------------------------------------------------------------
diff --git a/src/docs/src/documentation/content/xdocs/site.xml b/src/docs/src/documentation/content/xdocs/site.xml
deleted file mode 100644
index e49d92c..0000000
--- a/src/docs/src/documentation/content/xdocs/site.xml
+++ /dev/null
@@ -1,103 +0,0 @@
-<?xml version="1.0"?>
-<!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<!--
-Forrest site.xml
-
-This file contains an outline of the site's information content. It is used to:
-- Generate the website menus (though these can be overridden - see docs)
-- Provide semantic, location-independent aliases for internal 'site:' URIs, eg
-<link href="site:changes"> links to changes.html (or ../changes.html if in
- subdir).
-- Provide aliases for external URLs in the external-refs section. Eg, <link
- href="ext:cocoon"> links to http://xml.apache.org/cocoon/
-
-See http://forrest.apache.org/docs/linking.html for more info.
--->
-
-<site label="ZooKeeper" href="" xmlns="http://apache.org/forrest/linkmap/1.0">
-
- <docs label="Overview">
- <welcome label="Welcome" href="index.html" />
- <overview label="Overview" href="zookeeperOver.html" />
- <started label="Getting Started" href="zookeeperStarted.html" />
- <relnotes label="Release Notes" href="ext:relnotes" />
- </docs>
-
- <docs label="Developer">
- <api label="API Docs" href="ext:api/index" />
- <program label="Programmer's Guide" href="zookeeperProgrammers.html" />
- <javaEx label="Java Example" href="javaExample.html" />
- <barTutor label="Barrier and Queue Tutorial" href="zookeeperTutorial.html" />
- <recipes label="Recipes" href="recipes.html" />
- </docs>
-
- <docs label="BookKeeper">
- <bkStarted label="Getting started" href="bookkeeperStarted.html" />
- <bkOverview label="Overview" href="bookkeeperOverview.html" />
- <bkProgrammer label="Setup guide" href="bookkeeperConfig.html" />
- <bkProgrammer label="Programmer's guide" href="bookkeeperProgrammer.html" />
- </docs>
-
- <docs label="Admin & Ops">
- <admin label="Administrator's Guide" href="zookeeperAdmin.html" />
- <quota label="Quota Guide" href="zookeeperQuotas.html" />
- <jmx label="JMX" href="zookeeperJMX.html" />
- <observers label="Observers Guide" href="zookeeperObservers.html" />
- </docs>
-
- <docs label="Contributor">
- <internals label="ZooKeeper Internals" href="zookeeperInternals.html" />
- </docs>
-
- <docs label="Miscellaneous">
- <wiki label="Wiki" href="ext:wiki" />
- <faq label="FAQ" href="ext:faq" />
- <lists label="Mailing Lists" href="ext:lists" />
- <!--<other label="Other Info" href="zookeeperOtherInfo.html" />-->
- </docs>
-
-
-
- <external-refs>
- <site href="http://zookeeper.apache.org/"/>
- <lists href="http://zookeeper.apache.org/mailing_lists.html"/>
- <releases href="http://zookeeper.apache.org/releases.html">
- <download href="#Download" />
- </releases>
- <jira href="http://zookeeper.apache.org/issue_tracking.html"/>
- <wiki href="https://cwiki.apache.org/confluence/display/ZOOKEEPER" />
- <faq href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/FAQ" />
- <zlib href="http://www.zlib.net/" />
- <lzo href="http://www.oberhumer.com/opensource/lzo/" />
- <gzip href="http://www.gzip.org/" />
- <cygwin href="http://www.cygwin.com/" />
- <osx href="http://www.apple.com/macosx" />
- <relnotes href="releasenotes.html" />
- <api href="api/">
- <started href="overview-summary.html#overview_description" />
- <index href="index.html" />
- <org href="org/">
- <apache href="apache/">
- <zookeeper href="zookeeper/">
- </zookeeper>
- </apache>
- </org>
- </api>
- </external-refs>
-
-</site>
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/c1efa954/src/docs/src/documentation/content/xdocs/tabs.xml
----------------------------------------------------------------------
diff --git a/src/docs/src/documentation/content/xdocs/tabs.xml b/src/docs/src/documentation/content/xdocs/tabs.xml
deleted file mode 100644
index aef7e59..0000000
--- a/src/docs/src/documentation/content/xdocs/tabs.xml
+++ /dev/null
@@ -1,36 +0,0 @@
-<?xml version="1.0"?>
-<!--
- Copyright 2002-2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
-<!DOCTYPE tabs PUBLIC "-//APACHE//DTD Cocoon Documentation Tab V1.0//EN"
- "http://forrest.apache.org/dtd/tab-cocoon-v10.dtd">
-
-<tabs software="ZooKeeper"
- title="ZooKeeper"
- copyright="The Apache Software Foundation"
- xmlns:xlink="http://www.w3.org/1999/xlink">
-
- <!-- The rules are:
- @dir will always have /index.html added.
- @href is not modified unless it is root-relative and obviously specifies a
- directory (ends in '/'), in which case /index.html will be added
- -->
-
- <tab label="Project" href="http://zookeeper.apache.org/" />
- <tab label="Wiki" href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/" />
- <tab label="ZooKeeper 3.4 Documentation" dir="" />
-
-</tabs>