com.netflix.curator.framework.recipes.leader
Class LeaderLatch

java.lang.Object
  com.netflix.curator.framework.recipes.leader.LeaderLatch

All Implemented Interfaces:

java.io.Closeable

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

Constructor Summary

LeaderLatch(com.netflix.curator.framework.CuratorFramework client, java.lang.String latchPath)

LeaderLatch(com.netflix.curator.framework.CuratorFramework client, java.lang.String latchPath, java.lang.String id)

Method Summary

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.
void	close() 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.util.Collection<Participant>	getParticipants() Returns the set of current participants in the leader selection
boolean	hasLeadership() Return true if leadership is currently held by this instance
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(com.netflix.curator.framework.CuratorFramework client,
                   java.lang.String latchPath)

Parameters:

client - the client

latchPath - the path for this leadership group

LeaderLatch

public LeaderLatch(com.netflix.curator.framework.CuratorFramework client,
                   java.lang.String latchPath,
                   java.lang.String id)

Parameters:

client - the client

latchPath - the path for this leadership group

id - participant ID

Method Detail

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.io.Closeable

Throws:

java.io.IOException - errors

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

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