You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@curator.apache.org by ra...@apache.org on 2013/03/27 02:11:11 UTC
[16/52] [abbrv] git commit: site wip
site wip
Project: http://git-wip-us.apache.org/repos/asf/incubator-curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-curator/commit/327b89e3
Tree: http://git-wip-us.apache.org/repos/asf/incubator-curator/tree/327b89e3
Diff: http://git-wip-us.apache.org/repos/asf/incubator-curator/diff/327b89e3
Branch: refs/heads/master
Commit: 327b89e3bc5f2ac35f06483ee2ecfdf9ffa14bd1
Parents: f2513a0
Author: Jordan Zimmerman <jo...@jordanzimmerman.com>
Authored: Sat Mar 9 19:53:16 2013 -0800
Committer: Jordan Zimmerman <jo...@jordanzimmerman.com>
Committed: Sat Mar 9 19:53:16 2013 -0800
----------------------------------------------------------------------
.../src/site/confluence/index.confluence | 73 +++++++++
curator-client/src/site/resources/css/site.css | 4 +
curator-client/src/site/site.xml | 27 ++++
.../src/site/confluence/index.confluence | 121 +++++++++++++++
curator-framework/src/site/resources/css/site.css | 4 +
curator-framework/src/site/site.xml | 27 ++++
curator-recipes/src/site/site.xml | 4 -
pom.xml | 1 +
src/site/apt/index.apt | 74 ---------
src/site/confluence/errors.confluence | 35 ++++
src/site/confluence/index.confluence | 33 ++++
src/site/confluence/utilities.confluence | 59 +++++++
src/site/site.xml | 14 ++-
13 files changed, 396 insertions(+), 80 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/curator-client/src/site/confluence/index.confluence
----------------------------------------------------------------------
diff --git a/curator-client/src/site/confluence/index.confluence b/curator-client/src/site/confluence/index.confluence
new file mode 100644
index 0000000..7d827db
--- /dev/null
+++ b/curator-client/src/site/confluence/index.confluence
@@ -0,0 +1,73 @@
+h1. Client
+
+h2. IMPORTANT NOTE
+The Curator Client is a low-level API. It is strongly recommended that you use the Curator [[Framework|../curator-framework/index.html]]
+instead of directly using CuratorZookeeperClient.
+
+h2. Background
+CuratorZookeeperClient is a wrapper around ZooKeeper's Java client that makes client access to ZooKeeper much simpler and
+less error prone. It provides the following features:
+
+* Continuous connection management - ZooKeeper has many caveats regarding connection management (see the ZooKeeper FAQ for
+details). CuratorZookeeperClient takes care of most of them automatically.
+
+* Operation retry utilities - a method for retrying operations is provided
+* Test ZooKeeper server - an in-process, self-contained ZooKeeper test server is provided that can be used for test cases and experimentation
+
+h2. Method Documentation
+||Method||Description||
+|_Constructor_|Create a connection to a given ZooKeeper cluster. You can pass in an optional watcher. You must provide a Retry Policy.|
+|getZooKeeper()|Returns the managed ZooKeeper instance. *IMPORTANT NOTES:* a) It takes time for a connection to complete, you should validate that the connection is complete before using other methods. b) The managed ZooKeeper instance can change due to certain events. Do not hold on to the instance for long periods. Always get a fresh reference from getZooKeeper().|
+|isConnected()|Returns true if the ZooKeeper client is currently connected (this can always change due to errors)|
+|blockUntilConnectedOrTimedOut()|A convenience method that blocks until the initial connection is successful or times out|
+|close()|Close the connection|
+|setRetryPolicy()|Change the retry policy|
+|newRetryLoop()|Allocate a new Retry Loop - see details below|
+
+h2. Retry Loop
+For a variety of reasons, operations on a ZooKeeper cluster can fail. Best practices dictate that these operations should be retried. The Retry Loop mechanism provides the means to do this. <b>Every operation should be wrapped in a retry loop</b>. Here's the canonical usage:
+{code}
+RetryLoop retryLoop = client.newRetryLoop();
+while ( retryLoop.shouldContinue() )
+{
+ try
+ {
+ // perform your work
+ ...
+ // it's important to re-get the ZK instance as there may have been an error and the instance was re-created
+ ZooKeeper zk = client.getZookeeper();
+ retryLoop.markComplete();
+ }
+ catch ( Exception e )
+ {
+ retryLoop.takeException(e);
+ }
+}
+{code}
+
+The Retry Loop maintains a count of retries and determines if a given error is retry-able. If an operation is a candidate for retrying, the Retry Policy is invoked to determine if the retry should proceed.
+
+As a convenience, RetryLoop has a static method that takes a Callable to perform a complete retry loop on. E.g.
+{code}
+RetryLoop.callWithRetry(client, new Callable<Void>()
+{
+ @Override
+ public Void call() throws Exception
+ {
+ // do your work here - it will get retried if needed
+ return null;
+ }
+});
+{code}
+
+h2. Retry Policies
+A retry policy is a mechanism to alter retry behavior. It is abstracted by the RetryPolicy interface which has one method:
+{{public boolean allowRetry(int retryCount, long elapsedTimeMs);}}
+Before a retry is attempted, allowRetry() is called with the current retry count and the elapsed time of the operation. If the policy allows it, the retry is attempted. If not, an exception is thrown.
+
+Several retry policy implementations are provided (in the package {{com.netflix.curator.retry}}):
+||Policy Name||Description||
+|ExponentialBackoffRetry|Retry policy that retries a set number of times with increasing sleep time between retries|
+|RetryNTimes|Retry policy that retries a max number of times|
+|RetryOneTime|A retry policy that retries only once|
+|RetryUntilElapsed|A retry policy that retries until a given amount of time elapses|
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/curator-client/src/site/resources/css/site.css
----------------------------------------------------------------------
diff --git a/curator-client/src/site/resources/css/site.css b/curator-client/src/site/resources/css/site.css
new file mode 100644
index 0000000..f847d66
--- /dev/null
+++ b/curator-client/src/site/resources/css/site.css
@@ -0,0 +1,4 @@
+tt
+{
+ background-color: transparent;
+}
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/curator-client/src/site/site.xml
----------------------------------------------------------------------
diff --git a/curator-client/src/site/site.xml b/curator-client/src/site/site.xml
new file mode 100644
index 0000000..becd75d
--- /dev/null
+++ b/curator-client/src/site/site.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?><!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ -->
+
+<project xmlns="http://maven.apache.org/DECORATION/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/DECORATION/1.1.0 http://maven.apache.org/xsd/decoration-1.1.0.xsd" name="Apache Curator Client">
+ <body>
+ <breadcrumbs>
+ <item name="Home" href="../index.html"/>
+ <item name="Client" href="index.html"/>
+ </breadcrumbs>
+ </body>
+</project>
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/curator-framework/src/site/confluence/index.confluence
----------------------------------------------------------------------
diff --git a/curator-framework/src/site/confluence/index.confluence b/curator-framework/src/site/confluence/index.confluence
new file mode 100644
index 0000000..1a63c15
--- /dev/null
+++ b/curator-framework/src/site/confluence/index.confluence
@@ -0,0 +1,121 @@
+h1. Framework
+
+h2. Introducing Curator Framework
+The Curator Framework is a high-level API that greatly simplifies using ZooKeeper. It adds many features that build on
+ZooKeeper and handles the complexity of managing connections to the ZooKeeper cluster and retrying operations. Some of the features are:
+
+* Automatic connection management:
+** There are potential error cases that require ZooKeeper clients to recreate a connection and/or retry operations. Curator
+ automatically and transparently (mostly) handles these cases.
+* Cleaner API:
+** simplifies the raw ZooKeeper methods, events, etc.
+** provides a modern, fluent interface
+* Recipe implementations (see [[Recipes|../curator-recipes/index.html]]):
+** Leader election
+** Shared lock
+** Path cache and watcher
+** Distributed Queue
+** Distributed Priority Queue
+** ...
+
+h2. Allocating a Curator Framework Instance
+CuratorFrameworks are allocated using the CuratorFrameworkFactory which provides both factory methods and a builder for
+creating instances. IMPORTANT: CuratorFramework instances are fully thread-safe. You should share one CuratorFramework per
+ZooKeeper cluster in your application.
+
+The factory methods (newClient()) provide a simplified way of creating an instance. The Builder gives control over all
+parameters. Once you have a CuratorFramework instance, you must call the start() method. At the end of your application, you should call close().
+
+h2. CuratorFramework API
+The CuratorFramework uses a Fluent-style interface. Operations are constructed using builders returned by the CuratorFramework
+instance. When strung together, the methods form sentence-like statements. e.g.
+{code}
+client.create().forPath("/head", new byte[0]);
+client.delete().inBackground().forPath("/head");
+client.create().withMode(CreateMode.EPHEMERAL_SEQUENTIAL).forPath("/head/child", new byte[0]);
+client.getData().watched().inBackground().forPath("/test");
+{code}
+
+h3. Methods
+|create()|Begins a create operation. Call additional methods (mode or background) and finalize the operation by calling forPath()|
+|delete()|Begins a delete operation. Call additional methods (version or background) and finalize the operation by calling forPath()|
+|checkExists()|Begins an operation to check that a ZNode exists. Call additional methods (watch or background) and finalize the operation by calling forPath()|
+|getData()|Begins an operation to get a ZNode's data. Call additional methods (watch, background or get stat) and finalize the operation by calling forPath()|
+|setData()|Begins an operation to set a ZNode's data. Call additional methods (version or background) and finalize the operation by calling forPath()|
+|getChildren()|Begins an operation to get a ZNode's list of children ZNodes. Call additional methods (watch, background or get stat) and finalize the operation by calling forPath()|
+|inTransaction()|Begins an atomic ZooKeeper transaction. Combine create, setData, check, and/or delete operations and then commit() as a unit.|
+
+h3. Notifications
+Notifications for background operations and watches are published via the ClientListener interface. You register listeners with the
+CuratorFramework instance using the addListener() method. The listener implements two methods:
+
+|eventReceived()|A background operation has completed or a watch has triggered. Examine the given event for details|
+<td>clientClosedDueToError()|An unrecoverable error has occurred. The CuratorFramework instance has been shut down|
+
+h3. ClientEvent
+The ClientEvent object is a super-set POJO that can hold every type of background notification and triggered watch. The useful fields of
+ClientEvent depend on the type of event which is exposed via the getType() method.
+
+||Event Type||Event Methods||
+|CREATE|getResultCode() and getPath()|
+|DELETE|getResultCode() and getPath()|
+|EXISTS|getResultCode(), getPath() and getStat()|
+|GET_DATA|getResultCode(), getPath(), getStat() and getData()|
+|SET_DATA|getResultCode(), getPath() and getStat()|
+|CHILDREN|getResultCode(), getPath(), getStat(), getChildren()|
+|WATCHED|getWatchedEvent()|
+
+h2. Namespaces
+Because a ZooKeeper cluster is a shared environment, it's vital that a namespace convention is
+observed so that various applications that use a given cluster don't use conflicting ZK paths.
+
+The CuratorFramework has a concept of a "namespace". You set the namespace when creating a CuratorFramework
+instance (via the Builder). The CuratorFramework will then prepend the namespace to all paths when one of its APIs is called. i.e.
+{code}
+CuratorFramework client = CuratorFrameworkFactory.builder().namespace("MyApp") ... build();
+ ...
+client.create().forPath("/test", data);
+// node was actually written to: "/MyApp/test"
+{code}
+
+h2. Temporary Connections
+
+Temporary CuratorFramework instances are meant for single requests to ZooKeeper ensembles over a failure prone network
+such as a WAN. The APIs available from CuratorTempFramework are limited. Further, the connection will be closed
+after a period of inactivity.
+
+This is based on an idea mentioned in a post by Camille Fournier:
+[[http://whilefalse.blogspot.com/2012/12/building-global-highly-available.html]].
+
+h3. Creating a CuratorTempFramework
+
+CuratorTempFramework instances are created via the CuratorFrameworkFactory just like normal CuratorFramework instances.
+However, instead of calling the {{build()}} method, call {{buildTemp()}}. {{buildTemp()}} creates a CuratorTempFramework
+instance that closes itself after 3 minutes of inactivity. There is an alternate version of {{buildTemp()}} that allows you to specify the inactivity period.
+
+h3. Limited API
+
+CuratorTempFramework instances provide the following methods:
+
+{code}
+ /**
+ * Stop the client
+ */
+ public void close();
+
+ /**
+ * Start a transaction builder
+ *
+ * @return builder object
+ * @throws Exception errors
+ */
+ public CuratorTransaction inTransaction() throws Exception;
+
+ /**
+ * Start a get data builder
+ *
+ * @return builder object
+ * @throws Exception errors
+ */
+ public TempGetDataBuilder getData() throws Exception;
+{code}
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/curator-framework/src/site/resources/css/site.css
----------------------------------------------------------------------
diff --git a/curator-framework/src/site/resources/css/site.css b/curator-framework/src/site/resources/css/site.css
new file mode 100644
index 0000000..f847d66
--- /dev/null
+++ b/curator-framework/src/site/resources/css/site.css
@@ -0,0 +1,4 @@
+tt
+{
+ background-color: transparent;
+}
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/curator-framework/src/site/site.xml
----------------------------------------------------------------------
diff --git a/curator-framework/src/site/site.xml b/curator-framework/src/site/site.xml
new file mode 100644
index 0000000..cc3fdc0
--- /dev/null
+++ b/curator-framework/src/site/site.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?><!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ -->
+
+<project xmlns="http://maven.apache.org/DECORATION/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/DECORATION/1.1.0 http://maven.apache.org/xsd/decoration-1.1.0.xsd" name="Apache Curator Framework">
+ <body>
+ <breadcrumbs>
+ <item name="Home" href="../index.html"/>
+ <item name="Framework" href="index.html"/>
+ </breadcrumbs>
+ </body>
+</project>
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/curator-recipes/src/site/site.xml
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/site.xml b/curator-recipes/src/site/site.xml
index 4e991cc..3122b7f 100644
--- a/curator-recipes/src/site/site.xml
+++ b/curator-recipes/src/site/site.xml
@@ -23,9 +23,5 @@
<item name="Home" href="../index.html"/>
<item name="Recipes" href="index.html"/>
</breadcrumbs>
-
- <menu name="Apache Curator">
- <item name="<-- Back" href="../index.html"/>
- </menu>
</body>
</project>
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index 757223b..f230afa 100644
--- a/pom.xml
+++ b/pom.xml
@@ -29,6 +29,7 @@
<description>
Curator is a set of Java libraries that make using Apache ZooKeeper much easier.
</description>
+ <url>http://curator.incubator.apache.org</url>
<properties>
<svnUrl>https://svn.apache.org/repos/asf/incubator/onami/site/</svnUrl>
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/src/site/apt/index.apt
----------------------------------------------------------------------
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
deleted file mode 100644
index d2abb7b..0000000
--- a/src/site/apt/index.apt
+++ /dev/null
@@ -1,74 +0,0 @@
- ------
- Apache Curator Home
- ------
- Apache Curator Documentation Team
- ------
- 2013-03-09
- ------
-
-~~
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you 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.
-~~
-
-Welcome to Apache Curator
-
-* What is Curator?
-
- Curator <n ˈkyoor͝ˌātər>: a keeper or custodian of a museum or other collection - A ZooKeeper Keeper.
-
- Curator is a set of Java libraries that make using {{{http://zookeeper.apache.org}Apache ZooKeeper}} much easier.
-
-* Getting Started
-
- See the page for quick start: [[Getting Started]].
-
-* Components
-
-*---*---*
-|[[Client]]|A replacement for the bundled <code>ZooKeeper</code> class that takes care of some low-level housekeeping and provides some useful utilities.|
-*---*---*
-|[[Framework]]|The Curator Framework is a high-level API that greatly simplifies using ZooKeeper. It adds many features that build on ZooKeeper and handles the complexity of managing connections to the ZooKeeper cluster and retrying operations.|
-*---*---*
-|[[Recipes]]|Implementations of some of the common ZooKeeper "recipes". The implementations are built on top of the Curator Framework.|
-*---*---*
-|[[Utilities]]|Various utilities that are useful when using ZooKeeper.|
-*---*---*
-|[[Errors]]|How Curator deals with errors, connection issues, recoverable exceptions, etc.|
-*---*---*
-|[[Extensions]]|Optional/extension recipes for vertical uses.|
-*---*---*
-
-* Maven / Artifacts
-
- Curator binaries are published to Maven Central. Curator consists of several artifacts. Which artifacts to use depends on your needs. For most users, the only artifact you need is <code>curator-recipes</code>.
-
-*---*---*---*
-|<<GroupID/Org>>|<<ArtifactID/Name>>|<<Description>>|
-*---*---*---*
-|org.apache.curator|curator-recipes|All of the recipes. Note: this artifact has dependencies on client and framework and, so, Maven (or whatever tool you're using) should pull those in automatically.|
-*---*---*---*
-|org.apache.curator|curator-framework|The Curator Framework high level API. This is built on top of the client and should pull it in automatically.|
-*---*---*---*
-|org.apache.curator|curator-client|The Curator Client - replacement for the ZooKeeper class in the ZK distribution.|
-*---*---*---*
-|org.apache.curator|curator-test|Contains the TestingServer, the TestingCluster and a few other tools useful for testing.|
-*---*---*---*
-|org.apache.curator|curator-x-discovery|A Service Discovery implementation built on the Curator Framework.|
-*---*---*---*
-|org.apache.curator|curator-x-discovery-server|A RESTful server that can be used with Curator Discovery.|
-*---*---*---*
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/src/site/confluence/errors.confluence
----------------------------------------------------------------------
diff --git a/src/site/confluence/errors.confluence b/src/site/confluence/errors.confluence
new file mode 100644
index 0000000..1a27bf8
--- /dev/null
+++ b/src/site/confluence/errors.confluence
@@ -0,0 +1,35 @@
+h1. Error Handling
+
+h2. Background
+ZooKeeper is a very low level system that requires users to do a lot of housekeeping. See:
+
+* [[http://wiki.apache.org/hadoop/ZooKeeper/FAQ]]
+
+The Curator [[Framework|curator-framework/index.html]] is designed to hide as much of the details/tedium of this housekeeping as is possible.
+
+h2. Connection Guarantees
+The Curator [[Framework|curator-framework/index.html]] constantly monitors the connection to the ZooKeeper ensemble. Further every operation is wrapped
+in a retry mechanism. Thus, the following guarantees can be made:
+
+* Every Curator operation properly waits until the ZooKeeper connection is established
+* Every Curator [[Framework|curator-framework/index.html]] operation (create, getData, etc.) is guaranteed to manage connection loss and/or session expiration per the currently set retry policy
+* If the connection is temporarily lost, Curator will attempt to retry the operation until it succeeds per the currently set retry policy
+* All Curator recipes attempt to deal with connection issues in an appropriate way
+
+h2. Notifications
+Curator exposes several listenable interfaces for clients to monitor the state of the ZooKeeper connection.
+
+{{ConnectionStateListener}} is called when there are connection disruptions. Clients can monitor these changes and take
+appropriate action. There are three possible state changes:
+
+|SUSPENDED|There has been a loss of connection. Leaders, locks, etc. should suspend until the connection is re-established. If the connection times-out you will receive a LOST notice|
+|RECONNECTED</td>
+|A suspended connection has been re-established</td>
+|LOST|The connection is confirmed to be lost. Close any locks, leaders, etc. and attempt to re-create them. NOTE: it is possible to get a RECONNECTED state after this but you should still consider any locks, etc. as dirty/unstable|
+|READ_ONLY|The connection has gone into read-only mode. This can only happen if you pass true for CuratorFrameworkFactory.Builder.canBeReadOnly(). See the ZooKeeper doc regarding read only connections: <a href="http://wiki.apache.org/hadoop/ZooKeeper/GSoCReadOnlyMode">http://wiki.apache.org/hadoop/ZooKeeper/GSoCReadOnlyMode</a>. The connection will remain in read only mode until another state change is sent.|
+
+{{UnhandledErrorListener}} is called when a background task, etc. catch an exception. In general, Curator users shouldn't care
+about these as they are logged. However, you can listen for them if you choose.
+
+h2. Recipes
+In general, the recipes attempt to deal with errors and connection issues. See the doc for each recipe for details on how it deals with errors.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/src/site/confluence/index.confluence
----------------------------------------------------------------------
diff --git a/src/site/confluence/index.confluence b/src/site/confluence/index.confluence
new file mode 100644
index 0000000..db89fd0
--- /dev/null
+++ b/src/site/confluence/index.confluence
@@ -0,0 +1,33 @@
+h1. Welcome to Apache Curator
+
+h2. What is Curator?
+
+Curator _n ˈkyoor͝ˌātər_: a keeper or custodian of a museum or other collection - A ZooKeeper Keeper.
+
+Curator is a set of Java libraries that make using [[http://zookeeper.apache.org|Apache ZooKeeper]] much easier.
+
+h2. Getting Started
+
+See the page for quick start: [[Getting Started|getting-started.html]].
+
+h2. Components
+
+|[[Framework|curator-framework/index.html]]|The Curator Framework is a high-level API that greatly simplifies using ZooKeeper. It adds many features that build on ZooKeeper and handles the complexity of managing connections to the ZooKeeper cluster and retrying operations.|
+|[[Recipes|curator-recipes/index.html]]|Implementations of some of the common ZooKeeper "recipes". The implementations are built on top of the Curator Framework.|
+|[[Utilities|utilities.html]]|Various utilities that are useful when using ZooKeeper.|
+|[[Client|curator-client/index.html]]|A replacement for the bundled {{ZooKeeper}} class that takes care of some low-level housekeeping and provides some useful utilities.|
+|[[Errors]]|How Curator deals with errors, connection issues, recoverable exceptions, etc.|
+|[[Extensions]]|Optional/extension recipes for vertical uses.|
+
+h2. Maven / Artifacts
+
+Curator binaries are published to Maven Central. Curator consists of several artifacts. Which artifacts to use depends on your needs. For
+most users, the only artifact you need is {{curator-recipes}}.
+
+||GroupID/Org||ArtifactID/Name||Description>||
+|org.apache.curator|curator-recipes|All of the recipes. Note: this artifact has dependencies on client and framework and, so, Maven (or whatever tool you're using) should pull those in automatically.|
+|org.apache.curator|curator-framework|The Curator Framework high level API. This is built on top of the client and should pull it in automatically.|
+|org.apache.curator|curator-client|The Curator Client - replacement for the ZooKeeper class in the ZK distribution.|
+|org.apache.curator|curator-test|Contains the TestingServer, the TestingCluster and a few other tools useful for testing.|
+|org.apache.curator|curator-x-discovery|A Service Discovery implementation built on the Curator Framework.|
+|org.apache.curator|curator-x-discovery-server|A RESTful server that can be used with Curator Discovery.|
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/src/site/confluence/utilities.confluence
----------------------------------------------------------------------
diff --git a/src/site/confluence/utilities.confluence b/src/site/confluence/utilities.confluence
new file mode 100644
index 0000000..d4b5ccb
--- /dev/null
+++ b/src/site/confluence/utilities.confluence
@@ -0,0 +1,59 @@
+h1. Utilities
+
+h2. Test Server
+In the curator-test sub-model the {{TestingServer}} class is provided. This class creates a local, in-process ZooKeeper server that can be used for testing.
+
+h2. Test Cluster
+In the curator-test sub-model the {{TestingCluster}} class is provided. This class creates an internally running ensemble of ZooKeeper servers.
+
+h2. ZKPaths
+Various static methods to help with using ZooKeeper ZNode paths:
+
+* getNodeFromPath: Given a full path, return the node name. i.e. "/one/two/three" will return "three"
+* mkdirs: Make sure all the nodes in the path are created.
+* getSortedChildren: Return the children of the given path sorted by sequence number
+* makePath: Given a parent path and a child node, create a combined full path
+
+h2. EnsurePath
+Utility to ensure that a particular path is created.
+The first time it is used, a synchronized call to {{ZKPaths.mkdirs(ZooKeeper, String)}} is made to ensure that the entire path has been created (with an empty byte array if needed). Subsequent calls with the instance are un-synchronized NOPs.
+
+Usage:
+{code}
+EnsurePath ensurePath = new EnsurePath(aFullPathToEnsure);
+...
+String nodePath = aFullPathToEnsure + "/foo";
+ensurePath.ensure(zk); // first time syncs and creates if needed
+zk.create(nodePath, ...);
+...
+ensurePath.ensure(zk); // subsequent times are NOPs
+zk.create(nodePath, ...);
+{code}
+
+*NOTE:* There's a method in the [[CuratorFramework class|curator-framework/index.html]] that returns an EnsurePath instance that is namespace aware.
+
+h2. BlockingQueueConsumer
+
+See: *[[DistributedQueue|curator-recipes/distributed-queue.html]]* and *[[DistributedPriorityQueue|curator-recipes/distributed-priority-queue.html]]*
+
+A queue consumer that provides behavior similar to a the JDK's BlockingQueue.
+
+h2. QueueSharder
+
+Due to limitations in ZooKeeper's transport layer, a single queue will break if it has more than 10K-ish items in it. This class
+provides a facade over multiple distributed queues. It monitors the queues and if any one of them goes over a threshold, a new
+queue is added. Puts are distributed amongst the queues.
+
+h2. Reaper and ChildReaper
+
+_Reaper_
+
+A Utility to delete parent paths of locks, etc. Periodically checks paths added to the reaper. If at check time, there are no
+children, the path is deleted. Clients should create one Reaper instance per application. Add lock paths to the reaper as
+needed and the reaper will periodically delete them. Curator's lock recipes will correctly handle parents getting deleted.
+
+_ChildReaper_
+
+Utility to reap the empty child nodes in a parent node. Periodically calls getChildren() on the node and adds empty nodes to an internally managed Reaper.
+
+*NOTE:* You should consider using LeaderSelector to run the Reapers as they don't need to run in every client.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/327b89e3/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 618913e..4be9b12 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -19,6 +19,7 @@
<project xmlns="http://maven.apache.org/DECORATION/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.1.0 http://maven.apache.org/xsd/decoration-1.1.0.xsd" name="Apache Curator">
+
<skin>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-fluido-skin</artifactId>
@@ -44,13 +45,22 @@
<item name="Apache ZooKeeper" href="http://zookeeper.apache.org"/>
</links>
- <menu name="Apache Curator">
+ <menu name="Apache Curator" inherit="top">
<item name="Home" href="index.html"/>
<item name="Getting Started" href="getting-started.html"/>
+ <item name="Framework" href="curator-framework/index.html"/>
<item name="Recipes" href="curator-recipes/index.html"/>
+ <item name="Utilities" href="utilities.html"/>
+ <item name="Client" href="curator-client/index.html"/>
+ </menu>
+
+ <menu name="Details" inherit="top">
+ <item name="Error Handling" href="errors.html"/>
</menu>
- <menu name="ASF" inherit="bottom">
+ <menu ref="reports" />
+
+ <menu name="ASF">
<item name="How the ASF works" href="http://www.apache.org/foundation/how-it-works.html"/>
<item name="Get Involved" href="http://www.apache.org/foundation/getinvolved.html"/>
<item name="Developer Resources" href="http://www.apache.org/dev/"/>