org.apache.hadoop.ha

Class ActiveStandbyElector

java.lang.Object

org.apache.hadoop.ha.ActiveStandbyElector

All Implemented Interfaces:

org.apache.zookeeper.AsyncCallback, org.apache.zookeeper.AsyncCallback.StatCallback, org.apache.zookeeper.AsyncCallback.StringCallback

@InterfaceAudience.Private
@InterfaceStability.Evolving
public class ActiveStandbyElector
extends Object
implements org.apache.zookeeper.AsyncCallback.StatCallback, org.apache.zookeeper.AsyncCallback.StringCallback

This class implements a simple library to perform leader election on top of Apache Zookeeper. Using Zookeeper as a coordination service, leader election can be performed by atomically creating an ephemeral lock file (znode) on Zookeeper. The service instance that successfully creates the znode becomes active and the rest become standbys.
This election mechanism is only efficient for small number of election candidates (order of 10's) because contention on single znode by a large number of candidates can result in Zookeeper overload.
The elector does not guarantee fencing (protection of shared resources) among service instances. After it has notified an instance about becoming a leader, then that instance must ensure that it meets the service consistency requirements. If it cannot do so, then it is recommended to quit the election. The application implements the ActiveStandbyElector.ActiveStandbyElectorCallback to interact with the elector

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ActiveStandbyElector.ActiveNotFoundException Exception thrown when there is no active leader
static interface	ActiveStandbyElector.ActiveStandbyElectorCallback Callback interface to interact with the ActiveStandbyElector object.

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

org.apache.zookeeper.AsyncCallback.ACLCallback, org.apache.zookeeper.AsyncCallback.Children2Callback, org.apache.zookeeper.AsyncCallback.ChildrenCallback, org.apache.zookeeper.AsyncCallback.DataCallback, org.apache.zookeeper.AsyncCallback.StatCallback, org.apache.zookeeper.AsyncCallback.StringCallback, org.apache.zookeeper.AsyncCallback.VoidCallback

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	BREADCRUMB_FILENAME
protected static String	LOCK_FILENAME Name of the lock znode used by the library.
static org.apache.commons.logging.Log	LOG

Constructor Summary

Constructors

Constructor and Description

ActiveStandbyElector(String zookeeperHostPorts, int zookeeperSessionTimeout, String parentZnodeName, List<org.apache.zookeeper.data.ACL> acl, List<ZKUtil.ZKAuthInfo> authInfo, ActiveStandbyElector.ActiveStandbyElectorCallback app) Create a new ActiveStandbyElector object The elector is created by providing to it the Zookeeper configuration, the parent znode under which to create the znode and a reference to the callback interface.

Method Summary

Methods

Modifier and Type	Method and Description
void	clearParentZNode() Clear all of the state held within the parent ZNode.
void	ensureParentZNode() Utility function to ensure that the configured base znode exists.
byte[]	getActiveData() get data set by the active leader
protected org.apache.zookeeper.ZooKeeper	getNewZooKeeper() Get a new zookeeper client instance.
void	joinElection(byte[] data) To participate in election, the app will call joinElection.
boolean	parentZNodeExists()
void	processResult(int rc, String path, Object ctx, org.apache.zookeeper.data.Stat stat) interface implementation of Zookeeper callback for monitor (exists)
void	processResult(int rc, String path, Object ctx, String name) interface implementation of Zookeeper callback for create
void	quitElection(boolean needFence) Any service instance can drop out of the election by calling quitElection.
protected void	sleepFor(int sleepMs) Sleep for the given number of milliseconds.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

LOCK_FILENAME

protected static final String LOCK_FILENAME

Name of the lock znode used by the library. Protected for access in test classes

See Also:

Constant Field Values

BREADCRUMB_FILENAME

protected static final String BREADCRUMB_FILENAME

See Also:

Constant Field Values

LOG

public static final org.apache.commons.logging.Log LOG

Constructor Detail

ActiveStandbyElector

public ActiveStandbyElector(String zookeeperHostPorts,
                    int zookeeperSessionTimeout,
                    String parentZnodeName,
                    List<org.apache.zookeeper.data.ACL> acl,
                    List<ZKUtil.ZKAuthInfo> authInfo,
                    ActiveStandbyElector.ActiveStandbyElectorCallback app)
                     throws IOException,
                            HadoopIllegalArgumentException,
                            org.apache.zookeeper.KeeperException

Create a new ActiveStandbyElector object
The elector is created by providing to it the Zookeeper configuration, the parent znode under which to create the znode and a reference to the callback interface.
The parent znode name must be the same for all service instances and different across services.
After the leader has been lost, a new leader will be elected after the session timeout expires. Hence, the app must set this parameter based on its needs for failure response time. The session timeout must be greater than the Zookeeper disconnect timeout and is recommended to be 3X that value to enable Zookeeper to retry transient disconnections. Setting a very short session timeout may result in frequent transitions between active and standby states during issues like network outages/GS pauses.

Parameters:

zookeeperHostPorts - ZooKeeper hostPort for all ZooKeeper servers

zookeeperSessionTimeout - ZooKeeper session timeout

parentZnodeName - znode under which to create the lock

acl - ZooKeeper ACL's

authInfo - a list of authentication credentials to add to the ZK connection

app - reference to callback interface object

Throws:

IOException

HadoopIllegalArgumentException

org.apache.zookeeper.KeeperException

Method Detail

joinElection

public void joinElection(byte[] data)
                  throws HadoopIllegalArgumentException

To participate in election, the app will call joinElection. The result will be notified by a callback on either the becomeActive or becomeStandby app interfaces.
After this the elector will automatically monitor the leader status and perform re-election if necessary
The app could potentially start off in standby mode and ignore the becomeStandby call.

Parameters:

data - to be set by the app. non-null data must be set.

Throws:

HadoopIllegalArgumentException - if valid data is not supplied

parentZNodeExists

public boolean parentZNodeExists()
                          throws IOException,
                                 InterruptedException

Returns:

true if the configured parent znode exists

Throws:

IOException

InterruptedException

ensureParentZNode

public void ensureParentZNode()
                       throws IOException,
                              InterruptedException

Utility function to ensure that the configured base znode exists. This recursively creates the znode as well as all of its parents.

Throws:

IOException

InterruptedException

clearParentZNode

public void clearParentZNode()
                      throws IOException,
                             InterruptedException

Clear all of the state held within the parent ZNode. This recursively deletes everything within the znode as well as the parent znode itself. It should only be used when it's certain that no electors are currently participating in the election.

Throws:

IOException

InterruptedException

quitElection

public void quitElection(boolean needFence)

Any service instance can drop out of the election by calling quitElection.
This will lose any leader status, if held, and stop monitoring of the lock node.
If the instance wants to participate in election again, then it needs to call joinElection().
This allows service instances to take themselves out of rotation for known impending unavailable states (e.g. long GC pause or software upgrade).

Parameters:

needFence - true if the underlying daemon may need to be fenced if a failover occurs due to dropping out of the election.

getActiveData

public byte[] getActiveData()
                     throws ActiveStandbyElector.ActiveNotFoundException,
                            org.apache.zookeeper.KeeperException,
                            InterruptedException,
                            IOException

get data set by the active leader

Returns:

data set by the active instance

Throws:

ActiveStandbyElector.ActiveNotFoundException - when there is no active leader

org.apache.zookeeper.KeeperException - other zookeeper operation errors

InterruptedException

IOException - when ZooKeeper connection could not be established

processResult

public void processResult(int rc,
                 String path,
                 Object ctx,
                 String name)

interface implementation of Zookeeper callback for create

Specified by:

processResult in interface org.apache.zookeeper.AsyncCallback.StringCallback

processResult

public void processResult(int rc,
                 String path,
                 Object ctx,
                 org.apache.zookeeper.data.Stat stat)

interface implementation of Zookeeper callback for monitor (exists)

Specified by:

processResult in interface org.apache.zookeeper.AsyncCallback.StatCallback

getNewZooKeeper

protected org.apache.zookeeper.ZooKeeper getNewZooKeeper()
                                                  throws IOException,
                                                         org.apache.zookeeper.KeeperException

Get a new zookeeper client instance. protected so that test class can inherit and pass in a mock object for zookeeper

Returns:

new zookeeper client instance

Throws:

IOException

org.apache.zookeeper.KeeperException - zookeeper connectionloss exception

sleepFor

protected void sleepFor(int sleepMs)

Sleep for the given number of milliseconds. This is non-static, and separated out, so that unit tests can override the behavior not to sleep.

toString

public String toString()

Overrides:

toString in class Object