org.onosproject.cluster

Interface LeadershipService

public interface LeadershipService

Service for leader election. Leadership contests are organized around topics. A instance can join the leadership race for a topic or withdraw from a race it has previously joined. Listeners can be added to receive notifications asynchronously for various leadership contests.

Method Summary

Modifier and Type	Method and Description
void	addListener(LeadershipEventListener listener) Registers a event listener to be notified of leadership events.
Map<String,List<NodeId>>	getCandidates() Returns the candidates for all known topics.
List<NodeId>	getCandidates(String path) Returns the candidates for a given topic.
NodeId	getLeader(String path) Returns the current leader for the topic.
Map<String,Leadership>	getLeaderBoard() Returns the current leader board.
Leadership	getLeadership(String path) Returns the current leadership info for the topic.
boolean	makeTopCandidate(String path, NodeId nodeId) Moves the specified nodeId to the top of the candidates list for the topic.
Set<String>	ownedTopics(NodeId nodeId) Returns the set of topics owned by the specified node.
void	removeListener(LeadershipEventListener listener) Unregisters a event listener for leadership events.
CompletableFuture<Leadership>	runForLeadership(String path) Joins the leadership contest.
boolean	stepdown(String path) If the local nodeId is the leader for specified topic, this method causes it to step down temporarily from leadership.
CompletableFuture<Void>	withdraw(String path) Withdraws from a leadership contest.

Method Detail

getLeader

NodeId getLeader(String path)

Returns the current leader for the topic.

Parameters:

path - topic

Returns:

nodeId of the leader, null if so such topic exists.

getLeadership

Leadership getLeadership(String path)

Returns the current leadership info for the topic.

Parameters:

path - topic

Returns:

leadership info or null if so such topic exists.

ownedTopics

Set<String> ownedTopics(NodeId nodeId)

Returns the set of topics owned by the specified node.

Parameters:

nodeId - node Id.

Returns:

set of topics for which this node is the current leader.

runForLeadership

CompletableFuture<Leadership> runForLeadership(String path)

Joins the leadership contest.

Parameters:

path - topic for which this controller node wishes to be a leader

Returns:

Leadership future

withdraw

CompletableFuture<Void> withdraw(String path)

Withdraws from a leadership contest.

Parameters:

path - topic for which this controller node no longer wishes to be a leader

Returns:

future that is successfully completed when withdraw is done

stepdown

boolean stepdown(String path)

If the local nodeId is the leader for specified topic, this method causes it to step down temporarily from leadership.

The node will continue to be in contention for leadership and can potentially become the leader again if and when it becomes the highest priority candidate

If the local nodeId is not the leader, this method will make no changes and simply return false.

Parameters:

path - topic for which this controller node should give up leadership

Returns:

true if this node stepped down from leadership, false otherwise

makeTopCandidate

boolean makeTopCandidate(String path,
                         NodeId nodeId)

Moves the specified nodeId to the top of the candidates list for the topic.

If the node is not a candidate for this topic, this method will be a noop.

Parameters:

path - leadership topic

nodeId - nodeId to make the top candidate

Returns:

true if nodeId is now the top candidate, false otherwise

getLeaderBoard

Map<String,Leadership> getLeaderBoard()

Returns the current leader board.

Returns:

mapping from topic to leadership info.

getCandidates

Map<String,List<NodeId>> getCandidates()

Returns the candidates for all known topics.

Returns:

A mapping from topics to corresponding list of candidates.

getCandidates

List<NodeId> getCandidates(String path)

Returns the candidates for a given topic.

Parameters:

path - topic

Returns:

A lists of NodeIds, which may be empty.

addListener

void addListener(LeadershipEventListener listener)

Registers a event listener to be notified of leadership events.

Parameters:

listener - listener that will asynchronously notified of leadership events.

removeListener

void removeListener(LeadershipEventListener listener)

Unregisters a event listener for leadership events.

Parameters:

listener - listener to be removed.