com.bigdata.zookeeper
Class ZNodeLockWatcher

java.lang.Object
  com.bigdata.zookeeper.AbstractZNodeConditionWatcher
      com.bigdata.zookeeper.ZNodeLockWatcher

All Implemented Interfaces:

org.apache.zookeeper.Watcher

Deprecated. Replaced by ZNodeLockWatcher.ZLockImpl

public class ZNodeLockWatcher
extends AbstractZNodeConditionWatcher

Watcher supporting distributed synchronous lock pattern.

A lock is just a node with CreateMode.EPHEMERAL_SEQUENTIAL children modeling a queue of processes obeying a contract on the conditions under which a process may proceed. The process whose child is ordered first in the queue holds the lock. To release the lock the process simply deletes its node in the queue. Each process seeking a lock creates a new child that watches the previous child in the ordered queue. When it receives a WatchedEvent (NodeDeleted) for that child, it has reached the head of the queue.

Any processes wishing to contend for the lock must ensure the creation of the lock node. This is a CreateMode.PERSISTENT znode. The SEQUENTIAL flag COULD be used if processes have another means to communicate the identity of the lock node. Lacking such a mechanism, the lock node must have a zpath which can be computed by any process seeking to contend for the lock. That is normally accomplished by naming the lock node for a resource with a well known identity.

This class only watches the previous child in the queue (if any). Zookeeper does not permit you to delete the parent without deleting the children, so you will always the queue purged of children before the lock node itself is deleted. If the child deleted from the queue, the next child in the queue will be granted the lock.

Destroying the lock node will not cause the lock to be persistently destroyed if the conditions still exist under which processes will contend for that lock as some process will simply re-create the lock node and the queue will become re-populated over time.

While a queue may seem excessive for one time operations, it provides failover if the process holding the lock dies.

Version:

$Id$

Author:

Bryan Thompson

See Also:

getLock(ZooKeeper, String, List), ZNodeLockWatcher.ZLockImpl

Nested Class Summary

protected static class

ZNodeLockWatcher.ZLockImpl Deprecated. ZLock implementation class.

Nested classes/interfaces inherited from interface org.apache.zookeeper.Watcher

org.apache.zookeeper.Watcher.Event

Field Summary

protected static boolean	DEBUG Deprecated.
protected static boolean	INFO Deprecated.
static String	INVALID Deprecated. The suffix for a marker that is a sibling of the lock node.
protected static org.apache.log4j.Logger	log Deprecated.

Fields inherited from class com.bigdata.zookeeper.AbstractZNodeConditionWatcher

zookeeper, zpath

Constructor Summary

protected

ZNodeLockWatcher(org.apache.zookeeper.ZooKeeper zookeeper, String zpath, String zchild) Deprecated.

Method Summary

protected void	clearWatch() Deprecated. Clear any watches.
static ZNodeLockWatcher.ZLockImpl	getLock(org.apache.zookeeper.ZooKeeper zookeeper, String zpath, List<org.apache.zookeeper.data.ACL> acl) Deprecated. Replaced by ZLockImpl
protected boolean	isCancelled() Deprecated. This implementation always returns false but may be overriden to permit cancellation of AbstractZNodeConditionWatcher.awaitCondition(long, TimeUnit).
protected boolean	isConditionSatisified() Deprecated. Obtains the children of the lock node.
protected boolean	isConditionSatisified(org.apache.zookeeper.WatchedEvent event) Deprecated. Implementation must inspect the event and determine if the conditions are satisified.
protected void	toString(StringBuilder sb) Deprecated. Subclasses may extend this method to add additional state into the representation generated by AbstractZNodeConditionWatcher.toString().

Methods inherited from class com.bigdata.zookeeper.AbstractZNodeConditionWatcher

_resumeWatch, awaitCondition, awaitCondition, process, success, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

log

protected static final org.apache.log4j.Logger log

Deprecated.

INFO

protected static final boolean INFO

Deprecated.

DEBUG

protected static final boolean DEBUG

Deprecated.

INVALID

public static final transient String INVALID

Deprecated.

The suffix for a marker that is a sibling of the lock node. The presence of this marker indicates that the queue is being destroyed. The isConditionSatisified() logic will not allow a lock to be granted if this marker is found. Likewise, new children are not permitted into the queue when this marker is present. Note: If you are monitoring a znode whose children a lock nodes, then a child ending with this string IS NOT a lock node!

See Also:

Constant Field Values

Constructor Detail

ZNodeLockWatcher

protected ZNodeLockWatcher(org.apache.zookeeper.ZooKeeper zookeeper,
                           String zpath,
                           String zchild)

Deprecated.

Method Detail

isCancelled

protected boolean isCancelled()

Deprecated.

Description copied from class: AbstractZNodeConditionWatcher

This implementation always returns false but may be overriden to permit cancellation of AbstractZNodeConditionWatcher.awaitCondition(long, TimeUnit).

Overrides:

isCancelled in class AbstractZNodeConditionWatcher

Returns:

toString

protected void toString(StringBuilder sb)

Deprecated.

Description copied from class: AbstractZNodeConditionWatcher

Subclasses may extend this method to add additional state into the representation generated by AbstractZNodeConditionWatcher.toString().

Note: This implementation MUST be safe (no exceptions) and non-blocking.

Overrides:

toString in class AbstractZNodeConditionWatcher

clearWatch

protected void clearWatch()
                   throws org.apache.zookeeper.KeeperException,
                          InterruptedException

Deprecated.

Description copied from class: AbstractZNodeConditionWatcher

Clear any watches.

Specified by:

clearWatch in class AbstractZNodeConditionWatcher

Throws:

org.apache.zookeeper.KeeperException

InterruptedException

isConditionSatisified

protected boolean isConditionSatisified(org.apache.zookeeper.WatchedEvent event)
                                 throws org.apache.zookeeper.KeeperException,
                                        InterruptedException

Deprecated.

Description copied from class: AbstractZNodeConditionWatcher

Implementation must inspect the event and determine if the conditions are satisified.

Specified by:

isConditionSatisified in class AbstractZNodeConditionWatcher

Parameters:

event - The WatchedEvent

Returns:

true if the event satisified the condition.

Throws:

org.apache.zookeeper.KeeperException

InterruptedException

isConditionSatisified

protected boolean isConditionSatisified()
                                 throws org.apache.zookeeper.KeeperException,
                                        InterruptedException

Deprecated.

Obtains the children of the lock node. If the process is the first child, then it holds the lock and we return true. Otherwise, set a watch on the prior child in the queue.

If the lock node has been deleted then set the cancelled flag (the entire queue was destroyed, so we cancel any process contending for a lock).

If the zchild has been deleted then set the cancelled flag (this let's you break the lock by deleting the child).

If the client is not connected, then an exception will be thrown and the watch will resume with the next WatchedEvent.

Specified by:

isConditionSatisified in class AbstractZNodeConditionWatcher

Returns:

Return true iff the process holds the lock

Throws:

org.apache.zookeeper.KeeperException

InterruptedException

getLock

public static ZNodeLockWatcher.ZLockImpl getLock(org.apache.zookeeper.ZooKeeper zookeeper,
                                                 String zpath,
                                                 List<org.apache.zookeeper.data.ACL> acl)
                                          throws org.apache.zookeeper.KeeperException,
                                                 InterruptedException

Deprecated. Replaced by ZLockImpl

Return an object that may be used to acquire a distributed synchronous lock.

This method will create a new lock node if the znode identified by the zpath does not exist. However, it will reject the request if the lock node has been invalidated pending the destruction of the lock node and its queue. In design patterns where the lock node may be destroyed, this places the responsibility on the caller to verify that the lock node is pre-existing if they wish to avoid re-creating a lock node which has been destroyed.

Parameters:

zookeeper -

zpath - The path identifying the lock node.

acl -

Returns:

Throws:

org.apache.zookeeper.KeeperException

InterruptedException

ZLockNodeInvalidatedException - if the lock node has been invalidated but not yet destroyed.