Package org.apache.curator.framework.recipes.leader

Class LeaderLatch

java.lang.Object
org.apache.curator.framework.recipes.leader.LeaderLatch
All Implemented Interfaces:
Closeable, AutoCloseable
public class LeaderLatch extends Object implements Closeable

Abstraction to select a "leader" amongst multiple contenders in a group of JVMs 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

  • Constructor Details

    • LeaderLatch

      public LeaderLatch(CuratorFramework client, String latchPath)
      Parameters:
      client - the client
      latchPath - the path for this leadership group

    • LeaderLatch

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

    • LeaderLatch

      public LeaderLatch(CuratorFramework client, String latchPath, 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 Exception
      Add this instance to the leadership election and attempt to acquire leadership.
      Throws:
      Exception - errors

    • close

      public void close() throws 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 AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - errors

    • close

      public void close(LeaderLatch.CloseMode closeMode) throws 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:
      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, 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 InterruptedException, 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:
      InterruptedException - if the current thread is interrupted while waiting
      EOFException - if the instance is closed while waiting

    • await

      public boolean await(long timeout, TimeUnit unit) throws 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:
      InterruptedException - if the current thread is interrupted while waiting

    • getId

      public 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 Collection<Participant> getParticipants() throws 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:
      Exception - ZK errors, interruptions, etc.

    • getLeader

      public Participant getLeader() throws 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:
      Exception - ZK errors, interruptions, etc.

    • hasLeadership

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

    • getOurPath

      public 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.

      However, the existence of ourPath doesn't mean that this instance holds leadership.

      Returns:
      lock node path or null
      See Also:

    • getLastPathIsLeader

      public String getLastPathIsLeader()
      Return last of this instance's lock node path that was leader ever. IMPORTANT: this instance owns the path returned. This method is meant for reference only. Also, it is possible for null to be returned (for this instance never becomes a leader). 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 the path.

      The existence of lastPathIsLeader means that this instance holds leadership.

      Returns:
      last lock node path that was leader ever or null

    • handleStateChange

      protected void handleStateChange(ConnectionState newState)