org.apache.curator.framework.recipes.leader
Class LeaderLatch

java.lang.Object
  org.apache.curator.framework.recipes.leader.LeaderLatch

All Implemented Interfaces:

Closeable

public class LeaderLatch
extends Object
implements 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

static class	LeaderLatch.CloseMode How to handle listeners when the latch is closed
static class	LeaderLatch.State

Constructor Summary

LeaderLatch(org.apache.curator.framework.CuratorFramework client, String latchPath)

LeaderLatch(org.apache.curator.framework.CuratorFramework client, String latchPath, String id)

LeaderLatch(org.apache.curator.framework.CuratorFramework client, String latchPath, String id, LeaderLatch.CloseMode closeMode)

Method Summary

void	addListener(LeaderLatchListener listener) Attaches a listener to this LeaderLatch Attaching the same listener multiple times is a noop from the second time on.
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.
void	await() Causes the current thread to wait until this instance acquires leadership unless the thread is interrupted or closed.
boolean	await(long timeout, 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.
String	getId() Return this instance's participant Id
Participant	getLeader() Return the id for the current leader.
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.
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 Detail

LeaderLatch

public LeaderLatch(org.apache.curator.framework.CuratorFramework client,
                   String latchPath)

Parameters:

client - the client

latchPath - the path for this leadership group

LeaderLatch

public LeaderLatch(org.apache.curator.framework.CuratorFramework client,
                   String latchPath,
                   String id)

Parameters:

client - the client

latchPath - the path for this leadership group

id - participant ID

LeaderLatch

public LeaderLatch(org.apache.curator.framework.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 Detail

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