com.twitter.common.zookeeper
Class ZooKeeperClient

java.lang.Object
  extended by com.twitter.common.zookeeper.ZooKeeperClient

public class ZooKeeperClient
extends Object

Manages a connection to a ZooKeeper cluster.


Nested Class Summary
static interface ZooKeeperClient.Credentials
          Encapsulates a user's credentials and has the ability to authenticate them through a ZooKeeper client.
 class ZooKeeperClient.ZooKeeperConnectionException
          Indicates an error connecting to a zookeeper cluster.
 
Constructor Summary
ZooKeeperClient(Amount<Integer,Time> sessionTimeout, InetSocketAddress zooKeeperServer, InetSocketAddress... zooKeeperServers)
          Creates an unconnected client that will lazily attempt to connect on the first call to get().
ZooKeeperClient(Amount<Integer,Time> sessionTimeout, Iterable<InetSocketAddress> zooKeeperServers)
          Creates an unconnected client that will lazily attempt to connect on the first call to get().
ZooKeeperClient(Amount<Integer,Time> sessionTimeout, ZooKeeperClient.Credentials credentials, InetSocketAddress zooKeeperServer, InetSocketAddress... zooKeeperServers)
          Creates an unconnected client that will lazily attempt to connect on the first call to get().
ZooKeeperClient(Amount<Integer,Time> sessionTimeout, ZooKeeperClient.Credentials credentials, Iterable<InetSocketAddress> zooKeeperServers)
          Creates an unconnected client that will lazily attempt to connect on the first call to get().
 
Method Summary
 void close()
          Closes the current connection if any expiring the current ZooKeeper session.
static ZooKeeperClient.Credentials credentials(String scheme, byte[] authToken)
          Creates a set of credentials for the given authentication scheme.
static ZooKeeperClient.Credentials digestCredentials(String username, String password)
          Creates a set of credentials for the zoo keeper digest authentication mechanism.
 org.apache.zookeeper.ZooKeeper get()
          Returns the current active ZK connection or establishes a new one if none has yet been established or a previous connection was disconnected or had its session time out.
 org.apache.zookeeper.ZooKeeper get(Amount<Long,Time> connectionTimeout)
          Returns the current active ZK connection or establishes a new one if none has yet been established or a previous connection was disconnected or had its session time out.
 void register(org.apache.zookeeper.Watcher watcher)
          Clients that need to register a top-level Watcher should do so using this method.
 org.apache.zookeeper.Watcher registerExpirationHandler(Command onExpired)
          Clients that need to re-establish state after session expiration can register an onExpired command to execute.
 boolean shouldRetry(org.apache.zookeeper.KeeperException e)
          Checks to see if the client might reasonably re-try an operation given the exception thrown while attempting it.
 boolean unregister(org.apache.zookeeper.Watcher watcher)
          Clients can attempt to unregister a top-level Watcher that has previously been registered.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ZooKeeperClient

public ZooKeeperClient(Amount<Integer,Time> sessionTimeout,
                       InetSocketAddress zooKeeperServer,
                       InetSocketAddress... zooKeeperServers)
Creates an unconnected client that will lazily attempt to connect on the first call to get().

Parameters:
sessionTimeout - the ZK session timeout
zooKeeperServer - the first, required ZK server
zooKeeperServers - any additional servers forming the ZK cluster

ZooKeeperClient

public ZooKeeperClient(Amount<Integer,Time> sessionTimeout,
                       Iterable<InetSocketAddress> zooKeeperServers)
Creates an unconnected client that will lazily attempt to connect on the first call to get().

Parameters:
sessionTimeout - the ZK session timeout
zooKeeperServers - the set of servers forming the ZK cluster

ZooKeeperClient

public ZooKeeperClient(Amount<Integer,Time> sessionTimeout,
                       ZooKeeperClient.Credentials credentials,
                       InetSocketAddress zooKeeperServer,
                       InetSocketAddress... zooKeeperServers)
Creates an unconnected client that will lazily attempt to connect on the first call to get(). All successful connections will be authenticated with the given credentials.

Parameters:
sessionTimeout - the ZK session timeout
credentials - the credentials to authenticate with
zooKeeperServer - the first, required ZK server
zooKeeperServers - any additional servers forming the ZK cluster

ZooKeeperClient

public ZooKeeperClient(Amount<Integer,Time> sessionTimeout,
                       ZooKeeperClient.Credentials credentials,
                       Iterable<InetSocketAddress> zooKeeperServers)
Creates an unconnected client that will lazily attempt to connect on the first call to get(). All successful connections will be authenticated with the given credentials.

Parameters:
sessionTimeout - the ZK session timeout
credentials - the credentials to authenticate with
zooKeeperServers - the set of servers forming the ZK cluster
Method Detail

digestCredentials

public static ZooKeeperClient.Credentials digestCredentials(String username,
                                                            String password)
Creates a set of credentials for the zoo keeper digest authentication mechanism.

Parameters:
username - the username to authenticate with
password - the password to authenticate with
Returns:
a set of credentials that can be used to authenticate the zoo keeper client

credentials

public static ZooKeeperClient.Credentials credentials(String scheme,
                                                      byte[] authToken)
Creates a set of credentials for the given authentication scheme.

Parameters:
scheme - the scheme to authenticate with
authToken - the authentication token
Returns:
a set of credentials that can be used to authenticate the zoo keeper client

get

public org.apache.zookeeper.ZooKeeper get()
                                   throws ZooKeeperClient.ZooKeeperConnectionException,
                                          InterruptedException
Returns the current active ZK connection or establishes a new one if none has yet been established or a previous connection was disconnected or had its session time out. This method will attempt to re-use sessions when possible. Equivalent to:
get(Amount.of(0L, ...)
.

Returns:
a connected ZooKeeper client
Throws:
ZooKeeperClient.ZooKeeperConnectionException - if there was a problem connecting to the ZK cluster
InterruptedException - if interrupted while waiting for a connection to be established

get

public org.apache.zookeeper.ZooKeeper get(Amount<Long,Time> connectionTimeout)
                                   throws ZooKeeperClient.ZooKeeperConnectionException,
                                          InterruptedException,
                                          TimeoutException
Returns the current active ZK connection or establishes a new one if none has yet been established or a previous connection was disconnected or had its session time out. This method will attempt to re-use sessions when possible.

Parameters:
connectionTimeout - the maximum amount of time to wait for the connection to the ZK cluster to be established; 0 to wait forever
Returns:
a connected ZooKeeper client
Throws:
ZooKeeperClient.ZooKeeperConnectionException - if there was a problem connecting to the ZK cluster
InterruptedException - if interrupted while waiting for a connection to be established
TimeoutException - if a connection could not be established within the configured session timeout

registerExpirationHandler

public org.apache.zookeeper.Watcher registerExpirationHandler(Command onExpired)
Clients that need to re-establish state after session expiration can register an onExpired command to execute.

Parameters:
onExpired - the Command to register
Returns:
the new Watcher which can later be passed to unregister(org.apache.zookeeper.Watcher) for removal.

register

public void register(org.apache.zookeeper.Watcher watcher)
Clients that need to register a top-level Watcher should do so using this method. The registered watcher will remain registered across re-connects and session expiration events.

Parameters:
watcher - the Watcher to register

unregister

public boolean unregister(org.apache.zookeeper.Watcher watcher)
Clients can attempt to unregister a top-level Watcher that has previously been registered.

Parameters:
watcher - the Watcher to unregister as a top-level, persistent watch
Returns:
whether the given Watcher was found and removed from the active set

shouldRetry

public boolean shouldRetry(org.apache.zookeeper.KeeperException e)
Checks to see if the client might reasonably re-try an operation given the exception thrown while attempting it. If the ZooKeeper session should be expired to enable the re-try to succeed this method will expire it as a side-effect.

Parameters:
e - the exception to test
Returns:
true if a retry can be attempted

close

public void close()
Closes the current connection if any expiring the current ZooKeeper session. Any subsequent calls to this method will no-op until the next successful get().