com.twitter.common.zookeeper
Class Group

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

public class Group
extends Object

This class exposes methods for joining and monitoring distributed groups. The groups this class monitors are realized as persistent paths in ZooKeeper with ephemeral sequential child nodes for each member of a group.


Nested Class Summary
static interface Group.GroupChangeListener
          An interface to an object that listens for changes to a group's membership.
static class Group.JoinException
          Indicates an error joining a group.
static interface Group.Membership
          Represents membership in a distributed group.
static class Group.UpdateException
          Indicates an error updating a group member's data.
static class Group.WatchException
          Indicates an error watching a group.
 
Constructor Summary
Group(ZooKeeperClient zkClient, Iterable<org.apache.zookeeper.data.ACL> acl, String path)
          Equivalent to Group(ZooKeeperClient, Iterable, String, String) with a default nodeNamePrefix of 'member_'.
Group(ZooKeeperClient zkClient, Iterable<org.apache.zookeeper.data.ACL> acl, String path, String nodeNamePrefix)
          Creates a group rooted at the given path.
 
Method Summary
 byte[] getMemberData(String memberId)
          Gets the data for one of this groups members by querying ZooKeeper synchronously.
 String getMemberId(String nodePath)
           
 Iterable<String> getMemberIds()
          Returns the current list of group member ids by querying ZooKeeper synchronously.
 String getMemberPath(String memberId)
           
 Group.Membership join()
          Equivalent to calling join(null, null).
 Group.Membership join(Command onLoseMembership)
          Equivalent to calling join(null, onLoseMembership).
 Group.Membership join(Supplier<byte[]> memberData)
          Equivalent to calling join(memberData, null).
 Group.Membership join(Supplier<byte[]> memberData, Command onLoseMembership)
          Joins this group and returns the resulting Membership when successful.
 String toString()
           
 void watch(Group.GroupChangeListener groupChangeListener)
          Watches this group for the lifetime of this jvm process.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Group

public Group(ZooKeeperClient zkClient,
             Iterable<org.apache.zookeeper.data.ACL> acl,
             String path,
             String nodeNamePrefix)
Creates a group rooted at the given path. Paths must be absolute and trailing or duplicate slashes will be normalized. For example, all the following paths would create a group at the normalized path /my/distributed/group:

Parameters:
zkClient - the client to use for interactions with ZooKeeper
acl - the ACL to use for creating the persistent group path if it does not already exist
path - the absolute persistent path that represents this group
nodeNamePrefix - Node name prefix that denotes group membership.

Group

public Group(ZooKeeperClient zkClient,
             Iterable<org.apache.zookeeper.data.ACL> acl,
             String path)
Equivalent to Group(ZooKeeperClient, Iterable, String, String) with a default nodeNamePrefix of 'member_'.

Method Detail

getMemberPath

public String getMemberPath(String memberId)

getMemberId

public String getMemberId(String nodePath)

getMemberIds

public Iterable<String> getMemberIds()
                              throws ZooKeeperClient.ZooKeeperConnectionException,
                                     org.apache.zookeeper.KeeperException,
                                     InterruptedException
Returns the current list of group member ids by querying ZooKeeper synchronously.

Returns:
the ids of all the present members of this group
Throws:
ZooKeeperClient.ZooKeeperConnectionException - if there was a problem connecting to ZooKeeper
org.apache.zookeeper.KeeperException - if there was a problem reading this group's member ids
InterruptedException - if this thread is interrupted listing the group members

getMemberData

public byte[] getMemberData(String memberId)
                     throws ZooKeeperClient.ZooKeeperConnectionException,
                            org.apache.zookeeper.KeeperException,
                            InterruptedException
Gets the data for one of this groups members by querying ZooKeeper synchronously.

Parameters:
memberId - the id of the member whose data to retrieve
Returns:
the data associated with the memberId
Throws:
ZooKeeperClient.ZooKeeperConnectionException - if there was a problem connecting to ZooKeeper
org.apache.zookeeper.KeeperException - if there was a problem reading this member's data
InterruptedException - if this thread is interrupted retrieving the member data

join

public final Group.Membership join()
                            throws Group.JoinException,
                                   InterruptedException
Equivalent to calling join(null, null).

Throws:
Group.JoinException
InterruptedException

join

public final Group.Membership join(Supplier<byte[]> memberData)
                            throws Group.JoinException,
                                   InterruptedException
Equivalent to calling join(memberData, null).

Throws:
Group.JoinException
InterruptedException

join

public final Group.Membership join(@Nullable
                                   Command onLoseMembership)
                            throws Group.JoinException,
                                   InterruptedException
Equivalent to calling join(null, onLoseMembership).

Throws:
Group.JoinException
InterruptedException

join

public final Group.Membership join(Supplier<byte[]> memberData,
                                   @Nullable
                                   Command onLoseMembership)
                            throws Group.JoinException,
                                   InterruptedException
Joins this group and returns the resulting Membership when successful. Membership will be automatically cancelled when the current jvm process dies; however the returned Membership object can be used to cancel membership earlier. Unless Group.Membership.cancel() is called the membership will be maintained by re-establishing it silently in the background.

Any memberData given is persisted in the member node in ZooKeeper. If an onLoseMembership callback is supplied, it will be notified each time this member loses membership in the group.

Parameters:
memberData - a supplier of the data to store in the member node
onLoseMembership - a callback to notify when membership is lost
Returns:
a Membership object with the member details
Throws:
Group.JoinException - if there was a problem joining the group
InterruptedException - if this thread is interrupted awaiting completion of the join

watch

public final void watch(Group.GroupChangeListener groupChangeListener)
                 throws Group.WatchException,
                        InterruptedException
Watches this group for the lifetime of this jvm process. This method will block until the current group members are available, notify the groupChangeListener and then return. All further changes to the group membership will cause notifications on a background thread.

Parameters:
groupChangeListener - the listener to notify of group membership change events
Throws:
Group.WatchException - if there is a problem generating the 1st group membership list
InterruptedException - if interrupted waiting to gather the 1st group membership list

toString

public String toString()
Overrides:
toString in class Object