Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 1 | /* |
Brian O'Connor | 5ab426f | 2016-04-09 01:19:45 -0700 | [diff] [blame] | 2 | * Copyright 2014-present Open Networking Laboratory |
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 | |
Thomas Vachuska | 42e8cce | 2015-07-29 19:25:18 -0700 | [diff] [blame] | 18 | import org.onosproject.event.ListenerService; |
| 19 | |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 20 | import com.google.common.base.Objects; |
| 21 | import com.google.common.collect.ImmutableList; |
| 22 | import com.google.common.collect.ImmutableMap; |
| 23 | import com.google.common.collect.Maps; |
| 24 | |
Madan Jampani | fd45d5e | 2015-04-20 13:33:21 -0700 | [diff] [blame] | 25 | import java.util.List; |
Yuta HIGUCHI | c2bf3d8 | 2014-11-28 18:50:41 -0800 | [diff] [blame] | 26 | import java.util.Map; |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 27 | import java.util.Set; |
Yuta HIGUCHI | c2bf3d8 | 2014-11-28 18:50:41 -0800 | [diff] [blame] | 28 | |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 29 | /** |
Madan Jampani | 1d3494e | 2014-11-20 11:24:22 -0800 | [diff] [blame] | 30 | * Service for leader election. |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 31 | * <p> |
Madan Jampani | 1ee9178 | 2014-11-20 20:24:24 -0800 | [diff] [blame] | 32 | * Leadership contests are organized around topics. A instance can join the |
| 33 | * 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] | 34 | * <p> |
Madan Jampani | 1ee9178 | 2014-11-20 20:24:24 -0800 | [diff] [blame] | 35 | * Listeners can be added to receive notifications asynchronously for various |
| 36 | * leadership contests. |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 37 | * <p> |
| 38 | * When a node gets elected as a leader for a topic, all nodes receive notifications |
| 39 | * indicating a change in leadership. |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 40 | */ |
Thomas Vachuska | 42e8cce | 2015-07-29 19:25:18 -0700 | [diff] [blame] | 41 | public interface LeadershipService |
| 42 | extends ListenerService<LeadershipEvent, LeadershipEventListener> { |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 43 | |
| 44 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 45 | * 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] | 46 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 47 | * @param topic leadership topic |
| 48 | * @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] | 49 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 50 | default NodeId getLeader(String topic) { |
| 51 | Leadership leadership = getLeadership(topic); |
| 52 | return leadership == null ? null : leadership.leaderNodeId(); |
| 53 | } |
Madan Jampani | 1ee9178 | 2014-11-20 20:24:24 -0800 | [diff] [blame] | 54 | |
| 55 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 56 | * Returns the current {@link Leadership leadership} for a topic. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 57 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 58 | * @param topic leadership topic |
| 59 | * @return leadership or {@code null} if no such topic exists |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 60 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 61 | Leadership getLeadership(String topic); |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 62 | |
| 63 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 64 | * Returns the set of topics owned by the specified {@link NodeId node}. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 65 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 66 | * @param nodeId node identifier. |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 67 | * @return set of topics for which this node is the current leader. |
| 68 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 69 | default Set<String> ownedTopics(NodeId nodeId) { |
| 70 | return Maps.filterValues(getLeaderBoard(), v -> Objects.equal(nodeId, v.leaderNodeId())).keySet(); |
| 71 | } |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 72 | |
| 73 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 74 | * Enters a leadership contest. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 75 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 76 | * @param topic leadership topic |
Madan Jampani | de003d9 | 2015-05-11 17:14:20 -0700 | [diff] [blame] | 77 | * @return {@code Leadership} future |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 78 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 79 | Leadership runForLeadership(String topic); |
Pavlin Radoslavov | a6b754c | 2014-11-18 13:55:37 -0800 | [diff] [blame] | 80 | |
| 81 | /** |
Madan Jampani | 1d3494e | 2014-11-20 11:24:22 -0800 | [diff] [blame] | 82 | * Withdraws from a leadership contest. |
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 |
Madan Jampani | 1d3494e | 2014-11-20 11:24:22 -0800 | [diff] [blame] | 85 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 86 | void withdraw(String topic); |
Madan Jampani | 1af8e13 | 2015-04-30 16:41:18 -0700 | [diff] [blame] | 87 | |
| 88 | /** |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 89 | * Returns the current leader board. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 90 | * |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 91 | * @return mapping from topic to leadership info. |
Madan Jampani | a4a5994 | 2016-05-02 11:25:34 -0700 | [diff] [blame] | 92 | * @deprecated 1.6.0 Goldeneye release. Replace usages with {@link #getLeadership(String)} |
Madan Jampani | 5961051 | 2015-02-25 15:25:43 -0800 | [diff] [blame] | 93 | */ |
Madan Jampani | a4a5994 | 2016-05-02 11:25:34 -0700 | [diff] [blame] | 94 | @Deprecated |
Yuta HIGUCHI | c2bf3d8 | 2014-11-28 18:50:41 -0800 | [diff] [blame] | 95 | Map<String, Leadership> getLeaderBoard(); |
| 96 | |
Madan Jampani | 1d3494e | 2014-11-20 11:24:22 -0800 | [diff] [blame] | 97 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 98 | * Returns the candidate nodes for each topic. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 99 | * |
Madan Jampani | fd45d5e | 2015-04-20 13:33:21 -0700 | [diff] [blame] | 100 | * @return A mapping from topics to corresponding list of candidates. |
Madan Jampani | a4a5994 | 2016-05-02 11:25:34 -0700 | [diff] [blame] | 101 | * @deprecated 1.6.0 Goldeneye release. Replace usages with {@link #getLeadership(String)} |
Ayaka Koshibe | c19b8b8 | 2015-04-08 15:18:24 -0700 | [diff] [blame] | 102 | */ |
Madan Jampani | a4a5994 | 2016-05-02 11:25:34 -0700 | [diff] [blame] | 103 | @Deprecated |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 104 | default Map<String, List<NodeId>> getCandidates() { |
| 105 | return ImmutableMap.copyOf(Maps.transformValues(getLeaderBoard(), v -> ImmutableList.copyOf(v.candidates()))); |
| 106 | } |
Ayaka Koshibe | c19b8b8 | 2015-04-08 15:18:24 -0700 | [diff] [blame] | 107 | |
| 108 | /** |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 109 | * Returns the candidate nodes for a given topic. |
Sho SHIMIZU | 25d843c | 2015-04-10 16:52:33 -0700 | [diff] [blame] | 110 | * |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 111 | * @param topic leadership topic |
| 112 | * @return A lists of {@link NodeId nodeIds}, which may be empty. |
Ayaka Koshibe | c19b8b8 | 2015-04-08 15:18:24 -0700 | [diff] [blame] | 113 | */ |
Madan Jampani | 620f70d | 2016-01-30 22:22:47 -0800 | [diff] [blame] | 114 | default List<NodeId> getCandidates(String topic) { |
| 115 | Leadership leadership = getLeadership(topic); |
| 116 | return leadership == null ? ImmutableList.of() : ImmutableList.copyOf(leadership.candidates()); |
| 117 | } |
| 118 | } |