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:

    • 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()