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
Modifier and Type | Class and Description |
---|---|
static class |
LeaderLatch.CloseMode
How to handle listeners when the latch is closed
|
static class |
LeaderLatch.State |
Constructor and Description |
---|
LeaderLatch(CuratorFramework client,
String latchPath) |
LeaderLatch(CuratorFramework client,
String latchPath,
String id) |
LeaderLatch(CuratorFramework client,
String latchPath,
String id,
LeaderLatch.CloseMode closeMode) |
Modifier and Type | Method and Description |
---|---|
void |
addListener(LeaderLatchListener listener)
Attaches a listener to this LeaderLatch
|
void |
addListener(LeaderLatchListener listener,
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,
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
|
String |
getLastPathIsLeader()
Return last of this instance's lock node path that was leader ever.
|
Participant |
getLeader()
Return the id for the current leader.
|
String |
getOurPath()
Return this instance's lock node path.
|
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.
|
public LeaderLatch(CuratorFramework client, String latchPath)
client
- the clientlatchPath
- the path for this leadership grouppublic LeaderLatch(CuratorFramework client, String latchPath, String id)
client
- the clientlatchPath
- the path for this leadership groupid
- participant IDpublic LeaderLatch(CuratorFramework client, String latchPath, String id, LeaderLatch.CloseMode closeMode)
client
- the clientlatchPath
- the path for this leadership groupid
- participant IDcloseMode
- behaviour of listener on explicit close.public void start() throws Exception
Exception
- errorspublic void close() throws IOException
close
in interface Closeable
close
in interface AutoCloseable
IOException
- errorspublic void close(LeaderLatch.CloseMode closeMode) throws IOException
closeMode
- allows the default close mode to be overridden at the time the latch is closed.IOException
- errorsprotected boolean cancelStartTask()
public void addListener(LeaderLatchListener listener)
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.
listener
- the listener to attachpublic void addListener(LeaderLatchListener listener, Executor executor)
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.
listener
- the listener to attachexecutor
- An executor to run the methods for the listener on.public void removeListener(LeaderLatchListener listener)
listener
- the listener to removepublic 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:
If the current thread:
then InterruptedException
is thrown and the current thread's
interrupted status is cleared.
InterruptedException
- if the current thread is interrupted
while waitingEOFException
- if the instance is closed
while waitingpublic 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:
If the current thread:
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.
timeout
- the maximum time to waitunit
- the time unit of the timeout
argumenttrue
if the count reached zero and false
if the waiting time elapsed before the count reached zero or the instances was closedInterruptedException
- if the current thread is interrupted
while waitingpublic String getId()
public LeaderLatch.State getState()
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.
Exception
- ZK errors, interruptions, etc.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.
Exception
- ZK errors, interruptions, etc.public boolean hasLeadership()
public String getOurPath()
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.null
getLastPathIsLeader()
public String getLastPathIsLeader()
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.null
protected void handleStateChange(ConnectionState newState)
Copyright © 2011–2023 The Apache Software Foundation. All rights reserved.