Package 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

@Private
@Evolving
public class ActiveStandbyElector
extends java.lang.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	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.AllChildrenNumberCallback, org.apache.zookeeper.AsyncCallback.Children2Callback, org.apache.zookeeper.AsyncCallback.ChildrenCallback, org.apache.zookeeper.AsyncCallback.Create2Callback, org.apache.zookeeper.AsyncCallback.DataCallback, org.apache.zookeeper.AsyncCallback.EphemeralsCallback, org.apache.zookeeper.AsyncCallback.MultiCallback, org.apache.zookeeper.AsyncCallback.StatCallback, org.apache.zookeeper.AsyncCallback.StringCallback, org.apache.zookeeper.AsyncCallback.VoidCallback

Field Summary

Fields

Modifier and Type	Field	Description
protected static java.lang.String	BREADCRUMB_FILENAME
protected static java.lang.String	LOCK_FILENAME	Name of the lock znode used by the library.
static org.slf4j.Logger	LOG

Constructor Summary

Constructors

Constructor	Description
ActiveStandbyElector(java.lang.String zookeeperHostPorts, int zookeeperSessionTimeout, java.lang.String parentZnodeName, java.util.List<org.apache.zookeeper.data.ACL> acl, java.util.List<ZKUtil.ZKAuthInfo> authInfo, ActiveStandbyElector.ActiveStandbyElectorCallback app, int maxRetryNum, boolean failFast, SecurityUtil.TruststoreKeystore truststoreKeystore)	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.
ActiveStandbyElector(java.lang.String zookeeperHostPorts, int zookeeperSessionTimeout, java.lang.String parentZnodeName, java.util.List<org.apache.zookeeper.data.ACL> acl, java.util.List<ZKUtil.ZKAuthInfo> authInfo, ActiveStandbyElector.ActiveStandbyElectorCallback app, int maxRetryNum, SecurityUtil.TruststoreKeystore truststoreKeystore)	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

Modifier and Type	Method	Description
void	clearParentZNode()	Clear all of the state held within the parent ZNode.
protected org.apache.zookeeper.ZooKeeper	connectToZooKeeper()	Get a new zookeeper client instance.
protected org.apache.zookeeper.ZooKeeper	createZooKeeper()	Get a new zookeeper client instance.
void	ensureParentZNode()	Utility function to ensure that the configured base znode exists.
byte[]	getActiveData()	get data set by the active leader
java.lang.String	getHAZookeeperConnectionState()
boolean	getWantToBeInElection()
protected org.apache.zookeeper.ZooKeeper	initiateZookeeper(org.apache.zookeeper.client.ZKClientConfig zkClientConfig)
void	joinElection(byte[] data)	To participate in election, the app will call joinElection.
boolean	parentZNodeExists()
void	processResult(int rc, java.lang.String path, java.lang.Object ctx, java.lang.String name)	interface implementation of Zookeeper callback for create
void	processResult(int rc, java.lang.String path, java.lang.Object ctx, org.apache.zookeeper.data.Stat stat)	interface implementation of Zookeeper callback for monitor (exists)
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.
void	terminateConnection()
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

LOCK_FILENAME

@VisibleForTesting
protected static final java.lang.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

@VisibleForTesting
protected static final java.lang.String BREADCRUMB_FILENAME

See Also:

Constant Field Values

LOG

public static final org.slf4j.Logger LOG

Constructor Detail

ActiveStandbyElector

public ActiveStandbyElector(java.lang.String zookeeperHostPorts,
                            int zookeeperSessionTimeout,
                            java.lang.String parentZnodeName,
                            java.util.List<org.apache.zookeeper.data.ACL> acl,
                            java.util.List<ZKUtil.ZKAuthInfo> authInfo,
                            ActiveStandbyElector.ActiveStandbyElectorCallback app,
                            int maxRetryNum,
                            SecurityUtil.TruststoreKeystore truststoreKeystore)
                     throws java.io.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

maxRetryNum - maxRetryNum.

truststoreKeystore - truststore keystore, that we will use for ZK if SSL/TLS is enabled

Throws:

java.io.IOException - raised on errors performing I/O.

HadoopIllegalArgumentException - if valid data is not supplied.

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

ActiveStandbyElector

public ActiveStandbyElector(java.lang.String zookeeperHostPorts,
                            int zookeeperSessionTimeout,
                            java.lang.String parentZnodeName,
                            java.util.List<org.apache.zookeeper.data.ACL> acl,
                            java.util.List<ZKUtil.ZKAuthInfo> authInfo,
                            ActiveStandbyElector.ActiveStandbyElectorCallback app,
                            int maxRetryNum,
                            boolean failFast,
                            SecurityUtil.TruststoreKeystore truststoreKeystore)
                     throws java.io.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

failFast - whether need to add the retry when establishing ZK connection.

maxRetryNum - max Retry Num

truststoreKeystore - truststore keystore, that we will use for ZK if SSL/TLS is enabled

Throws:

java.io.IOException - raised on errors performing I/O.

HadoopIllegalArgumentException - if valid data is not supplied.

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

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 java.io.IOException,
                                 java.lang.InterruptedException

Returns:

true if the configured parent znode exists

Throws:

java.io.IOException - raised on errors performing I/O.

java.lang.InterruptedException - interrupted exception.

ensureParentZNode

public void ensureParentZNode()
                       throws java.io.IOException,
                              java.lang.InterruptedException,
                              org.apache.zookeeper.KeeperException

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

Throws:

java.io.IOException - raised on errors performing I/O.

java.lang.InterruptedException - interrupted exception.

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

clearParentZNode

public void clearParentZNode()
                      throws java.io.IOException,
                             java.lang.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:

java.io.IOException - raised on errors performing I/O.

java.lang.InterruptedException - interrupted exception.

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,
                            java.lang.InterruptedException,
                            java.io.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

java.lang.InterruptedException - interrupted exception.

java.io.IOException - when ZooKeeper connection could not be established

processResult

public void processResult(int rc,
                          java.lang.String path,
                          java.lang.Object ctx,
                          java.lang.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,
                          java.lang.String path,
                          java.lang.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

getWantToBeInElection

@VisibleForTesting
public boolean getWantToBeInElection()

connectToZooKeeper

protected org.apache.zookeeper.ZooKeeper connectToZooKeeper()
                                                     throws java.io.IOException,
                                                            org.apache.zookeeper.KeeperException

Get a new zookeeper client instance. protected so that test class can inherit and mock out the zookeeper instance

Returns:

new zookeeper client instance

Throws:

java.io.IOException - raised on errors performing I/O.

org.apache.zookeeper.KeeperException - zookeeper connectionloss exception

createZooKeeper

protected org.apache.zookeeper.ZooKeeper createZooKeeper()
                                                  throws java.io.IOException

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:

java.io.IOException - raised on errors performing I/O.

initiateZookeeper

protected org.apache.zookeeper.ZooKeeper initiateZookeeper(org.apache.zookeeper.client.ZKClientConfig zkClientConfig)
                                                    throws java.io.IOException

Throws:

java.io.IOException

sleepFor

@VisibleForTesting
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.

Parameters:

sleepMs - sleep ms.

terminateConnection

@Private
public void terminateConnection()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getHAZookeeperConnectionState

public java.lang.String getHAZookeeperConnectionState()