ONOS checkin based on commit tag e796610b1f721d02f9b0e213cf6f7790c10ecd60

Change-Id: Ife8810491034fe7becdba75dda20de4267bd15cd

9 files changed, 540 insertions, 0 deletions

diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipAdminService.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipAdminService.java
new file mode 100644
index 00000000..a8835fc7
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipAdminService.java
@@ -0,0 +1,45 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.mastership;
+
+import java.util.concurrent.CompletableFuture;
+
+import org.onosproject.cluster.NodeId;
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.MastershipRole;
+
+/**
+ * Service for administering the inventory of device masterships.
+ */
+public interface MastershipAdminService {
+
+    /**
+     * Applies the current mastership role for the specified device.
+     *
+     * @param instance controller instance identifier
+     * @param deviceId device identifier
+     * @param role     requested role
+     * @return future that is completed when the role is set
+     */
+    CompletableFuture<Void> setRole(NodeId instance, DeviceId deviceId, MastershipRole role);
+
+    /**
+     * Balances the mastership to be shared as evenly as possibly by all
+     * online instances.
+     */
+    void balanceRoles();
+
+}
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipEvent.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipEvent.java
new file mode 100644
index 00000000..35c32e79
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipEvent.java
@@ -0,0 +1,95 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.mastership;
+
+import org.joda.time.LocalDateTime;
+import org.onosproject.cluster.RoleInfo;
+import org.onosproject.event.AbstractEvent;
+import org.onosproject.net.DeviceId;
+
+import com.google.common.base.MoreObjects;
+
+/**
+ * Describes a device mastership event.
+ */
+public class MastershipEvent extends AbstractEvent<MastershipEvent.Type, DeviceId> {
+
+    //Contains master and standby information.
+    RoleInfo roleInfo;
+
+    /**
+     * Type of mastership events.
+     */
+    public enum Type {
+        /**
+         * Signifies that the master for a device has changed.
+         */
+        MASTER_CHANGED,
+
+        /**
+         * Signifies that the list of backup nodes has changed. If
+         * the change in the backups list is accompanied by a change in
+         * master, the event is subsumed by MASTER_CHANGED.
+         */
+        BACKUPS_CHANGED
+    }
+
+    /**
+     * Creates an event of a given type and for the specified device,
+     * role information, and the current time.
+     *
+     * @param type   mastership event type
+     * @param device event device subject
+     * @param info   mastership role information
+     */
+    public MastershipEvent(Type type, DeviceId device, RoleInfo info) {
+        super(type, device);
+        this.roleInfo = info;
+    }
+
+    /**
+     * Creates an event of a given type and for the specified device, master,
+     * and time.
+     *
+     * @param type   mastership event type
+     * @param device event device subject
+     * @param info   role information
+     * @param time   occurrence time
+     */
+    public MastershipEvent(Type type, DeviceId device, RoleInfo info, long time) {
+        super(type, device, time);
+        this.roleInfo = info;
+    }
+
+    /**
+     * Returns the current role state for the subject.
+     *
+     * @return RoleInfo associated with Device ID subject
+     */
+    public RoleInfo roleInfo() {
+        return roleInfo;
+    }
+
+    @Override
+    public String toString() {
+        return MoreObjects.toStringHelper(getClass())
+                .add("time", new LocalDateTime(time()))
+                .add("type", type())
+                .add("subject", subject())
+                .add("roleInfo", roleInfo)
+                .toString();
+    }
+}
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipListener.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipListener.java
new file mode 100644
index 00000000..9c5690e2
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipListener.java
@@ -0,0 +1,24 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.mastership;
+
+import org.onosproject.event.EventListener;
+
+/**
+ * Entity capable of receiving device mastership-related events.
+ */
+public interface MastershipListener extends EventListener<MastershipEvent> {
+}
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipService.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipService.java
new file mode 100644
index 00000000..a709f5cf
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipService.java
@@ -0,0 +1,101 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.mastership;
+
+import static org.onosproject.net.MastershipRole.MASTER;
+
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+
+import org.onosproject.cluster.NodeId;
+import org.onosproject.cluster.RoleInfo;
+import org.onosproject.event.ListenerService;
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.MastershipRole;
+
+/**
+ * Service responsible for determining the controller instance mastership of
+ * a device in a clustered environment. This is the central authority for
+ * determining mastership, but is not responsible for actually applying it
+ * to the devices; this falls on the device service.
+ */
+public interface MastershipService
+    extends ListenerService<MastershipEvent, MastershipListener> {
+
+    /**
+     * Returns the role of the local node for the specified device, without
+     * triggering master selection.
+     *
+     * @param deviceId the the identifier of the device
+     * @return role of the current node
+     */
+    MastershipRole getLocalRole(DeviceId deviceId);
+
+    /**
+     * Returns true if the local controller is the Master for the specified deviceId.
+     *
+     * @param deviceId the the identifier of the device
+     * @return true if local node is master; false otherwise
+     */
+    default boolean isLocalMaster(DeviceId deviceId) {
+        return getLocalRole(deviceId) == MASTER;
+    }
+
+    /**
+     * Returns the mastership status of the local controller for a given
+     * device forcing master selection if necessary.
+     *
+     * @param deviceId the the identifier of the device
+     * @return the role of this controller instance
+     */
+    CompletableFuture<MastershipRole> requestRoleFor(DeviceId deviceId);
+
+    /**
+     * Abandons mastership of the specified device on the local node thus
+     * forcing selection of a new master. If the local node is not a master
+     * for this device, no master selection will occur.
+     *
+     * @param deviceId the identifier of the device
+     * @return future that is completed when relinquish is complete
+     */
+    CompletableFuture<Void> relinquishMastership(DeviceId deviceId);
+
+    /**
+     * Returns the current master for a given device.
+     *
+     * @param deviceId the identifier of the device
+     * @return the ID of the master controller for the device
+     */
+    NodeId getMasterFor(DeviceId deviceId);
+
+    /**
+     * Returns controllers connected to a given device, in order of
+     * preference. The first entry in the list is the current master.
+     *
+     * @param deviceId the identifier of the device
+     * @return a list of controller IDs
+     */
+    RoleInfo getNodesFor(DeviceId deviceId);
+
+    /**
+     * Returns the devices for which a controller is master.
+     *
+     * @param nodeId the ID of the controller
+     * @return a set of device IDs
+     */
+    Set<DeviceId> getDevicesOf(NodeId nodeId);
+
+}
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipStore.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipStore.java
new file mode 100644
index 00000000..81c2d8b6
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipStore.java
@@ -0,0 +1,125 @@
+/*
+ * Copyright 2014-2015 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.mastership;
+
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+
+import org.onosproject.cluster.NodeId;
+import org.onosproject.cluster.RoleInfo;
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.MastershipRole;
+import org.onosproject.store.Store;
+
+/**
+ * Manages inventory of mastership roles for devices, across controller
+ * instances; not intended for direct use.
+ */
+public interface MastershipStore extends Store<MastershipEvent, MastershipStoreDelegate> {
+
+    // three things to map: NodeId, DeviceId, MastershipRole
+
+    /**
+     * Requests role of the local node for the specified device.
+     *
+     * @param deviceId device identifier
+     * @return established or newly negotiated mastership role
+     */
+    CompletableFuture<MastershipRole> requestRole(DeviceId deviceId);
+
+    /**
+     * Returns the role of a device for a specific controller instance.
+     *
+     * @param nodeId   the instance identifier
+     * @param deviceId the device identifiers
+     * @return the role
+     */
+    MastershipRole getRole(NodeId nodeId, DeviceId deviceId);
+
+    /**
+     * Returns the master for a device.
+     *
+     * @param deviceId the device identifier
+     * @return the instance identifier of the master
+     */
+    NodeId getMaster(DeviceId deviceId);
+
+    /**
+     * Returns the master and backup nodes for a device.
+     *
+     * @param deviceId the device identifier
+     * @return a RoleInfo containing controller IDs
+     */
+    RoleInfo getNodes(DeviceId deviceId);
+
+    /**
+     * Returns the devices that a controller instance is master of.
+     *
+     * @param nodeId the instance identifier
+     * @return a set of device identifiers
+     */
+    Set<DeviceId> getDevices(NodeId nodeId);
+
+
+    /**
+     * Sets a device's role for a specified controller instance.
+     *
+     * @param nodeId   controller instance identifier
+     * @param deviceId device identifier
+     * @return a mastership event
+     */
+    CompletableFuture<MastershipEvent> setMaster(NodeId nodeId, DeviceId deviceId);
+
+    /**
+     * Returns the current master and number of past mastership hand-offs
+     * (terms) for a device.
+     *
+     * @param deviceId the device identifier
+     * @return the current master's ID and the term value for device, or null
+     */
+    MastershipTerm getTermFor(DeviceId deviceId);
+
+    /**
+     * Sets a controller instance's mastership role to STANDBY for a device.
+     * If the role is MASTER, another controller instance will be selected
+     * as a candidate master.
+     *
+     * @param nodeId   the controller instance identifier
+     * @param deviceId device to revoke mastership role for
+     * @return a mastership event
+     */
+    CompletableFuture<MastershipEvent> setStandby(NodeId nodeId, DeviceId deviceId);
+
+    /**
+     * Allows a controller instance to give up its current role for a device.
+     * If the role is MASTER, another controller instance will be selected
+     * as a candidate master.
+     *
+     * @param nodeId   the controller instance identifier
+     * @param deviceId device to revoke mastership role for
+     * @return a mastership event
+     */
+    CompletableFuture<MastershipEvent> relinquishRole(NodeId nodeId, DeviceId deviceId);
+
+    /**
+     * Removes all the roles for the specified controller instance.
+     * If the role was MASTER, another controller instance will be selected
+     * as a candidate master.
+     *
+     * @param nodeId the controller instance identifier
+     */
+    void relinquishAllRole(NodeId nodeId);
+}
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipStoreDelegate.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipStoreDelegate.java
new file mode 100644
index 00000000..c71f4ed0
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipStoreDelegate.java
@@ -0,0 +1,24 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.mastership;
+
+import org.onosproject.store.StoreDelegate;
+
+/**
+ * Mastership store delegate abstraction.
+ */
+public interface MastershipStoreDelegate extends StoreDelegate<MastershipEvent> {
+}
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipTerm.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipTerm.java
new file mode 100644
index 00000000..049d1d2b
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipTerm.java
@@ -0,0 +1,71 @@
+/*
+ * Copyright 2014-2015 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.mastership;
+
+import java.util.Objects;
+
+import org.onosproject.cluster.NodeId;
+
+import com.google.common.base.MoreObjects;
+
+public final class MastershipTerm {
+
+    private final NodeId master;
+    private final long termNumber;
+
+    private MastershipTerm(NodeId master, long term) {
+        this.master = master;
+        this.termNumber = term;
+    }
+
+    public static MastershipTerm of(NodeId master, long term) {
+        return new MastershipTerm(master, term);
+    }
+
+    public NodeId master() {
+        return master;
+    }
+
+    public long termNumber() {
+        return termNumber;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(master, termNumber);
+    }
+
+    @Override
+    public boolean equals(Object other) {
+        if (this == other) {
+            return true;
+        }
+        if (other instanceof MastershipTerm) {
+            MastershipTerm that = (MastershipTerm) other;
+            return Objects.equals(this.master, that.master) &&
+                    Objects.equals(this.termNumber, that.termNumber);
+        }
+        return false;
+    }
+
+    @Override
+    public String toString() {
+        return MoreObjects.toStringHelper(getClass())
+                .add("master", this.master)
+                .add("termNumber", this.termNumber)
+                .toString();
+    }
+}
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipTermService.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipTermService.java
new file mode 100644
index 00000000..1725ee03
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/MastershipTermService.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.onosproject.mastership;
+
+import org.onosproject.net.DeviceId;
+
+// TODO give me a better name
+/**
+ * Service to obtain mastership term information.
+ */
+public interface MastershipTermService {
+
+    // TBD: manage/increment per device mastership change
+    //      or increment on any change
+    /**
+     * Returns the term number of mastership change occurred for given device.
+     *
+     * @param deviceId the identifier of the device
+     * @return current master's term.
+     */
+    MastershipTerm getMastershipTerm(DeviceId deviceId);
+}
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/package-info.java b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/package-info.java
new file mode 100644
index 00000000..0040680a
--- /dev/null
+++ b/framework/src/onos/core/api/src/main/java/org/onosproject/mastership/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Set of abstractions for dealing with controller mastership related topics.
+ */
+package org.onosproject.mastership;