Return-Path: X-Original-To: apmail-curator-commits-archive@minotaur.apache.org Delivered-To: apmail-curator-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 9475AF9EE for ; Wed, 27 Mar 2013 01:11:26 +0000 (UTC) Received: (qmail 87632 invoked by uid 500); 27 Mar 2013 01:11:26 -0000 Delivered-To: apmail-curator-commits-archive@curator.apache.org Received: (qmail 87608 invoked by uid 500); 27 Mar 2013 01:11:26 -0000 Mailing-List: contact commits-help@curator.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@curator.incubator.apache.org Delivered-To: mailing list commits@curator.incubator.apache.org Received: (qmail 87567 invoked by uid 99); 27 Mar 2013 01:11:26 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 27 Mar 2013 01:11:26 +0000 X-ASF-Spam-Status: No, hits=-2001.3 required=5.0 tests=ALL_TRUSTED,RP_MATCHES_RCVD X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Wed, 27 Mar 2013 01:11:18 +0000 Received: (qmail 86303 invoked by uid 99); 27 Mar 2013 01:10:57 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 27 Mar 2013 01:10:57 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id B8F558217EC; Wed, 27 Mar 2013 01:10:56 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: randgalt@apache.org To: commits@curator.incubator.apache.org Date: Wed, 27 Mar 2013 01:11:08 -0000 Message-Id: In-Reply-To: <3e5d789fdb264943b4b84b15fcffb654@git.apache.org> References: <3e5d789fdb264943b4b84b15fcffb654@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [13/52] [abbrv] git commit: site wip X-Virus-Checked: Checked by ClamAV on apache.org 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/34b98227 Tree: http://git-wip-us.apache.org/repos/asf/incubator-curator/tree/34b98227 Diff: http://git-wip-us.apache.org/repos/asf/incubator-curator/diff/34b98227 Branch: refs/heads/master Commit: 34b98227a5ea8d58142b74266265b9fb833cb5fa Parents: 0149fee Author: Jordan Zimmerman Authored: Sat Mar 9 14:09:40 2013 -0800 Committer: Jordan Zimmerman Committed: Sat Mar 9 14:09:40 2013 -0800 ---------------------------------------------------------------------- .gitignore | 1 + pom.xml | 10 ++- src/site/apt/index.apt | 74 +++++++++++++++ src/site/confluence/getting-started.confluence | 92 +++++++++++++++++++ src/site/site.xml | 10 ++- 5 files changed, 182 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/34b98227/.gitignore ---------------------------------------------------------------------- diff --git a/.gitignore b/.gitignore index 23667f7..28d1a74 100644 --- a/.gitignore +++ b/.gitignore @@ -65,3 +65,4 @@ atlassian-ide-plugin.xml .nbattrs +build-web.sh http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/34b98227/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index f987f67..757223b 100644 --- a/pom.xml +++ b/pom.xml @@ -27,8 +27,7 @@ Apache 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 Apache ZooKeeper much easier. While ZooKeeper comes bundled with a Java client, using the client is non-trivial and error prone. + Curator is a set of Java libraries that make using Apache ZooKeeper much easier. @@ -194,6 +193,13 @@ org.apache.maven.plugins maven-site-plugin 3.2 + + + org.apache.maven.doxia + doxia-module-confluence + 1.3 + + http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/34b98227/src/site/apt/index.apt ---------------------------------------------------------------------- diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt new file mode 100644 index 0000000..d2abb7b --- /dev/null +++ b/src/site/apt/index.apt @@ -0,0 +1,74 @@ + ------ + 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 : 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 ZooKeeper 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 curator-recipes. + +*---*---*---* +|<>|<>|<>| +*---*---*---* +|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/34b98227/src/site/confluence/getting-started.confluence ---------------------------------------------------------------------- diff --git a/src/site/confluence/getting-started.confluence b/src/site/confluence/getting-started.confluence new file mode 100644 index 0000000..fd64a58 --- /dev/null +++ b/src/site/confluence/getting-started.confluence @@ -0,0 +1,92 @@ +h2. Learn ZooKeeper + +Curator users are assumed to know ZooKeeper. A good place to start is here: [[http://zookeeper.apache.org/doc/trunk/zookeeperStarted.html]] + +h2. Using Curator + +The Curator JARs are available from Maven Central. The various artifacts are listed here: [[https://github.com/Netflix/curator/wiki]]. Users +of Maven, Gradle, Ant, etc. can easily include Curator into their build script. + +Most users will want to use one of Curator's pre-built recipes. So, the {{curator-recipes}} is the correct artifact to use. If you only +want a wrapper around ZooKeeper that adds connection management and retry policies, use {{curator-framework}}. + +h2. Getting a Connection + +Curator uses [[Fluent Style|http://en.wikipedia.org/wiki/Fluent_interface]]. If you haven't used this before, it might seem odd +so it's suggested that you familiarize yourself with the style. + +Curator connection instances ({{CuratorFramework}}) are allocated from the {{CuratorFrameworkFactory}}. You only need *one* +{{CuratorFramework}} object for each ZooKeeper cluster you are connecting to: + +{code} +CuratorFrameworkFactory.newClient(zookeeperConnectionString, retryPolicy) +{code} + +This will create a connection to a ZooKeeper cluster using default values. The only thing that you need to specify is the retry +policy. For most cases, you should use: + +{code} +RetryPolicy retryPolicy = new ExponentialBackoffRetry(1000, 3) +CuratorFramework client = CuratorFrameworkFactory.newClient(zookeeperConnectionString, retryPolicy); +client.start(); +{code} + +The client must be started (and closed when no longer needed). + +h2. Calling ZooKeeper Directly + +Once you have a CuratorFramework instance, you can make direct calls to ZooKeeper in a similar way to using the raw +{{ZooKeeper}} object provided in the ZooKeeper distribution. E.g.: + +{code} +client.create().forPath("/my/path", myData) +{code} + +The benefit here is that Curator manages the ZooKeeper connection and will retry operations if there are connection problems. + +h2. Recipes + +h3. Distributed Lock + +{code} +InterProcessMutex lock = new InterProcessMutex(client, lockPath); +if ( lock.acquire(maxWait, waitUnit) ) +{ + try + { + // do some work inside of the critical section here + } + finally + { + lock.release(); + } +} +{code} + +h3. Leader Election + +{code} +LeaderSelectorListener listener = new LeaderSelectorListener() +{ + public void takeLeadership(CuratorFramework client) throws Exception + { + // this callback will get called when you are the leader + // do whatever leader work you need to and only exit + // this method when you want to relinquish leadership + } + + public void stateChanged(CuratorFramework client, ConnectionState newState) + { + // see https://github.com/Netflix/curator/wiki/Errors + // You always need to be aware that connections to ZK can fail + } +} + +LeaderSelector selector = new LeaderSelector(client, path, listener); +selector.autoRequeue(); // not required, but this is behavior that you will probably expect +selector.start(); +{code} + +h2. Examples + +Examples of Curator usage can be found here: [[https://github.com/Netflix/curator/tree/master/curator-examples/src/main/java]] http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/34b98227/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index 74f59e3..6991a99 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -27,7 +27,7 @@ Apache Curator /images/curator-logo.png - / + /index.html @@ -36,10 +36,14 @@ http://incubator.apache.org - - + + + + + +