org.apache.giraph.zk

Class ZooKeeperExt

java.lang.Object

org.apache.giraph.zk.ZooKeeperExt

public class ZooKeeperExt
extends Object

ZooKeeper provides only atomic operations. ZooKeeperExt provides additional non-atomic operations that are useful. It also provides wrappers to deal with ConnectionLossException. All methods of this class should be thread-safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ZooKeeperExt.PathStat Data structure for handling the output of createOrSet()

Field Summary

Fields

Modifier and Type	Field and Description
static int	SEQUENCE_NUMBER_LENGTH Length of the ZK sequence number

Constructor Summary

Constructors

Constructor and Description
ZooKeeperExt(String connectString, int sessionTimeout, int maxRetryAttempts, int retryWaitMsecs, org.apache.zookeeper.Watcher watcher) Constructor to connect to ZooKeeper, does not make progress
ZooKeeperExt(String connectString, int sessionTimeout, int maxRetryAttempts, int retryWaitMsecs, org.apache.zookeeper.Watcher watcher, org.apache.hadoop.util.Progressable progressable) Constructor to connect to ZooKeeper, make progress

Method Summary

Modifier and Type	Method and Description
void	close() Close this client object.
String	createExt(String path, byte[] data, List<org.apache.zookeeper.data.ACL> acl, org.apache.zookeeper.CreateMode createMode, boolean recursive) Provides a possibility of a creating a path consisting of more than one znode (not atomic).
ZooKeeperExt.PathStat	createOnceExt(String path, byte[] data, List<org.apache.zookeeper.data.ACL> acl, org.apache.zookeeper.CreateMode createMode, boolean recursive) Create a znode if there is no other znode there
ZooKeeperExt.PathStat	createOrSetExt(String path, byte[] data, List<org.apache.zookeeper.data.ACL> acl, org.apache.zookeeper.CreateMode createMode, boolean recursive, int version) Create a znode.
void	deleteExt(String path, int version, boolean recursive) Delete a path recursively.
org.apache.zookeeper.data.Stat	exists(String path, boolean watch) Return the stat of the node of the given path.
org.apache.zookeeper.data.Stat	exists(String path, org.apache.zookeeper.Watcher watcher) Return the stat of the node of the given path.
List<String>	getChildrenExt(String path, boolean watch, boolean sequenceSorted, boolean fullPath) Get the children of the path with extensions.
byte[]	getData(String path, boolean watch, org.apache.zookeeper.data.Stat stat) Return the data and the stat of the node of the given path.
byte[]	getData(String path, org.apache.zookeeper.Watcher watcher, org.apache.zookeeper.data.Stat stat) Return the data and the stat of the node of the given path.

Methods inherited from class java.lang.Object

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

Field Detail

SEQUENCE_NUMBER_LENGTH

public static final int SEQUENCE_NUMBER_LENGTH

Length of the ZK sequence number

See Also:

Constant Field Values

Constructor Detail

ZooKeeperExt

public ZooKeeperExt(String connectString,
                    int sessionTimeout,
                    int maxRetryAttempts,
                    int retryWaitMsecs,
                    org.apache.zookeeper.Watcher watcher)
             throws IOException

Constructor to connect to ZooKeeper, does not make progress

Parameters:

connectString - Comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).

sessionTimeout - Session timeout in milliseconds

maxRetryAttempts - Max retry attempts during connection loss

retryWaitMsecs - Msecs to wait when retrying due to connection loss

watcher - A watcher object which will be notified of state changes, may also be notified for node events

Throws:

IOException

ZooKeeperExt

public ZooKeeperExt(String connectString,
                    int sessionTimeout,
                    int maxRetryAttempts,
                    int retryWaitMsecs,
                    org.apache.zookeeper.Watcher watcher,
                    org.apache.hadoop.util.Progressable progressable)
             throws IOException

Constructor to connect to ZooKeeper, make progress

Parameters:

connectString - Comma separated host:port pairs, each corresponding to a zk server. e.g. "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002" If the optional chroot suffix is used the example would look like: "127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the client would be rooted at "/app/a" and all paths would be relative to this root - ie getting/setting/etc... "/foo/bar" would result in operations being run on "/app/a/foo/bar" (from the server perspective).

sessionTimeout - Session timeout in milliseconds

maxRetryAttempts - Max retry attempts during connection loss

retryWaitMsecs - Msecs to wait when retrying due to connection loss

watcher - A watcher object which will be notified of state changes, may also be notified for node events

progressable - Makes progress for longer operations

Throws:

IOException

Method Detail

createExt

public String createExt(String path,
                        byte[] data,
                        List<org.apache.zookeeper.data.ACL> acl,
                        org.apache.zookeeper.CreateMode createMode,
                        boolean recursive)
                 throws org.apache.zookeeper.KeeperException,
                        InterruptedException

Provides a possibility of a creating a path consisting of more than one znode (not atomic). If recursive is false, operates exactly the same as create().

Parameters:

path - path to create

data - data to set on the final znode

acl - acls on each znode created

createMode - only affects the final znode

recursive - if true, creates all ancestors

Returns:

Actual created path

Throws:

org.apache.zookeeper.KeeperException

InterruptedException

createOrSetExt

public ZooKeeperExt.PathStat createOrSetExt(String path,
                                            byte[] data,
                                            List<org.apache.zookeeper.data.ACL> acl,
                                            org.apache.zookeeper.CreateMode createMode,
                                            boolean recursive,
                                            int version)
                                     throws org.apache.zookeeper.KeeperException,
                                            InterruptedException

Create a znode. Set the znode if the created znode already exists.

Parameters:

path - path to create

data - data to set on the final znode

acl - acls on each znode created

createMode - only affects the final znode

recursive - if true, creates all ancestors

version - Version to set if setting

Returns:

Path of created znode or Stat of set znode

Throws:

InterruptedException

org.apache.zookeeper.KeeperException

createOnceExt

public ZooKeeperExt.PathStat createOnceExt(String path,
                                           byte[] data,
                                           List<org.apache.zookeeper.data.ACL> acl,
                                           org.apache.zookeeper.CreateMode createMode,
                                           boolean recursive)
                                    throws org.apache.zookeeper.KeeperException,
                                           InterruptedException

Create a znode if there is no other znode there

Parameters:

path - path to create

data - data to set on the final znode

acl - acls on each znode created

createMode - only affects the final znode

recursive - if true, creates all ancestors

Returns:

Path of created znode or Stat of set znode

Throws:

InterruptedException

org.apache.zookeeper.KeeperException

deleteExt

public void deleteExt(String path,
                      int version,
                      boolean recursive)
               throws InterruptedException,
                      org.apache.zookeeper.KeeperException

Delete a path recursively. When the deletion is recursive, it is a non-atomic operation, hence, not part of ZooKeeper.

Parameters:

path - path to remove (i.e. /tmp will remove /tmp/1 and /tmp/2)

version - expected version (-1 for all)

recursive - if true, remove all children, otherwise behave like remove()

Throws:

InterruptedException

org.apache.zookeeper.KeeperException

exists

public org.apache.zookeeper.data.Stat exists(String path,
                                             boolean watch)
                                      throws org.apache.zookeeper.KeeperException,
                                             InterruptedException

Return the stat of the node of the given path. Return null if no such a node exists.

If the watch is true and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that creates/delete the node or sets the data on the node.

Parameters:

path - the node path

watch - whether need to watch this node

Returns:

the stat of the node of the given path; return null if no such a node exists.

Throws:

org.apache.zookeeper.KeeperException - If the server signals an error

InterruptedException - If the server transaction is interrupted.

exists

public org.apache.zookeeper.data.Stat exists(String path,
                                             org.apache.zookeeper.Watcher watcher)
                                      throws org.apache.zookeeper.KeeperException,
                                             InterruptedException

Return the stat of the node of the given path. Return null if no such a node exists.

If the watch is non-null and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that creates/delete the node or sets the data on the node.

Parameters:

path - the node path

watcher - explicit watcher

Returns:

the stat of the node of the given path; return null if no such a node exists.

Throws:

org.apache.zookeeper.KeeperException - If the server signals an error

InterruptedException - If the server transaction is interrupted.

IllegalArgumentException - if an invalid path is specified

getData

public byte[] getData(String path,
                      org.apache.zookeeper.Watcher watcher,
                      org.apache.zookeeper.data.Stat stat)
               throws org.apache.zookeeper.KeeperException,
                      InterruptedException

Return the data and the stat of the node of the given path.

If the watch is non-null and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that sets data on the node, or deletes the node.

A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

Parameters:

path - the given path

watcher - explicit watcher

stat - the stat of the node

Returns:

the data of the node

Throws:

org.apache.zookeeper.KeeperException - If the server signals an error with a non-zero error code

InterruptedException - If the server transaction is interrupted.

IllegalArgumentException - if an invalid path is specified

getData

public byte[] getData(String path,
                      boolean watch,
                      org.apache.zookeeper.data.Stat stat)
               throws org.apache.zookeeper.KeeperException,
                      InterruptedException

Return the data and the stat of the node of the given path.

If the watch is true and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that sets data on the node, or deletes the node.

A KeeperException with error code KeeperException.NoNode will be thrown if no node with the given path exists.

Parameters:

path - the given path

watch - whether need to watch this node

stat - the stat of the node

Returns:

the data of the node

Throws:

org.apache.zookeeper.KeeperException - If the server signals an error with a non-zero error code

InterruptedException - If the server transaction is interrupted.

getChildrenExt

public List<String> getChildrenExt(String path,
                                   boolean watch,
                                   boolean sequenceSorted,
                                   boolean fullPath)
                            throws org.apache.zookeeper.KeeperException,
                                   InterruptedException

Get the children of the path with extensions. Extension 1: Sort the children based on sequence number Extension 2: Get the full path instead of relative path

Parameters:

path - path to znode

watch - set the watch?

sequenceSorted - sort by the sequence number

fullPath - if true, get the fully znode path back

Returns:

list of children

Throws:

InterruptedException

org.apache.zookeeper.KeeperException

close

public void close()
           throws InterruptedException

Close this client object. Once the client is closed, its session becomes invalid. All the ephemeral nodes in the ZooKeeper server associated with the session will be removed. The watches left on those nodes (and on their parents) will be triggered.

Throws:

InterruptedException