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:10 UTC
[15/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/f2513a06
Tree: http://git-wip-us.apache.org/repos/asf/incubator-curator/tree/f2513a06
Diff: http://git-wip-us.apache.org/repos/asf/incubator-curator/diff/f2513a06
Branch: refs/heads/master
Commit: f2513a0649a7c7760da198c58a0861116891cd35
Parents: af6a77e
Author: Jordan Zimmerman <jo...@jordanzimmerman.com>
Authored: Sat Mar 9 17:56:11 2013 -0800
Committer: Jordan Zimmerman <jo...@jordanzimmerman.com>
Committed: Sat Mar 9 17:56:11 2013 -0800
----------------------------------------------------------------------
.../src/site/confluence/barrier.confluence | 35 ++++++++
.../confluence/distributed-atomic-long.confluence | 55 ++++++++++++
.../src/site/confluence/double-barrier.confluence | 39 ++++++++
.../src/site/confluence/index.confluence | 12 ++--
.../src/site/confluence/node-cache.confluence | 35 ++++++++
.../src/site/confluence/path-cache.confluence | 61 +++++++++++++
.../src/site/confluence/shared-counter.confluence | 69 +++++++++++++++
7 files changed, 300 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/f2513a06/curator-recipes/src/site/confluence/barrier.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/barrier.confluence b/curator-recipes/src/site/confluence/barrier.confluence
new file mode 100644
index 0000000..2cf2e08
--- /dev/null
+++ b/curator-recipes/src/site/confluence/barrier.confluence
@@ -0,0 +1,35 @@
+h1. Barrier
+
+h2. Description
+An implementation of the Distributed Barrier ZK recipe.
+
+Distributed systems use barriers to block processing of a set of nodes until a condition is met at which time all the nodes are allowed to proceed.
+
+h2. Participating Classes
+* DistributedBarrier
+
+h2. Usage
+h3. Creating a DistributedBarrier
+{code}
+public DistributedBarrier(CuratorFramework client,
+ String barrierPath)
+Parameters:
+client - client
+barrierPath - path to use as the barrier
+{code}
+
+h2. General Usage
+To wait on the barrier:
+{code}
+public void waitOnBarrier()
+{code}
+
+There are utilities for setting/removing the barrier:
+
+{code}
+setBarrier();
+removeBarrier();
+{code}
+
+h2. Error Handling
+DistributedBarrier instances watch for connection loss and will throw an exception from {{waitOnBarrier()}}.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/f2513a06/curator-recipes/src/site/confluence/distributed-atomic-long.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/distributed-atomic-long.confluence b/curator-recipes/src/site/confluence/distributed-atomic-long.confluence
new file mode 100644
index 0000000..43d8155
--- /dev/null
+++ b/curator-recipes/src/site/confluence/distributed-atomic-long.confluence
@@ -0,0 +1,55 @@
+h1. Distributed Atomic Long
+
+h2. Description
+A counter that attempts atomic increments. It first tries using optimistic locking. If that fails, an optional
+InterProcessMutex is taken. For both optimistic and mutex, a retry policy is used to retry the increment
+
+h2. Participating Classes
+* DistributedAtomicLong
+* AtomicValue
+* PromotedToLock
+
+h2. Usage
+h3. Creating a DistributedAtomicLong
+Optimistic mode only:
+{code}
+public DistributedAtomicLong(CuratorFramework client,
+ String counterPath,
+ RetryPolicy retryPolicy)
+Creates the counter in optimistic mode only - i.e. the promotion to a mutex is not done
+Parameters:
+client - the client
+counterPath - path to hold the counter value
+retryPolicy - the retry policy to use
+{code}
+
+Mutex promotion mode:
+{code}
+public DistributedAtomicLong(CuratorFramework client,
+ String counterPath,
+ RetryPolicy retryPolicy,
+ PromotedToLock promotedToLock)
+Creates the counter in mutex promotion mode. The optimistic lock will be tried first using
+the given retry policy. If the increment does not succeed, a InterProcessMutex will be
+tried with its own retry policy
+Parameters:
+client - the client
+counterPath - path to hold the counter value
+retryPolicy - the retry policy to use
+promotedToLock - the arguments for the mutex promotion
+{code}
+
+h2. General Usage
+# Perform an operation on the counter:
+** {{get()}}
+** {{increment()}}
+** {{decrement()}}
+** {{add()}}
+** {{subtract()}}
+# Examine the result AtomicValue:
+** You *must* first check {{succeeded()}} which returns true if the operation succeeded. If false is returned, the operation failed and the atomic was not updated.
+** If the operation succeeded, you can get the value prior to the operation via {{preValue()}} and the value after the operation {{postValue()}}
+
+h2. Error Handling
+All the atomic instances access the ZooKeeper server for each method call. Therefore, the standard retry
+mechanism will be applied and any errors executing the operations will result in an Exception being thrown.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/f2513a06/curator-recipes/src/site/confluence/double-barrier.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/double-barrier.confluence b/curator-recipes/src/site/confluence/double-barrier.confluence
new file mode 100644
index 0000000..246927e
--- /dev/null
+++ b/curator-recipes/src/site/confluence/double-barrier.confluence
@@ -0,0 +1,39 @@
+h1. Double Barrier
+
+h2. Description
+An implementation of the Distributed Double Barrier ZK recipe.
+
+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.
+
+h2. Participating Classes
+* DistributedDoubleBarrier
+
+h2. Usage
+h3. Creating a DistributedBarrier
+{code}
+public DistributedDoubleBarrier(CuratorFramework client,
+ String barrierPath,
+ int memberQty)
+Creates the barrier abstraction. memberQty is the number of members in the barrier. When enter() is called, it blocks until
+all members have entered. When leave() is called, it blocks until all members have left.
+
+Parameters:
+client - the client
+barrierPath - path to use
+memberQty - the number of members in the barrier
+{code}
+
+h2. General Usage
+To enter on the barrier:
+{code}
+public void enter();
+{code}
+
+To leave on the barrier:
+{code}
+public void leave();
+{code}
+
+h2. Error Handling
+DistributedDoubleBarrier instances watch for connection loss and will throw an exception from {{enter()}} and/or {{leave()}}.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/f2513a06/curator-recipes/src/site/confluence/index.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/index.confluence b/curator-recipes/src/site/confluence/index.confluence
index 004c066..2977880 100644
--- a/curator-recipes/src/site/confluence/index.confluence
+++ b/curator-recipes/src/site/confluence/index.confluence
@@ -19,13 +19,13 @@ Curator implements all of the recipes listed on the ZooKeeper recipes doc (excep
|[[Distributed Delay Queue|distributed-delay-queue.html]]|An implementation of a Distributed Delay Queue.|
|[[Simple Distributed Queue|simple-distributed-queue.html]]|A drop-in replacement for the DistributedQueue that comes with the ZK distribution.|
||Barriers|| ||
-|[[Barrier]]|Distributed systems use barriers to block processing of a set of nodes until a condition is met at which time all the nodes are allowed to proceed.|
-|[[Double Barrier]]|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.|
+|[[Barrier|barrier.html]]|Distributed systems use barriers to block processing of a set of nodes until a condition is met at which time all the nodes are allowed to proceed.|
+|[[Double Barrier|double-barrier.html]]|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.|
| | |
||Counters|| ||
-|[[Shared Counter]]|Manages a shared integer. All clients watching the same path will have the up-to-date value of the shared integer (considering ZK's normal consistency guarantees).|
-|[[Distributed Atomic Long]]|A counter that attempts atomic increments. It first tries using optimistic locking. If that fails, an optional InterProcessMutex is taken. For both optimistic and mutex, a retry policy is used to retry the increment.|
+|[[Shared Counter|shared-counter.html]]|Manages a shared integer. All clients watching the same path will have the up-to-date value of the shared integer (considering ZK's normal consistency guarantees).|
+|[[Distributed Atomic Long|distributed-atomic-long.html]]|A counter that attempts atomic increments. It first tries using optimistic locking. If that fails, an optional InterProcessMutex is taken. For both optimistic and mutex, a retry policy is used to retry the increment.|
| | |
||Caches|| ||
-|[[Path Cache]]|A Path Cache is used to watch a ZNode. Whenever a child is added, updated or removed, the Path Cache will change its state to contain the current set of children, the children's data and the children's state. Path caches in the Curator Framework are provided by the PathChildrenCache class. Changes to the path are passed to registered PathChildrenCacheListener instances.|
-|[[Node Cache]]|A utility that attempts to keep the data from a node locally cached. This class will watch the node, respond to update/create/delete events, pull down the data, etc. You can register a listener that will get notified when changes occur.|
+|[[Path Cache|path-cache.html]]|A Path Cache is used to watch a ZNode. Whenever a child is added, updated or removed, the Path Cache will change its state to contain the current set of children, the children's data and the children's state. Path caches in the Curator Framework are provided by the PathChildrenCache class. Changes to the path are passed to registered PathChildrenCacheListener instances.|
+|[[Node Cache|node-cache.html]]|A utility that attempts to keep the data from a node locally cached. This class will watch the node, respond to update/create/delete events, pull down the data, etc. You can register a listener that will get notified when changes occur.|
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/f2513a06/curator-recipes/src/site/confluence/node-cache.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/node-cache.confluence b/curator-recipes/src/site/confluence/node-cache.confluence
new file mode 100644
index 0000000..ca13b8e
--- /dev/null
+++ b/curator-recipes/src/site/confluence/node-cache.confluence
@@ -0,0 +1,35 @@
+h1. Node Cache
+
+h2. Description
+A Node Cache is used to watch a ZNode. Whenever the data is modified or the ZNode is deleted, the Node Cache will change its
+state to contain the current data (or null if ZNode was deleted).
+
+h2. Participating Classes
+* NodeCache
+* NodeCacheListener
+* ChildData
+
+h2. Usage
+h3. Creating a NodeChildrenCache
+{code}
+public NodeCache(CuratorFramework client,
+ String path)
+Parameters:
+client - the client
+path - path to cache
+{code}
+
+h2. General Usage
+The cache must be started by calling {{start()}}. Call {{close()}} when you are through with the cache.
+
+At any time, call {{getCurrentData()}} to get the current state of the cache. You can also register to be notified
+when a change occurs by calling {{getListenable()}} and then:
+{code}
+public void addListener(NodeCacheListener listener)
+ Add a change listener
+Parameters:
+listener - the listener
+{code}
+
+h2. Error Handling
+NodeCache instances internally monitor a {{ConnectionStateListener}}.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/f2513a06/curator-recipes/src/site/confluence/path-cache.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/path-cache.confluence b/curator-recipes/src/site/confluence/path-cache.confluence
new file mode 100644
index 0000000..072fa5a
--- /dev/null
+++ b/curator-recipes/src/site/confluence/path-cache.confluence
@@ -0,0 +1,61 @@
+h1. Path Cache
+
+h2. Description
+A Path Cache is used to watch a ZNode. Whenever a child is added, updated or removed, the Path Cache will change its state to contain the current set of children, the children's data and the children's state.
+
+h2. Participating Classes
+* PathChildrenCache
+* PathChildrenCacheMode
+* PathChildrenCacheListener
+* ChildData
+
+h2. Usage
+h3. Creating a PathChildrenCache
+{code}
+public PathChildrenCache(CuratorFramework client,
+ String path,
+ boolean cacheData)
+Parameters:
+client - the client
+path - path to watch
+cacheData - if true, node contents are cached in addition to the stat
+{code}
+
+h2. General Usage
+The cache must be started by calling {{start()}}. Call {{close()}} when you are through with the cache.
+
+There are two versions of {{start()}}. The no-arg version gives default behavior. The other version takes an enumeration that allows you to control how the initial cache is warmed:
+
+{code}
+public enum StartMode
+{
+ /**
+ * cache will _not_ be primed. i.e. it will start empty and you will receive
+ * events for all nodes added, etc.
+ */
+ NORMAL,
+
+ /**
+ * rebuild() will be called before this method returns in
+ * order to get an initial view of the node.
+ */
+ BUILD_INITIAL_CACHE,
+
+ /**
+ * After cache is primed with initial values (in the background) a
+ * PathChildrenCacheEvent.Type.INITIALIZED event will be posted
+ */
+ POST_INITIALIZED_EVENT
+}
+{code}
+
+At any time, call {{getCurrentData()}} to get the current state of the cache. You can also register to be notified when a change occurs by calling {{getListenable()}} and then:
+{code}
+public void addListener(PathChildrenCacheListener listener)
+ Add a change listener
+Parameters:
+listener - the listener
+{code}
+
+h2. Error Handling
+PathChildrenCache instances internally monitor a {{ConnectionStateListener}}. If the connection state changes, the cache is reset (the {{PathChildrenCacheListener}} will receive a RESET).
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/f2513a06/curator-recipes/src/site/confluence/shared-counter.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/shared-counter.confluence b/curator-recipes/src/site/confluence/shared-counter.confluence
new file mode 100644
index 0000000..e05b060
--- /dev/null
+++ b/curator-recipes/src/site/confluence/shared-counter.confluence
@@ -0,0 +1,69 @@
+h1. Shared Counter
+
+h2. Description
+Manages a shared integer. All clients watching the same path will have the up-to-date value of the shared integer
+(considering ZK's normal consistency guarantees).
+
+h2. Participating Classes
+* SharedCount
+* SharedCountReader
+* SharedCountListener
+
+h2. Usage
+h3. Creating a SharedCounter
+{code}
+public SharedCount(CuratorFramework client,
+ String path,
+ int seedValue)
+Parameters:
+client - the client
+path - the shared path - i.e. where the shared count is stored
+seedValue - the initial value for the count if/f the path has not yet been created
+{code}
+
+h3. General Usage
+SharedCounts must be started:
+{code}
+count.start();
+{code}
+
+When you are through with the instance, you should call close:
+{code}
+count.close();
+{code}
+
+{code}
+int getCount()
+Return the current value of the count
+{code}
+
+{code}
+void addListener(SharedCountListener listener)
+Add a listener for changes to the count
+{code}
+
+{code}
+public void setCount(int newCount)
+
+Change the shared count value irrespective of its previous state
+{code}
+
+{code}
+public boolean trySetCount(int newCount)
+
+Changes the shared count only if its value has not changed since this client last read it. If the count
+has changed, the value is not set and this client's view of the value is updated. i.e. if the count is
+not successful you can get the updated value by calling getCount().
+Parameters:
+newCount - the new value to attempt
+Returns:
+true if the change attempt was successful, false if not. If the change was not successful, getCount()
+will return the updated value
+{code}
+
+h2. Error Handling
+The {{SharedCountListener}} class extends {{ConnectionStateListener}}. When the SharedCount
+is started, it adds the listener to the Curator instance. Users of the {{SharedCount}} must pay attention to any connection state changes.
+
+If the SUSPENDED state is reported, the instance must assume that, until it receives a RECONNECTED state, the count
+is no longer accurate and isn't being updated. If the LOST state is reported, the count is permanently down.