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

Class LeaderSelector

java.lang.Object

org.apache.curator.framework.recipes.leader.LeaderSelector

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class LeaderSelector
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 contends for leadership, one will be assigned leader until it releases leadership at which time another one from the group will be chosen.

Note that this class uses an underlying InterProcessMutex and as a result leader election is "fair" - each user will become leader in the order originally requested (from ZK's point of view).

Constructor Summary

Constructors

Constructor	Description
LeaderSelector(org.apache.curator.framework.CuratorFramework client, java.lang.String leaderPath, java.util.concurrent.ExecutorService executorService, LeaderSelectorListener listener)
LeaderSelector(org.apache.curator.framework.CuratorFramework client, java.lang.String leaderPath, java.util.concurrent.ThreadFactory threadFactory, java.util.concurrent.Executor executor, LeaderSelectorListener listener)	Deprecated. This constructor was poorly thought out.
LeaderSelector(org.apache.curator.framework.CuratorFramework client, java.lang.String leaderPath, LeaderSelectorListener listener)
LeaderSelector(org.apache.curator.framework.CuratorFramework client, java.lang.String leaderPath, org.apache.curator.utils.CloseableExecutorService executorService, LeaderSelectorListener listener)

Method Summary

Modifier and Type	Method	Description
void	autoRequeue()	By default, when LeaderSelectorListener.takeLeadership(CuratorFramework) returns, this instance is not requeued.
void	close()	Shutdown this selector and remove yourself from the leadership group
java.lang.String	getId()	Return the ID that was set via setId(String)
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	interruptLeadership()	Attempt to cancel and interrupt the current leadership if this instance has leadership
boolean	requeue()	Re-queue an attempt for leadership.
void	setId(java.lang.String id)	Sets the ID to store for this leader.
void	start()	Attempt leadership.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LeaderSelector

public LeaderSelector(org.apache.curator.framework.CuratorFramework client,
                      java.lang.String leaderPath,
                      LeaderSelectorListener listener)

Parameters:

client - the client

leaderPath - the path for this leadership group

listener - listener

LeaderSelector

@Deprecated
public LeaderSelector(org.apache.curator.framework.CuratorFramework client,
                      java.lang.String leaderPath,
                      java.util.concurrent.ThreadFactory threadFactory,
                      java.util.concurrent.Executor executor,
                      LeaderSelectorListener listener)

Deprecated.

This constructor was poorly thought out. Custom executor is useless. Use this version instead: LeaderSelector(CuratorFramework, String, ExecutorService, LeaderSelectorListener)

Parameters:

client - the client

leaderPath - the path for this leadership group

threadFactory - factory to use for making internal threads

executor - the executor to run in

listener - listener

LeaderSelector

public LeaderSelector(org.apache.curator.framework.CuratorFramework client,
                      java.lang.String leaderPath,
                      java.util.concurrent.ExecutorService executorService,
                      LeaderSelectorListener listener)

Parameters:

client - the client

leaderPath - the path for this leadership group

executorService - thread pool to use

listener - listener

LeaderSelector

public LeaderSelector(org.apache.curator.framework.CuratorFramework client,
                      java.lang.String leaderPath,
                      org.apache.curator.utils.CloseableExecutorService executorService,
                      LeaderSelectorListener listener)

Parameters:

client - the client

leaderPath - the path for this leadership group

executorService - thread pool to use

listener - listener

Method Detail

autoRequeue

public void autoRequeue()

By default, when LeaderSelectorListener.takeLeadership(CuratorFramework) returns, this instance is not requeued. Calling this method puts the leader selector into a mode where it will always requeue itself.

setId

public void setId(java.lang.String id)

Sets the ID to store for this leader. Will be the value returned when getParticipants() is called. IMPORTANT: must be called prior to start() to have effect.

Parameters:

id - ID

getId

public java.lang.String getId()

Return the ID that was set via setId(String)

Returns:

id

start

public void start()

Attempt leadership. This attempt is done in the background - i.e. this method returns immediately.

IMPORTANT: previous versions allowed this method to be called multiple times. This is no longer supported. Use requeue() for this purpose.

requeue

public boolean requeue()

Re-queue an attempt for leadership. If this instance is already queued, nothing happens and false is returned. If the instance was not queued, it is re-qeued and true is returned

Returns:

true if re-queue is successful

close

public void close()

Shutdown this selector and remove yourself from the leadership group

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

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

interruptLeadership

public void interruptLeadership()

Attempt to cancel and interrupt the current leadership if this instance has leadership