curator-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From randg...@apache.org
Subject [13/52] [abbrv] git commit: site wip
Date Wed, 27 Mar 2013 01:11:08 GMT
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 <jordan@jordanzimmerman.com>
Authored: Sat Mar 9 14:09:40 2013 -0800
Committer: Jordan Zimmerman <jordan@jordanzimmerman.com>
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 @@
 
     <name>Apache Curator</name>
     <description>
-        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.
     </description>
 
     <properties>
@@ -194,6 +193,13 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-site-plugin</artifactId>
                 <version>3.2</version>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.apache.maven.doxia</groupId>
+                        <artifactId>doxia-module-confluence</artifactId>
+                        <version>1.3</version>
+                    </dependency>
+                </dependencies>
             </plugin>
         </plugins>
     </build>

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 <n &#x02c8;kyoor&#x035d;&#x02cc;&#x0101;t&#x0259;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/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 @@
     <bannerLeft>
         <name>Apache Curator</name>
         <src>/images/curator-logo.png</src>
-        <href>/</href>
+        <href>/index.html</href>
     </bannerLeft>
 
     <bannerRight>
@@ -36,10 +36,14 @@
         <href>http://incubator.apache.org</href>
     </bannerRight>
 
-    <publishDate position="right"/>
-    <version position="right"/>
+    <publishDate/>
 
     <body>
+        <menu name="Apache Curator">
+            <item name="Home" href="index.html" />
+            <item name="Getting Started" href="getting-started.html" />
+        </menu>
+
         <footer>
             <div>
                 Apache Curator, the Apache feather logo, and the Apache Curator project logos
are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks
or registered trademarks of their respective owners.


Mime
View raw message