com.bigdata.zookeeper
Class ZooKeeperAccessor

java.lang.Object
  com.bigdata.zookeeper.ZooKeeperAccessor

public class ZooKeeperAccessor
extends Object

Interface exposing a ZooKeeper client that may be transparently replaced by a new instance in response to a KeeperException.SessionExpiredException.

The KeeperException.SessionExpiredException is a severe error. A ZooKeeper instance which throws this exception WILL NOT reconnect. This is by design since in general the application needs to be aware of expired sessions and take correcting actions.

A KeeperException.SessionExpiredException means that all ephemeral znodes for the ZooKeeper have been discarded by the ensemble. An application MUST be extremely careful in using this interface that they do not violate assumptions concerning their state within the zookeeper ensemble.

To ensure this, the application SHOULD use the following pattern.

1. Obtain ZooKeeper client from this interface.

   Note that the client MIGHT already have an expired session which has not yet been reported to the watcher behind this interface. The implementation will allocate a new ZooKeeper client if ZooKeeper.getState() is ZooKeeper.States#CLOSED. Therefore the first event observed by (2) MIGHT be ZooKeeper.States#CLOSED (or equivalently, the first request made using the client MIGHT throw a KeeperException.SessionExpiredException), in which case the application MUST request a new ZooKeeper client from this interface.

   A ZooKeeper ensemble will sometimes drop the ball on your client, causing it to receive a KeeperException.SessionExpiredException. This can happen because your client was temporarily partitioned, but it can also happen under heavy load - presumably because the client fails to maintain its lease with the ZooKeeper ensemble when under load.

2. When KeeperException.SessionExpiredException is thrown or the state for a WatchedEvent is ZooKeeper.States#CLOSED:
   • Handle the expired session in any manner demanded by the watcher's local semantics. All ephemeral znodes for the old ZooKeeper client will have been deleted so this is your chance to clean things up. You may also have to halt processing based on the assumption that you are holding a ZLock, etc.
   • If the event was survivable, then obtain a new ZooKeeper client using this interface (e.g., goto 1).

Version:

$Id$

Author:

Bryan Thompson

See Also:

http://wiki.apache.org/hadoop/ZooKeeper/FAQ, which has a state transition diagram for the {@link ZooKeeper} client. FIXME Check all use of {@link SessionExpiredException}, of {@link ZooKeeper.States#CLOSED} or {@link ZooKeeper.States#isAlive()}, and of {@link KeeperState#Expired} TODO This does not make any systematic attempt to facilitate handling the other absorbing state which is an authentication failure.

Field Summary

String	hosts The hosts parameter.
int	sessionTimeout The session timeout parameter.

Constructor Summary

ZooKeeperAccessor(String hosts, int sessionTimeout)

Method Summary

void	addWatcher(org.apache.zookeeper.Watcher w) Adds a Watcher which will receive WatchedEvents until it is removed.
boolean	awaitZookeeperConnected(long timeout, TimeUnit unit) Await ZooKeeper to be ZooKeeper.States#CONNECTED, but not more than the specified timeout.
void	close() If the accessor is open, then it is closed.
protected void	finalize() Ensure that we close the associated ZooKeeper connection.
org.apache.zookeeper.ZooKeeper	getZookeeper() Return a ZooKeeper instance that is not "dead" as reported by ZooKeeper.States#isAlive().
boolean	isOpen()
void	removeWatcher(org.apache.zookeeper.Watcher w) Remove a Watcher.

Methods inherited from class java.lang.Object

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

Field Detail

hosts

public final String hosts

The hosts parameter.

sessionTimeout

public final int sessionTimeout

The session timeout parameter.

Constructor Detail

ZooKeeperAccessor

public ZooKeeperAccessor(String hosts,
                         int sessionTimeout)
                  throws InterruptedException

Parameters:

hosts -

sessionTimeout -

Throws:

InterruptedException - if the caller's thread is interrupted while awaiting a zookeeper client connection.

Method Detail

finalize

protected void finalize()
                 throws Throwable

Ensure that we close the associated ZooKeeper connection.

Overrides:

finalize in class Object

Throws:

Throwable

getZookeeper

public org.apache.zookeeper.ZooKeeper getZookeeper()
                                            throws InterruptedException

Return a ZooKeeper instance that is not "dead" as reported by ZooKeeper.States#isAlive(). This method will block and retry if there is an IOException connecting to the ensemble and will log errors during such retries.

Throws:

IllegalStateException - if this class is closed.

InterruptedException - if the caller's thread is interrupted while awaiting a zookeeper client connection.

TODO:

variant with timeout, perhaps running on an executor service.

close

public void close()
           throws InterruptedException

If the accessor is open, then it is closed. If there is a Zookeeper instance, then it is closed to release the session with which it is associated.

Throws:

InterruptedException - if interrupted before ZooKeeper.close() was finished. If this case this object will continue to report that it isOpen() and should be close()d again.

isOpen

public boolean isOpen()

awaitZookeeperConnected

public boolean awaitZookeeperConnected(long timeout,
                                       TimeUnit unit)
                                throws InterruptedException

Await ZooKeeper to be ZooKeeper.States#CONNECTED, but not more than the specified timeout. Note that even a true return DOES NOT mean that the Zookeeper instance returned by getZookeeper() will be connected by the time you attempt to use it.

Parameters:

timeout -

unit -

Returns:

true if we noticed the ZooKeeper client entering the connected state before the timeout.

Throws:

InterruptedException - if interrupted awaiting the ZooKeeper client to be connected.

IllegalStateException - if this class is closed.

addWatcher

public void addWatcher(org.apache.zookeeper.Watcher w)

Adds a Watcher which will receive WatchedEvents until it is removed.

Parameters:

w - The watcher.

removeWatcher

public void removeWatcher(org.apache.zookeeper.Watcher w)

Remove a Watcher.

Parameters:

w - The watcher.