ActiveStandbyElector (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.ha, class: ActiveStandbyElector

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 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 final String`
  `BREADCRUMB_FILENAME`
  `protected static final String`
  `LOCK_FILENAME`
  Name of the lock znode used by the library.
  `static final org.slf4j.Logger`
  `LOG`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ActiveStandbyElector(String zookeeperHostPorts, int zookeeperSessionTimeout, String parentZnodeName, List<org.apache.zookeeper.data.ACL> acl, 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(String zookeeperHostPorts, int zookeeperSessionTimeout, String parentZnodeName, List<org.apache.zookeeper.data.ACL> acl, 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 so that test class can inherit and mock out the zookeeper instance
  `protected org.apache.zookeeper.ZooKeeper`
  `createZooKeeper()`
  Get a new zookeeper client instance. protected so that test class can inherit and pass in a mock object for zookeeper
  `void`
  `ensureParentZNode()`
  Utility function to ensure that the configured base znode exists.
  `byte[]`
  `getActiveData()`
  get data set by the active leader
  `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, String path, Object ctx, String name)`
  interface implementation of Zookeeper callback for create
  `void`
  `processResult(int rc, String path, 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()`
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### LOCK_FILENAME

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

    @VisibleForTesting protected static final String BREADCRUMB_FILENAME
    See Also:
      - Constant Field Values

  - ### LOG

    public static final org.slf4j.Logger LOG

- ## Constructor Details

  - ### ActiveStandbyElector

    public ActiveStandbyElector(String zookeeperHostPorts, int zookeeperSessionTimeout, String parentZnodeName, List<org.apache.zookeeper.data.ACL> acl, List<ZKUtil.ZKAuthInfo> authInfo, ActiveStandbyElector.ActiveStandbyElectorCallback app, int maxRetryNum, SecurityUtil.TruststoreKeystore truststoreKeystore) 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
      `maxRetryNum` - maxRetryNum.
      `truststoreKeystore` - truststore keystore, that we will use for ZK if SSL/TLS is enabled
    Throws:
      `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(String zookeeperHostPorts, int zookeeperSessionTimeout, String parentZnodeName, List<org.apache.zookeeper.data.ACL> acl, List<ZKUtil.ZKAuthInfo> authInfo, ActiveStandbyElector.ActiveStandbyElectorCallback app, int maxRetryNum, boolean failFast, SecurityUtil.TruststoreKeystore truststoreKeystore) 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
      `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:
      `IOException` - raised on errors performing I/O.
      `HadoopIllegalArgumentException` - if valid data is not supplied.
      `org.apache.zookeeper.KeeperException` - other zookeeper operation errors.

- ## Method Details

  - ### 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` - raised on errors performing I/O.
      `InterruptedException` - interrupted exception.

  - ### ensureParentZNode

    public void ensureParentZNode() throws IOException, 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:
      `IOException` - raised on errors performing I/O.
      `InterruptedException` - interrupted exception.
      `org.apache.zookeeper.KeeperException` - other zookeeper operation errors.

  - ### 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` - raised on errors performing I/O.
      `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, 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` - interrupted exception.
      `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`

  - ### getWantToBeInElection

    @VisibleForTesting public boolean getWantToBeInElection()

  - ### connectToZooKeeper

    protected org.apache.zookeeper.ZooKeeper connectToZooKeeper() throws 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:
      `IOException` - raised on errors performing I/O.
      `org.apache.zookeeper.KeeperException` - zookeeper connectionloss exception

  - ### createZooKeeper

    protected org.apache.zookeeper.ZooKeeper createZooKeeper() throws 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:
      `IOException` - raised on errors performing I/O.

  - ### initiateZookeeper

    protected org.apache.zookeeper.ZooKeeper initiateZookeeper(org.apache.zookeeper.client.ZKClientConfig zkClientConfig) throws IOException
    Throws:
      `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 String toString()
    Overrides:
      `toString` in class `Object`

  - ### getHAZookeeperConnectionState

    public String getHAZookeeperConnectionState()