Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 1 | /* |
Brian O'Connor | a09fe5b | 2017-08-03 21:12:30 -0700 | [diff] [blame] | 2 | * Copyright 2014-present Open Networking Foundation |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
Brian O'Connor | abafb50 | 2014-12-02 22:26:20 -0800 | [diff] [blame] | 16 | package org.onosproject.cluster; |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 17 | |
Ray Milkey | 3bceb01 | 2018-09-07 13:42:46 -0700 | [diff] [blame] | 18 | import com.google.common.collect.ImmutableList; |
Thomas Vachuska | 42e8cce | 2015-07-29 19:25:18 -0700 | [diff] [blame] | 19 | import org.onosproject.event.ListenerService; |
| 20 | |
Madan Jampani | fd45d5e | 2015-04-20 13:33:21 -0700 | [diff] [blame] | 21 | import java.util.List; |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 22 | import java.util.Set; |
Yuta HIGUCHI | c2bf3d8 | 2014-11-28 18:50:41 -0800 | [diff] [blame] | 23 | |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 24 | /** |
Madan Jampani | 1d3494e | 2014-11-20 11:24:22 -0800 | [diff] [blame] | 25 | * Service for leader election. |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 26 | * <p> |
Madan Jampani | 1ee9178 | 2014-11-20 20:24:24 -0800 | [diff] [blame] | 27 | * Leadership contests are organized around topics. A instance can join the |
| 28 | * leadership race for a topic or withdraw from a race it has previously joined. |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 29 | * <p> |
Madan Jampani | 1ee9178 | 2014-11-20 20:24:24 -0800 | [diff] [blame] | 30 | * Listeners can be added to receive notifications asynchronously for various |
| 31 | * leadership contests. |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 32 | * <p> |
| 33 | * When a node gets elected as a leader for a topic, all nodes receive notifications |
| 34 | * indicating a change in leadership. |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 35 | */ |
Thomas Vachuska | 42e8cce | 2015-07-29 19:25:18 -0700 | [diff] [blame] | 36 | public interface LeadershipService |
| 37 | extends ListenerService<LeadershipEvent, LeadershipEventListener> { |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 38 | |
| 39 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 40 | * Returns the {@link NodeId node identifier} that is the current leader for a topic. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 41 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 42 | * @param topic leadership topic |
| 43 | * @return node identifier of the current leader; {@code null} if there is no leader for the topic |
Madan Jampani | 1ee9178 | 2014-11-20 20:24:24 -0800 | [diff] [blame] | 44 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 45 | default NodeId getLeader(String topic) { |
| 46 | Leadership leadership = getLeadership(topic); |
| 47 | return leadership == null ? null : leadership.leaderNodeId(); |
| 48 | } |
Madan Jampani | 1ee9178 | 2014-11-20 20:24:24 -0800 | [diff] [blame] | 49 | |
| 50 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 51 | * Returns the current {@link Leadership leadership} for a topic. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 52 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 53 | * @param topic leadership topic |
| 54 | * @return leadership or {@code null} if no such topic exists |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 55 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 56 | Leadership getLeadership(String topic); |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 57 | |
| 58 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 59 | * Returns the set of topics owned by the specified {@link NodeId node}. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 60 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 61 | * @param nodeId node identifier. |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 62 | * @return set of topics for which this node is the current leader. |
| 63 | */ |
Ray Milkey | 3bceb01 | 2018-09-07 13:42:46 -0700 | [diff] [blame] | 64 | Set<String> ownedTopics(NodeId nodeId); |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 65 | |
| 66 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 67 | * Enters a leadership contest. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 68 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 69 | * @param topic leadership topic |
Madan Jampani | de003d9 | 2015-05-11 17:14:20 -0700 | [diff] [blame] | 70 | * @return {@code Leadership} future |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 71 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 72 | Leadership runForLeadership(String topic); |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 73 | |
| 74 | /** |
Madan Jampani | 1d3494e | 2014-11-20 11:24:22 -0800 | [diff] [blame] | 75 | * Withdraws from a leadership contest. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 76 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 77 | * @param topic leadership topic |
Madan Jampani | 1d3494e | 2014-11-20 11:24:22 -0800 | [diff] [blame] | 78 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 79 | void withdraw(String topic); |
Madan Jampani | 1af8e13 | 2015-04-30 16:41:18 -0700 | [diff] [blame] | 80 | |
| 81 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 82 | * Returns the candidate nodes for a given topic. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 83 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 84 | * @param topic leadership topic |
| 85 | * @return A lists of {@link NodeId nodeIds}, which may be empty. |
Ayaka Koshibe | c19b8b8 | 2015-04-08 15:18:24 -0700 | [diff] [blame] | 86 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 87 | default List<NodeId> getCandidates(String topic) { |
| 88 | Leadership leadership = getLeadership(topic); |
| 89 | return leadership == null ? ImmutableList.of() : ImmutableList.copyOf(leadership.candidates()); |
| 90 | } |
| 91 | } |