Class LeaderLatch

java.lang.Object
org.apache.curator.framework.recipes.leader.LeaderLatch
All Implemented Interfaces:
java.io.Closeable, java.lang.AutoCloseable

public class LeaderLatch
extends java.lang.Object
implements java.io.Closeable

Abstraction to select a "leader" amongst multiple contenders in a group of JMVs connected to a Zookeeper cluster. If a group of N thread/processes contend for leadership one will randomly be assigned leader until it releases leadership at which time another one from the group will randomly be chosen

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  LeaderLatch.CloseMode
    How to handle listeners when the latch is closed
    static class  LeaderLatch.State  
  • Constructor Summary

    Constructors 
    Constructor Description
    LeaderLatch​(CuratorFramework client, java.lang.String latchPath)  
    LeaderLatch​(CuratorFramework client, java.lang.String latchPath, java.lang.String id)  
    LeaderLatch​(CuratorFramework client, java.lang.String latchPath, java.lang.String id, LeaderLatch.CloseMode closeMode)  
  • Method Summary

    Modifier and Type Method Description
    void addListener​(LeaderLatchListener listener)
    Attaches a listener to this LeaderLatch
    void addListener​(LeaderLatchListener listener, java.util.concurrent.Executor executor)
    Attaches a listener to this LeaderLatch
    void await()
    Causes the current thread to wait until this instance acquires leadership unless the thread is interrupted or closed.
    boolean await​(long timeout, java.util.concurrent.TimeUnit unit)
    Causes the current thread to wait until this instance acquires leadership unless the thread is interrupted, the specified waiting time elapses or the instance is closed.
    protected boolean cancelStartTask()  
    void close()
    Remove this instance from the leadership election.
    void close​(LeaderLatch.CloseMode closeMode)
    Remove this instance from the leadership election.
    java.lang.String getId()
    Return this instance's participant Id
    Participant getLeader()
    Return the id for the current leader.
    java.lang.String getOurPath()
    Return this instance's lock node path.
    java.util.Collection<Participant> getParticipants()
    Returns the set of current participants in the leader selection
    LeaderLatch.State getState()
    Returns this instances current state, this is the only way to verify that the object has been closed before closing again.
    protected void handleStateChange​(ConnectionState newState)  
    boolean hasLeadership()
    Return true if leadership is currently held by this instance
    void removeListener​(LeaderLatchListener listener)
    Removes a given listener from this LeaderLatch
    void start()
    Add this instance to the leadership election and attempt to acquire leadership.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • LeaderLatch

      public LeaderLatch​(CuratorFramework client, java.lang.String latchPath)
      Parameters:
      client - the client
      latchPath - the path for this leadership group
    • LeaderLatch

      public LeaderLatch​(CuratorFramework client, java.lang.String latchPath, java.lang.String id)
      Parameters:
      client - the client
      latchPath - the path for this leadership group
      id - participant ID
    • LeaderLatch

      public LeaderLatch​(CuratorFramework client, java.lang.String latchPath, java.lang.String id, LeaderLatch.CloseMode closeMode)
      Parameters:
      client - the client
      latchPath - the path for this leadership group
      id - participant ID
      closeMode - behaviour of listener on explicit close.
  • Method Details

    • start

      public void start() throws java.lang.Exception
      Add this instance to the leadership election and attempt to acquire leadership.
      Throws:
      java.lang.Exception - errors
    • close

      public void close() throws java.io.IOException
      Remove this instance from the leadership election. If this instance is the leader, leadership is released. IMPORTANT: the only way to release leadership is by calling close(). All LeaderLatch instances must eventually be closed.
      Specified by:
      close in interface java.lang.AutoCloseable
      Specified by:
      close in interface java.io.Closeable
      Throws:
      java.io.IOException - errors
    • close

      public void close​(LeaderLatch.CloseMode closeMode) throws java.io.IOException
      Remove this instance from the leadership election. If this instance is the leader, leadership is released. IMPORTANT: the only way to release leadership is by calling close(). All LeaderLatch instances must eventually be closed.
      Parameters:
      closeMode - allows the default close mode to be overridden at the time the latch is closed.
      Throws:
      java.io.IOException - errors
    • cancelStartTask

      protected boolean cancelStartTask()
    • addListener

      public void addListener​(LeaderLatchListener listener)
      Attaches a listener to this LeaderLatch

      Attaching the same listener multiple times is a noop from the second time on.

      All methods for the listener are run using the provided Executor. It is common to pass in a single-threaded executor so that you can be certain that listener methods are called in sequence, but if you are fine with them being called out of order you are welcome to use multiple threads.

      Parameters:
      listener - the listener to attach
    • addListener

      public void addListener​(LeaderLatchListener listener, java.util.concurrent.Executor executor)
      Attaches a listener to this LeaderLatch

      Attaching the same listener multiple times is a noop from the second time on.

      All methods for the listener are run using the provided Executor. It is common to pass in a single-threaded executor so that you can be certain that listener methods are called in sequence, but if you are fine with them being called out of order you are welcome to use multiple threads.

      Parameters:
      listener - the listener to attach
      executor - An executor to run the methods for the listener on.
    • removeListener

      public void removeListener​(LeaderLatchListener listener)
      Removes a given listener from this LeaderLatch
      Parameters:
      listener - the listener to remove
    • await

      public void await() throws java.lang.InterruptedException, java.io.EOFException

      Causes the current thread to wait until this instance acquires leadership unless the thread is interrupted or closed.

      If this instance already is the leader then this method returns immediately.

      Otherwise the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happen:

      • This instance becomes the leader
      • Some other thread interrupts the current thread
      • The instance is closed

      If the current thread:

      • has its interrupted status set on entry to this method; or
      • is interrupted while waiting,

      then InterruptedException is thrown and the current thread's interrupted status is cleared.

      Throws:
      java.lang.InterruptedException - if the current thread is interrupted while waiting
      java.io.EOFException - if the instance is closed while waiting
    • await

      public boolean await​(long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException

      Causes the current thread to wait until this instance acquires leadership unless the thread is interrupted, the specified waiting time elapses or the instance is closed.

      If this instance already is the leader then this method returns immediately with the value true.

      Otherwise the current thread becomes disabled for thread scheduling purposes and lies dormant until one of four things happen:

      • This instance becomes the leader
      • Some other thread interrupts the current thread
      • The specified waiting time elapses.
      • The instance is closed

      If the current thread:

      • has its interrupted status set on entry to this method; or
      • is interrupted while waiting,

      then InterruptedException is thrown and the current thread's interrupted status is cleared.

      If the specified waiting time elapses or the instance is closed then the value false is returned. If the time is less than or equal to zero, the method will not wait at all.

      Parameters:
      timeout - the maximum time to wait
      unit - the time unit of the timeout argument
      Returns:
      true if the count reached zero and false if the waiting time elapsed before the count reached zero or the instances was closed
      Throws:
      java.lang.InterruptedException - if the current thread is interrupted while waiting
    • getId

      public java.lang.String getId()
      Return this instance's participant Id
      Returns:
      participant Id
    • getState

      public LeaderLatch.State getState()
      Returns this instances current state, this is the only way to verify that the object has been closed before closing again. If you try to close a latch multiple times, the close() method will throw an IllegalArgumentException which is often not caught and ignored (CloseableUtils.closeQuietly() only looks for IOException).
      Returns:
      the state of the current instance
    • getParticipants

      public java.util.Collection<Participant> getParticipants() throws java.lang.Exception

      Returns the set of current participants in the leader selection

      NOTE - this method polls the ZK server. Therefore it can possibly return a value that does not match hasLeadership() as hasLeadership uses a local field of the class.

      Returns:
      participants
      Throws:
      java.lang.Exception - ZK errors, interruptions, etc.
    • getLeader

      public Participant getLeader() throws java.lang.Exception

      Return the id for the current leader. If for some reason there is no current leader, a dummy participant is returned.

      NOTE - this method polls the ZK server. Therefore it can possibly return a value that does not match hasLeadership() as hasLeadership uses a local field of the class.

      Returns:
      leader
      Throws:
      java.lang.Exception - ZK errors, interruptions, etc.
    • hasLeadership

      public boolean hasLeadership()
      Return true if leadership is currently held by this instance
      Returns:
      true/false
    • getOurPath

      public java.lang.String getOurPath()
      Return this instance's lock node path. IMPORTANT: this instance owns the path returned. This method is meant for reference only. Also, it is possible for null to be returned. The path, if any, returned is not guaranteed to be valid at any point in the future as internal state changes might require the instance to delete and create a new path.
      Returns:
      lock node path or null
    • handleStateChange

      protected void handleStateChange​(ConnectionState newState)