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:09 UTC
[14/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/af6a77ed
Tree: http://git-wip-us.apache.org/repos/asf/incubator-curator/tree/af6a77ed
Diff: http://git-wip-us.apache.org/repos/asf/incubator-curator/diff/af6a77ed
Branch: refs/heads/master
Commit: af6a77ed68b2796c9ad9965017346d67ca1a9762
Parents: 34b9822
Author: Jordan Zimmerman <jo...@jordanzimmerman.com>
Authored: Sat Mar 9 17:33:51 2013 -0800
Committer: Jordan Zimmerman <jo...@jordanzimmerman.com>
Committed: Sat Mar 9 17:33:51 2013 -0800
----------------------------------------------------------------------
.../confluence/distributed-delay-queue.confluence | 61 +++++++++
.../confluence/distributed-id-queue.confluence | 35 +++++
.../distributed-priority-queue.confluence | 77 +++++++++++
.../site/confluence/distributed-queue.confluence | 68 ++++++++++
.../src/site/confluence/index.confluence | 31 +++++
.../src/site/confluence/leader-election.confluence | 54 ++++++++
.../src/site/confluence/leader-latch.confluence | 80 +++++++++++
.../site/confluence/multi-shared-lock.confluence | 36 +++++
.../src/site/confluence/shared-lock.confluence | 48 +++++++
.../confluence/shared-reentrant-lock.confluence | 72 ++++++++++
.../shared-reentrant-read-write-lock.confluence | 46 +++++++
.../site/confluence/shared-semaphore.confluence | 102 +++++++++++++++
.../confluence/simple-distributed-queue.confluence | 51 +++++++
curator-recipes/src/site/resources/css/site.css | 4 +
curator-recipes/src/site/site.xml | 31 +++++
src/site/resources/css/site.css | 4 +
src/site/site.xml | 26 +++-
17 files changed, 821 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/distributed-delay-queue.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/distributed-delay-queue.confluence b/curator-recipes/src/site/confluence/distributed-delay-queue.confluence
new file mode 100644
index 0000000..01f6f57
--- /dev/null
+++ b/curator-recipes/src/site/confluence/distributed-delay-queue.confluence
@@ -0,0 +1,61 @@
+h1. Distributed Delay Queue
+
+h2. *IMPORTANT* - We recommend that you do NOT use ZooKeeper for Queues. Please see [[Tech Note 4|../tech-note-4.html]] for details.
+
+h2. Description
+An implementation of a Distributed Delay Queue. A Delay Queue is similar to a Priority Queue. When items are added to the queue,
+a delay value is given. The item will not be sent to a consumer until the time elapses.
+
+h2. Participating Classes
+* QueueBuilder
+* QueueConsumer
+* QueueSerializer
+* DistributedDelayQueue
+
+h2. Usage
+h3. Creating a DistributedDelayQueue
+{code}
+public static <T> QueueBuilder<T> builder(CuratorFramework client,
+ QueueConsumer<T> consumer,
+ QueueSerializer<T> serializer,
+ java.lang.String queuePath)
+Parameters:
+client - the curator client
+consumer - message consumer
+serializer - serializer to use for items
+queuePath - path to store queue
+{code}
+
+{code}
+QueueBuilder<MessageType> builder = QueueBuilder.builder(client, consumer, serializer, path);
+... more builder method calls as needed ...
+DistributedDelayQueue<MessageType> queue = builder.buildDelayQueue();
+{code}
+
+h2. General Usage
+The queue must be started via the {{start()}} method. Call {{close()}} when you are done with the queue.
+
+To add messages to the queue:
+{code}{code}
+queue.put(aMessage, delayUntilEpoch);
+{code}
+
+The consumer ({{QueueConsumer.consumeMessage()}}) will get called as messages arrive. {{delayUntilEpoch}}
+is a future epoch (milliseconds) when this item will be available to consumers.
+
+h2. Lock Safety
+In the general usage case, the message is removed from the queue prior to the consumer being called. A more atomic mode is provided
+that removes the item from the queue only after the consumer successfully returns. To enable this mode, call the {{lockPath()}}
+method of the Queue Builder. This uses a lock to make the message recoverable. A lock is held while the message is being processed - this
+prevents other processes from taking the message. The message will not be removed from the queue until the consumer functor returns. Thus,
+if there is a failure or the process dies, the message will get sent to another process. There is a small performance penalty for this behavior however.
+
+h2. Data Format
+Same as [[Distributed Queue]]
+
+h2. Error Handling
+The {{QueueConsumer}} class extends {{ConnectionStateListener}}. When the queue is started, it adds the listener to the
+Curator instance. Users of the {{DistributedPriorityQueue}} 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 queue is no longer being updated.
+If the LOST state is reported, the queue is permanently down.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/distributed-id-queue.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/distributed-id-queue.confluence b/curator-recipes/src/site/confluence/distributed-id-queue.confluence
new file mode 100644
index 0000000..8cdbea4
--- /dev/null
+++ b/curator-recipes/src/site/confluence/distributed-id-queue.confluence
@@ -0,0 +1,35 @@
+h1. Distributed ID Queue
+
+h2. *IMPORTANT* - We recommend that you do NOT use ZooKeeper for Queues. Please see [[Tech Note 4|../tech-note-4.html]] for details.
+
+h2. Description
+This is an alternate version of [[Distributed Queue|distributed-queue.html]] that supports assigning IDs to the items
+added to the queue. Items put into the queue are guaranteed to be ordered (by means of ZK's PERSISTENT_SEQUENTIAL node).
+If a single consumer takes items out of the queue, they will be ordered FIFO. If ordering is important, use a LeaderSelector to nominate a single consumer.
+
+h2. Participating Classes
+* QueueBuilder
+* QueueConsumer
+* QueueSerializer
+* DistributedQueue
+
+h2. Usage
+h3. Creating a DistributedIdQueue
+See [[Distributed Queue|distributed-queue.html]] for details of using the builder, the only difference is to use the {{buildIdQueue()}} method.
+
+h2. General Usage
+The queue must be started via the {{start()}} method. Call {{close()}} when you are done with the queue.
+
+To add messages to the queue:
+{code}
+queue.put(aMessage, messageId);
+{code}
+
+To remove messages from the queue:
+{code}
+int numberRemoved = queue.remove(messageId);
+{code}
+
+Your consumer ({{QueueConsumer.consumeMessage()}}) will get called as messages arrive.
+
+The lock safety and error handling are the same as for [[Distributed Queue|distributed-queue.html]].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/distributed-priority-queue.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/distributed-priority-queue.confluence b/curator-recipes/src/site/confluence/distributed-priority-queue.confluence
new file mode 100644
index 0000000..b14bd77
--- /dev/null
+++ b/curator-recipes/src/site/confluence/distributed-priority-queue.confluence
@@ -0,0 +1,77 @@
+h1. Distributed Priority Queue
+
+h2. *IMPORTANT* - We recommend that you do NOT use ZooKeeper for Queues. Please see [[Tech Note 4|../tech-note-4.html]] for details.
+
+h2. Description
+An implementation of the Distributed Priority Queue ZK recipe.
+
+h2. Participating Classes
+* QueueBuilder
+* QueueConsumer
+* QueueSerializer
+* DistributedPriorityQueue
+
+h2. Usage
+h3. Creating a DistributedPriorityQueue
+{code}
+public static <T> QueueBuilder<T> builder(CuratorFramework client,
+ QueueConsumer<T> consumer,
+ QueueSerializer<T> serializer,
+ java.lang.String queuePath)
+Parameters:
+client - the curator client
+consumer - message consumer
+serializer - serializer to use for items
+queuePath - path to store queue
+{code}
+
+{code}
+QueueBuilder<MessageType> builder = QueueBuilder.builder(client, consumer, serializer, path);
+... more builder method calls as needed ...
+DistributedPriorityQueue<MessageType> queue = builder.buildPriorityQueue(minItemsBeforeRefresh);
+{code}
+
+{code}
+public DistributedPriorityQueue<T> buildPriorityQueue(int minItemsBeforeRefresh)
+Build a DistributedPriorityQueue from the current builder values.
+
+When the priority queue detects an item addition/removal, it will stop processing its current list of items and refresh the
+list. minItemsBeforeRefresh modifies this. It determines the minimum number of items from the active list that will get processed before a refresh.
+
+Due to a quirk in the way ZooKeeper notifies changes, the queue will get an item addition/remove notification after every item is
+processed. This can lead to poor performance. Set minItemsBeforeRefresh to the value your application can tolerate being out of sync.
+
+For example: if the queue sees 10 items to process, it will end up making 10 calls to ZooKeeper to check status. You can control
+this by setting minItemsBeforeRefresh to 10 (or more) and the queue will only refresh with ZooKeeper after 10 items are processed
+
+Parameters:
+minItemsBeforeRefresh - minimum items to process before refreshing the item list
+{code}
+
+h2. General Usage
+The queue must be started via the {{start()}} method. Call {{close()}} when you are done with the queue.
+
+To add messages to the queue:
+{code}
+queue.put(aMessage, priority);
+{code}
+
+The consumer ({{QueueConsumer.consumeMessage()}}) will get called as messages arrive.
+
+h2. Lock Safety
+In the general usage case, the message is removed from the queue prior to the consumer being called. A more atomic mode is
+provided that removes the item from the queue only after the consumer successfully returns. To enable this mode, call the
+{{lockPath()}} method of the Queue Builder. This uses a lock to make the message recoverable. A lock is held while the
+message is being processed - this prevents other processes from taking the message. The message will not be removed from the queue
+until the consumer functor returns. Thus, if there is a failure or the process dies, the message will get sent to another process.
+There is a small performance penalty for this behavior however.
+
+h2. Data Format
+Same as [[Distributed Queue]]
+
+h2. Error Handling
+The {{QueueConsumer}} class extends {{ConnectionStateListener}}. When the queue is started, it adds the listener to the
+Curator instance. Users of the {{DistributedPriorityQueue}} 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 queue is no longer being
+updated. If the LOST state is reported, the queue is permanently down.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/distributed-queue.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/distributed-queue.confluence b/curator-recipes/src/site/confluence/distributed-queue.confluence
new file mode 100644
index 0000000..3adf4ec
--- /dev/null
+++ b/curator-recipes/src/site/confluence/distributed-queue.confluence
@@ -0,0 +1,68 @@
+h1. Distributed Queue
+
+h2. *IMPORTANT* - We recommend that you do NOT use ZooKeeper for Queues. Please see [[Tech Note 4|../tech-note-4.html]] for details.
+
+h2. Description
+An implementation of the Distributed Queue ZK recipe. Items put into the queue are guaranteed to be ordered (by means of ZK's PERSISTENT_SEQUENTIAL node). If a single consumer takes items out of the queue, they will be ordered FIFO. If ordering is important, use a LeaderSelector to nominate a single consumer.
+
+h2. Participating Classes
+* QueueBuilder
+* QueueConsumer
+* QueueSerializer
+* DistributedQueue
+
+h2. Usage
+h3. Creating a DistributedQueue
+{code}
+public static <T> QueueBuilder<T> builder(CuratorFramework client,
+ QueueConsumer<T> consumer,
+ QueueSerializer<T> serializer,
+ java.lang.String queuePath)
+Parameters:
+client - the curator client
+consumer - functor to receive messages
+serializer - serializer to use for items
+queuePath - path to store queue
+{code}
+
+{code}
+QueueBuilder<MessageType> builder = QueueBuilder.builder(client, consumer, serializer, path);
+... more builder method calls as needed ...
+DistributedQueue<MessageType queue = builder.build();
+{code}
+
+h2. General Usage
+The queue must be started via the {{start()}} method. Call {{close()}} when you are done with the queue.
+
+To add messages to the queue:
+{code}
+queue.put(aMessage);
+{code}
+
+Your consumer ({{QueueConsumer.consumeMessage()}}) will get called as messages arrive.
+
+h2. Lock Safety
+In the general usage case, the message is removed from the queue prior to the consumer being called. A more
+atomic mode is provided that removes the item from the queue only after the consumer successfully returns. To
+enable this mode, call the {{lockPath()}} method of the Queue Builder. This uses a lock to make the
+message recoverable. A lock is held while the message is being processed - this prevents other processes
+from taking the message. The message will not be removed from the queue until the consumer functor returns.
+Thus, if there is a failure or the process dies, the message will get sent to another process. There is a
+small performance penalty for this behavior however.
+
+h2. Data Format
+The Distributed queue writes messages using this format:
+
+||OFFSET||SIZE||DESCRIPTION||
+|0|4|Format version. Currently 0x00010001|
+|4|1|Opcode: 0x01 = message, 0x02 = End of data|
+|5|4|Message byte length|
+|9|n|Message: serialized message bytes|
+|9 + n|...|Next set of opcode-size-bytes until end of data|
+
+h2. Error Handling
+The {{QueueConsumer}} class extends {{ConnectionStateListener}}. When the queue is started,
+it adds the listener to the Curator instance. Users of the {{DistributedQueue}} 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 queue is no longer being updated. If the LOST state is reported, the queue is permanently down.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/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
new file mode 100644
index 0000000..004c066
--- /dev/null
+++ b/curator-recipes/src/site/confluence/index.confluence
@@ -0,0 +1,31 @@
+h1. Recipes
+
+Curator implements all of the recipes listed on the ZooKeeper recipes doc (except two phase commit). Click on the recipe name below for detailed documentation.
+
+||Elections|| ||
+|[[Leader Latch|leader-latch.html]]|In distributed computing, leader election is the process of designating a single process as the organizer of some task distributed among several computers (nodes). Before the task is begun, all network nodes are unaware which node will serve as the "leader," or coordinator, of the task. After a leader election algorithm has been run, however, each node throughout the network recognizes a particular, unique node as the task leader.|
+|[[Leader Election|leader-election.html]]|Initial Curator leader election recipe.|
+| | |
+||Locks|| ||
+|[[Shared Reentrant Lock|shared-reentrant-lock.html]]|Fully distributed locks that are globally synchronous, meaning at any snapshot in time no two clients think they hold the same lock.|
+|[[Shared Lock|shared-lock.html]]|Similar to [[Shared Reentrant Lock|shared-reentrant-lock.html]] but not reentrant.|
+|[[Shared Reentrant Read Write Lock|shared-reentrant-read-write-lock.html]]|A re-entrant read/write mutex that works across JVMs. A read write lock maintains a pair of associated locks, one for read-only operations and one for writing. The read lock may be held simultaneously by multiple reader processes, so long as there are no writers. The write lock is exclusive.|
+|[[Shared Semaphore|shared-semaphore.html]]|A counting semaphore that works across JVMs. All processes in all JVMs that use the same lock path will achieve an inter-process limited set of leases. Further, this semaphore is mostly "fair" - each user will get a lease in the order requested (from ZK's point of view).|
+|[[Multi Shared Lock|multi-shared-lock.html]]|A container that manages multiple locks as a single entity. When acquire() is called, all the locks are acquired. If that fails, any paths that were acquired are released. Similarly, when release() is called, all locks are released (failures are ignored).|
+||Queues|| ||
+|[[Distributed Queue|distributed-queue.html]]|An implementation of the Distributed Queue ZK recipe. Items put into the queue are guaranteed to be ordered (by means of ZK's PERSISTENT_SEQUENTIAL node). If a single consumer takes items out of the queue, they will be ordered FIFO. If ordering is important, use a LeaderSelector to nominate a single consumer.|
+|[[Distributed Id Queue|distributed-id-queue.html]]|A version of DistributedQueue that allows IDs to be associated with queue items. Items can then be removed from the queue if needed.|
+|[[Distributed Priority Queue|distributed-priority-queue.html]]|An implementation of the Distributed Priority Queue ZK recipe.|
+|[[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.|
+| | |
+||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.|
+| | |
+||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.|
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/leader-election.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/leader-election.confluence b/curator-recipes/src/site/confluence/leader-election.confluence
new file mode 100644
index 0000000..85fde0a
--- /dev/null
+++ b/curator-recipes/src/site/confluence/leader-election.confluence
@@ -0,0 +1,54 @@
+h1. Leader Election
+
+h2. Description
+In distributed computing, leader election is the process of designating a single process as the organizer of some task distributed among several computers (nodes). Before the task is begun, all network nodes are unaware which node will serve as the "leader," or coordinator, of the task. After a leader election algorithm has been run, however, each node throughout the network recognizes a particular, unique node as the task leader.
+
+NOTE: Curator has two leader election recipes. Which one two use depends on your requirements.
+
+h2. Participating Classes
+* LeaderSelector
+* LeaderSelectorListener
+
+h2. Usage
+h3. Creating a LeaderSelector
+{code}
+public LeaderSelector(CuratorFramework client,
+ String mutexPath,
+ LeaderSelectorListener listener)
+Parameters:
+client - the client
+mutexPath - the path for this leadership group
+listener - listener
+{code}
+
+{code}
+public LeaderSelector(CuratorFramework client,
+ String mutexPath,
+ ThreadFactory threadFactory,
+ Executor executor,
+ LeaderSelectorListener listener)
+Parameters:
+client - the client
+mutexPath - the path for this leadership group
+threadFactory - factory to use for making internal threads
+executor - the executor to run in
+listener - listener
+{code}
+
+h3. General Usage
+LeaderSelectors must be started:
+{code}
+leaderSelector.start();
+{code}
+
+Once started, the {{takeLeadership()}} of your listener will be called when you have leadership. Your {{takeLeadership()}} method should only return when leadership is being relinquished.
+
+When you are through with the LeaderSelector instance, you should call close:
+{code}
+leaderSelector.close();
+{code}
+
+h2. Error Handling
+The {{LeaderSelectorListener}} class extends {{ConnectionStateListener}}. When the LeaderSelector is started, it adds the listener to the Curator instance. Users of the {{LeaderSelector}} must pay attention to any connection state changes. If an instance becomes the leader, it should respond to notification of being SUSPENDED or LOST.
+
+If the SUSPENDED state is reported, the instance must assume that it might no longer be the leader until it receives a RECONNECTED state. If the LOST state is reported, the instance is no longer the leader and its {{takeLeadership}} method should exit.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/leader-latch.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/leader-latch.confluence b/curator-recipes/src/site/confluence/leader-latch.confluence
new file mode 100644
index 0000000..2d6421a
--- /dev/null
+++ b/curator-recipes/src/site/confluence/leader-latch.confluence
@@ -0,0 +1,80 @@
+h1. Leader Latch
+
+h2. Description
+In distributed computing, leader election is the process of designating a single process as the organizer of some task distributed
+among several computers (nodes). Before the task is begun, all network nodes are unaware which node will serve as the "leader,"
+or coordinator, of the task. After a leader election algorithm has been run, however, each node throughout the network recognizes
+a particular, unique node as the task leader.
+
+NOTE: Curator has two leader election recipes. Which one to use depends on your requirements.
+
+h2. Participating Classes
+* LeaderLatch
+
+h2. Usage
+h3. Creating a LeaderLatch
+{code}
+public LeaderLatch(CuratorFramework client,
+ String latchPath)
+Parameters:
+client - the client
+latchPath - the path for this leadership group
+{code}
+
+{code}
+public LeaderLatch(CuratorFramework client,
+ String latchPath,
+ String id)
+Parameters:
+client - the client
+latchPath - the path for this leadership group
+id - participant ID
+{code}
+
+h3. General Usage
+LeaderLatches must be started:
+{code}
+leaderLatch.start();
+{code}
+
+Once started, the LeaderLatch will negotiate with any other LeaderLatch participants that use the same latch path and randomly choose one of them to be the leader. At any time, you can determine if a given instance is the leader by calling:
+
+{code}
+public boolean hasLeadership()
+Return true if leadership is currently held by this instance
+{code}
+
+Similar to the JDK's CountDownLatch, LeaderLatch has methods that block until leadership is acquired:
+
+{code}
+public void await()
+ throws InterruptedException,
+ EOFException
+Causes the current thread to wait until this instance acquires leadership
+unless the thread is interrupted or closed.
+{code}
+
+{code}
+public boolean await(long timeout,
+ TimeUnit unit)
+ throws InterruptedException
+Causes the current thread to wait until this instance acquires leadership unless
+the thread is interrupted, the specified waiting time elapses or the instance is closed.
+
+Parameters:
+timeout - the maximum time to wait
+unit - the time unit of the timeout argument
+Returns:
+true if the count reached zero and false if the waiting time elapsed before the count
+reached zero or the instances was closed
+{code}
+
+When you are through with the LeaderLatch instance, you must call close. This removes the instance from the leader election and releases leadership if the instance has it. Once leadership is released, another participating instance (if any) will be chosen as leader.
+{code}
+leaderLatch.close();
+{code}
+
+h2. Error Handling
+LeaderLatch instances add a ConnectionStateListener to watch for connection problems. If SUSPENDED or LOST is reported, the LeaderLatch that is the leader will report that it is no longer the leader (i.e. there will not be a leader until the connection is re-established). If a LOST connection is RECONNECTED, the LeaderLatch will delete its previous ZNode and create a new one.
+
+Users of LeaderLatch must take account that connection issues can cause leadership to be lost. i.e. hasLeadership() returns true but some time later the connection is SUSPENDED or LOST. At that point hasLeadership() will return false. It is highly recommended that LeaderLatch users register a ConnectionStateListener.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/multi-shared-lock.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/multi-shared-lock.confluence b/curator-recipes/src/site/confluence/multi-shared-lock.confluence
new file mode 100644
index 0000000..7d2bcd7
--- /dev/null
+++ b/curator-recipes/src/site/confluence/multi-shared-lock.confluence
@@ -0,0 +1,36 @@
+h1. Multi Shared Lock
+
+h2. Description
+A container that manages multiple locks as a single entity. When acquire() is called, all the locks are acquired. If that fails,
+any paths that were acquired are released. Similarly, when release() is called, all locks are released (failures are ignored).
+
+h2. Participating Classes
+* InterProcessMultiLock
+* InterProcessLock
+
+h2. Usage
+h3. Creating a InterProcessMultiLock
+{code}
+public InterProcessMultiLock(List<InterProcessLock> locks)
+Creates a multi lock of any type of inter process lock
+Parameters:
+locks - the locks
+{code}
+
+{code}
+public InterProcessMultiLock(CuratorFramework client,
+ List<String> paths)
+Creates a multi lock of InterProcessMutexes
+Parameters:
+client - client
+paths - list of paths to manage in the order that they are to be locked
+{code}
+
+h2. General Usage
+The usage is the same as for [[Shared Lock|shared-lock.html]]. However, When acquire() is called, all the locks are acquired. If that
+fails, any paths that were acquired are released. Similarly, when release() is called, all locks are released (failures are ignored).
+
+h2. Error Handling
+It is strongly recommended that you add a {{ConnectionStateListener}} and watch for SUSPENDED and LOST state changes. If a
+SUSPENDED state is reported you cannot be certain that you still hold the lock unless you subsequently receive a
+RECONNECTED state. If a LOST state is reported it is certain that you no longer hold the lock.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/shared-lock.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/shared-lock.confluence b/curator-recipes/src/site/confluence/shared-lock.confluence
new file mode 100644
index 0000000..aeb2eb0
--- /dev/null
+++ b/curator-recipes/src/site/confluence/shared-lock.confluence
@@ -0,0 +1,48 @@
+h1. Shared Lock
+
+h2. Description
+Fully distributed locks that are globally synchronous, meaning at any snapshot in time no two clients think
+they hold the same lock. Note: unlike InterProcessMutex this lock is *not* reentrant.
+
+h2. Participating Classes
+* InterProcessSemaphoreMutex
+
+h2. Usage
+h3. Create an InterProcessSemaphoreMutex
+{code}
+public InterProcessSemaphoreMutex(CuratorFramework client,
+ String path)
+Parameters:
+client - client
+path - the path to lock
+{code}
+
+h3. General Usage
+To acquire the lock, use one of the acquire methods:
+{code}
+public void acquire()
+Acquire the mutex - blocking until it's available. Must be balanced by a call to release().
+{code}
+
+{code}
+public boolean acquire(long time,
+ TimeUnit unit)
+Acquire the mutex - blocks until it's available or the given time expires. Must be balanced by a call to release().
+
+Parameters:
+time - time to wait
+unit - time unit
+Returns:
+true if the mutex was acquired, false if not
+{code}
+
+To release the mutex, call:
+{code}
+public void release()
+Perform one release of the mutex if the calling thread is the same thread that acquired it.
+{code}
+
+h2. Error Handling
+It is strongly recommended that you add a {{ConnectionStateListener}} and watch for SUSPENDED and LOST state changes.
+If a SUSPENDED state is reported you cannot be certain that you still hold the lock unless you subsequently receive a
+RECONNECTED state. If a LOST state is reported it is certain that you no longer hold the lock.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/shared-reentrant-lock.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/shared-reentrant-lock.confluence b/curator-recipes/src/site/confluence/shared-reentrant-lock.confluence
new file mode 100644
index 0000000..ce3784c
--- /dev/null
+++ b/curator-recipes/src/site/confluence/shared-reentrant-lock.confluence
@@ -0,0 +1,72 @@
+h1. Shared Reentrant Lock
+
+h2. Description
+Fully distributed locks that are globally synchronous, meaning at any snapshot in time no two clients think they hold the same lock.
+
+h2. Participating Classes
+* InterProcessMutex
+
+h2. Usage
+h3. Create an InterProcessMutex
+{code}
+public InterProcessMutex(CuratorFramework client,
+ String path)
+Parameters:
+client - client
+path - the path to lock
+{code}
+
+h3. General Usage
+To acquire the lock, use one of the acquire methods:
+{code}
+public void acquire()
+Acquire the mutex - blocking until it's available. Note: the same thread can call acquire
+re-entrantly. Each call to acquire must be balanced by a call to release()
+{code}
+{code}
+public boolean acquire(long time,
+ TimeUnit unit)
+Acquire the mutex - blocks until it's available or the given time expires. Note: the same thread can
+call acquire re-entrantly. Each call to acquire that returns true must be balanced by a call to release()
+
+Parameters:
+time - time to wait
+unit - time unit
+Returns:
+true if the mutex was acquired, false if not
+{code}
+
+To release the mutex, call:
+{code}
+public void release()
+Perform one release of the mutex if the calling thread is the same thread that acquired it. If the
+thread had made multiple calls to acquire, the mutex will still be held when this method returns.
+{code}
+
+*NOTE:* A InterProcessMutex instance is reusable. i.e. don't create a new instance every time. Re-use a single instance.
+
+h3. Revoking
+InterProcessMutex supports a cooperative revocation mechanism as described on the ZooKeeper recipes wiki.
+
+To make a mutex revocable, call:
+{code}
+public void makeRevocable(RevocationListener<T> listener)
+Make the lock revocable. Your listener will get called when another process/thread wants you to release the lock. Revocation is cooperative.
+Parameters:
+listener - the listener
+{code}
+
+To ask for a lock to revoke/release, use the static method in the {{Revoker}} class:
+{code}
+public static void attemptRevoke(CuratorFramework client,
+ String path)
+ throws Exception
+Utility to mark a lock for revocation. Assuming that the lock has been registered
+with a RevocationListener, it will get called and the lock should be released. Note,
+however, that revocation is cooperative.
+Parameters:
+client - the client
+path - the path of the lock - usually from something like InterProcessMutex.getParticipantNodes()
+{code}
+h2. Error Handling
+It is strongly recommended that you add a {{ConnectionStateListener}} and watch for SUSPENDED and LOST state changes. If a SUSPENDED state is reported you cannot be certain that you still hold the lock unless you subsequently receive a RECONNECTED state. If a LOST state is reported it is certain that you no longer hold the lock.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/shared-reentrant-read-write-lock.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/shared-reentrant-read-write-lock.confluence b/curator-recipes/src/site/confluence/shared-reentrant-read-write-lock.confluence
new file mode 100644
index 0000000..2860edd
--- /dev/null
+++ b/curator-recipes/src/site/confluence/shared-reentrant-read-write-lock.confluence
@@ -0,0 +1,46 @@
+h1. Shared Reentrant Read Write Lock
+
+h2. Description
+A re-entrant read/write mutex that works across JVMs. Uses Zookeeper to hold the lock. All processes in all
+JVMs that use the same lock path will achieve an inter-process critical section. Further, this mutex is "fair" -
+each user will get the mutex in the order requested (from ZK's point of view).
+
+A read write lock maintains a pair of associated locks, one for read-only operations and one for writing. The read
+lock may be held simultaneously by multiple reader processes, so long as there are no writers. The write lock is exclusive.
+
+_Reentrancy_
+This lock allows both readers and writers to reacquire read or write locks in the style of a re-entrant lock.
+Non-re-entrant readers are not allowed until all write locks held by the writing thread/process have been released.
+Additionally, a writer can acquire the read lock, but not vice-versa. If a reader tries to acquire the write lock it will never succeed.
+
+_Lock Downgrading_
+Re-entrancy also allows downgrading from the write lock to a read lock, by acquiring the write lock, then the read
+lock and then releasing the write lock. However, upgrading from a read lock to the write lock is not possible.
+
+h2. Participating Classes
+* InterProcessReadWriteLock
+* InterProcessLock
+
+h2. Usage
+h3. Create an InterProcessReadWriteLock
+{code}
+public InterProcessReadWriteLock(CuratorFramework client,
+ String basePath)
+Parameters:
+client - the client
+basePath - path to use for locking
+{code}
+
+h3. General Usage
+Access either the read lock or the write lock and then use the methods as described for [[Shared lock]].
+
+{code}
+public InterProcessLock readLock()
+
+public InterProcessLock writeLock()
+{code}
+
+h2. Error Handling
+It is strongly recommended that you add a {{ConnectionStateListener}} and watch for SUSPENDED and
+LOST state changes. If a SUSPENDED state is reported you cannot be certain that you still hold the lock unless you
+subsequently receive a RECONNECTED state. If a LOST state is reported it is certain that you no longer hold the lock.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/shared-semaphore.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/shared-semaphore.confluence b/curator-recipes/src/site/confluence/shared-semaphore.confluence
new file mode 100644
index 0000000..45d3d3a
--- /dev/null
+++ b/curator-recipes/src/site/confluence/shared-semaphore.confluence
@@ -0,0 +1,102 @@
+h1. Shared Semaphore
+
+h2. Description
+A counting semaphore that works across JVMs. All processes in all JVMs that use the same lock path will achieve an inter-process limited set of leases. Further, this semaphore is mostly "fair" - each user will get a lease in the order requested (from ZK's point of view).
+
+There are two modes for determining the max leases for the semaphore. In the first mode the max leases is a convention maintained by the users of a given path. In the second mode a SharedCountReader is used as the method for semaphores of a given path to determine the max leases.
+
+If a SharedCountReader is not used, no internal checks are done to prevent Process A acting as if there are 10 leases and Process B acting as if there are 20. Therefore, make sure that all instances in all processes use the same numberOfLeases value.
+
+The various acquire methods return Lease objects that represent acquired leases. Clients must take care to close lease objects (ideally in a {{finally}} block) else the lease will be lost. However, if the client session drops (crash, etc.), any leases held by the client are automatically closed and made available to other clients.
+
+h2. Participating Classes
+* InterProcessSemaphoreV2
+* Lease
+* SharedCountReader
+
+h2. Usage
+h3. Creating an InterProcessSemaphoreV2
+{code}
+public InterProcessSemaphoreV2(CuratorFramework client,
+ String path,
+ int numberOfLeases)
+Parameters:
+client - client
+path - the path to lock
+numberOfLeases - the number of leases allowed by this semaphore
+{code}
+
+{code}
+public InterProcessSemaphoreV2(CuratorFramework client,
+ String path,
+ SharedCountReader count)
+Parameters:
+client - the client
+path - path for the semaphore
+count - the shared count to use for the max leases
+{code}
+
+h2. General Usage
+To acquire one lease/usage, use one of the acquire methods:
+
+{code}
+public Lease acquire()
+
+Acquire a lease. If no leases are available, this method blocks until either the maximum number of
+leases is increased or another client/process closes a lease.
+The client must close the lease when it is done with it. You should do this in a finally block.
+Returns:
+the new lease
+{code}
+
+{code}
+public Collection<Lease> acquire(int qty)
+
+Acquire qty leases. If there are not enough leases available, this method blocks until either the
+maximum number of leases is increased enough or other clients/processes close enough leases.
+The client must close the leases when it is done with them. You should do this in a finally block.
+NOTE: You can use returnAll(Collection) for this.
+Parameters:
+qty - number of leases to acquire
+Returns:
+the new leases
+{code}
+
+{code}
+public Lease acquire(long time,
+ TimeUnit unit)
+Acquire a lease. If no leases are available, this method blocks until either the maximum number of
+leases is increased or another client/process closes a lease. However, this method will only block
+to a maximum of the time parameters given.
+The client must close the lease when it is done with it. You should do this in a finally block.
+Parameters:
+time - time to wait
+unit - time unit
+Returns:
+the new lease or null if time ran out
+{code}
+
+{code}
+public Collection<Lease> acquire(int qty,
+ long time,
+ TimeUnit unit)
+Acquire qty leases. If there are not enough leases available, this method blocks until either the
+maximum number of leases is increased enough or other clients/processes close enough leases. However,
+this method will only block to a maximum of the time parameters given. If time expires before all
+leases are acquired, the subset of acquired leases are automatically closed.
+The client must close the leases when it is done with them. You should do this in a finally block.
+NOTE: You can use returnAll(Collection) for this.
+Parameters:
+qty - number of leases to acquire
+time - time to wait
+unit - time unit
+{code}
+
+{{Lease}} instances can either be closed directly or you can use these convenience methods:
+{code}
+public void returnAll(Collection<Lease> leases)
+public void returnLease(Lease lease)
+{code}
+
+h2. Error Handling
+It is strongly recommended that you add a {{ConnectionStateListener}} and watch for SUSPENDED and LOST state changes. If a SUSPENDED state is reported you cannot be certain that you still hold the lock unless you subsequently receive a RECONNECTED state. If a LOST state is reported it is certain that you no longer hold the lock.
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/confluence/simple-distributed-queue.confluence
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/confluence/simple-distributed-queue.confluence b/curator-recipes/src/site/confluence/simple-distributed-queue.confluence
new file mode 100644
index 0000000..2e78c50
--- /dev/null
+++ b/curator-recipes/src/site/confluence/simple-distributed-queue.confluence
@@ -0,0 +1,51 @@
+h1. Simple Distributed Queue
+
+h2. *IMPORTANT* - We recommend that you do NOT use ZooKeeper for Queues. Please see [[Tech Note 4|../tech-note-4.html]] for details.
+
+h2. Description
+
+A drop-in replacement for the DistributedQueue that comes with the ZK distribution.
+
+h2. Participating Classes
+
+* SimpleDistributedQueue
+
+h2. Usage
+
+*Creating a SimpleDistributedQueue*
+
+{code}
+public SimpleDistributedQueue(CuratorFramework client,
+ String path)
+Parameters:
+client - the client
+path - path to store queue nodes
+{code}
+
+*Add to the queue*
+
+{code}
+public boolean offer(byte[] data)
+ throws Exception
+Inserts data into queue.
+Parameters:
+data - the data
+Returns:
+true if data was successfully added
+{code}
+
+*Take from the queue*
+
+{code}
+public byte[] take()
+ throws Exception
+Removes the head of the queue and returns it, blocks until it succeeds.
+Returns:
+The former head of the queue
+{code}
+
+NOTE: see the Javadoc for additional methods
+
+h2. Error Handling
+It is strongly recommended that you add a {{ConnectionStateListener}} and watch for SUSPENDED and LOST state changes.
+
http://git-wip-us.apache.org/repos/asf/incubator-curator/blob/af6a77ed/curator-recipes/src/site/resources/css/site.css
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/resources/css/site.css b/curator-recipes/src/site/resources/css/site.css
new file mode 100644
index 0000000..f847d66
--- /dev/null
+++ b/curator-recipes/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/af6a77ed/curator-recipes/src/site/site.xml
----------------------------------------------------------------------
diff --git a/curator-recipes/src/site/site.xml b/curator-recipes/src/site/site.xml
new file mode 100644
index 0000000..4e991cc
--- /dev/null
+++ b/curator-recipes/src/site/site.xml
@@ -0,0 +1,31 @@
+<?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 Recipes">
+ <body>
+ <breadcrumbs>
+ <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/af6a77ed/src/site/resources/css/site.css
----------------------------------------------------------------------
diff --git a/src/site/resources/css/site.css b/src/site/resources/css/site.css
new file mode 100644
index 0000000..f847d66
--- /dev/null
+++ b/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/af6a77ed/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 6991a99..618913e 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -17,7 +17,8 @@
~ 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="${project.name}">
+<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>
@@ -39,14 +40,29 @@
<publishDate/>
<body>
+ <links>
+ <item name="Apache ZooKeeper" href="http://zookeeper.apache.org"/>
+ </links>
+
<menu name="Apache Curator">
- <item name="Home" href="index.html" />
- <item name="Getting Started" href="getting-started.html" />
+ <item name="Home" href="index.html"/>
+ <item name="Getting Started" href="getting-started.html"/>
+ <item name="Recipes" href="curator-recipes/index.html"/>
+ </menu>
+
+ <menu name="ASF" inherit="bottom">
+ <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/"/>
+ <item name="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html"/>
+ <item name="Thanks" href="http://www.apache.org/foundation/thanks.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.
+ <div class="row span12">
+ 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.
</div>
</footer>
</body>