added more mastership-related interfaces

Change-Id: I3c5da1e2a4346d6e557232c5f896b32a7268ec39
diff --git a/core/api/src/main/java/org/onlab/onos/cluster/MastershipAdminService.java b/core/api/src/main/java/org/onlab/onos/cluster/MastershipAdminService.java
new file mode 100644
index 0000000..6c58020
--- /dev/null
+++ b/core/api/src/main/java/org/onlab/onos/cluster/MastershipAdminService.java
@@ -0,0 +1,20 @@
+package org.onlab.onos.cluster;
+
+import org.onlab.onos.net.DeviceId;
+import org.onlab.onos.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
+     */
+    void setRole(InstanceId instance, DeviceId deviceId, MastershipRole role);
+
+}
diff --git a/core/api/src/main/java/org/onlab/onos/cluster/MastershipEvent.java b/core/api/src/main/java/org/onlab/onos/cluster/MastershipEvent.java
index e0d2756..a835449 100644
--- a/core/api/src/main/java/org/onlab/onos/cluster/MastershipEvent.java
+++ b/core/api/src/main/java/org/onlab/onos/cluster/MastershipEvent.java
@@ -4,7 +4,7 @@
 import org.onlab.onos.net.DeviceId;
 
 /**
- * Describes infrastructure device event.
+ * Describes a device mastership event.
  */
 public class MastershipEvent extends AbstractEvent<MastershipEvent.Type, DeviceId> {
 
diff --git a/core/api/src/main/java/org/onlab/onos/cluster/MastershipListener.java b/core/api/src/main/java/org/onlab/onos/cluster/MastershipListener.java
index 22daed3..8a49c31 100644
--- a/core/api/src/main/java/org/onlab/onos/cluster/MastershipListener.java
+++ b/core/api/src/main/java/org/onlab/onos/cluster/MastershipListener.java
@@ -5,6 +5,6 @@
 /**
  * Entity capable of receiving device mastership-related events.
  */
-public interface MastershipListener extends EventListener<MastershipEvent>{
+public interface MastershipListener extends EventListener<MastershipEvent> {
 
 }
diff --git a/core/api/src/main/java/org/onlab/onos/cluster/MastershipService.java b/core/api/src/main/java/org/onlab/onos/cluster/MastershipService.java
index bdbd1f6..3592aeb 100644
--- a/core/api/src/main/java/org/onlab/onos/cluster/MastershipService.java
+++ b/core/api/src/main/java/org/onlab/onos/cluster/MastershipService.java
@@ -49,6 +49,6 @@
      *
      * @param listener the mastership listener
      */
-    void removeListemer(MastershipListener listener);
+    void removeListener(MastershipListener listener);
 
 }
diff --git a/core/api/src/main/java/org/onlab/onos/cluster/MastershipStore.java b/core/api/src/main/java/org/onlab/onos/cluster/MastershipStore.java
new file mode 100644
index 0000000..dad4a75
--- /dev/null
+++ b/core/api/src/main/java/org/onlab/onos/cluster/MastershipStore.java
@@ -0,0 +1,61 @@
+package org.onlab.onos.cluster;
+
+import java.util.Set;
+
+import org.onlab.onos.net.DeviceId;
+import org.onlab.onos.net.MastershipRole;
+
+/**
+ * Manages inventory of mastership roles for devices, across controller instances.
+ */
+public interface MastershipStore {
+
+    // three things to map: InstanceId, DeviceId, MastershipRole
+
+    /**
+     * Sets a device's role for a specified controller instance.
+     *
+     * @param instance controller instance identifier
+     * @param deviceId device identifier
+     * @param role     new role
+     * @return a mastership event
+     */
+    MastershipEvent setRole(
+            InstanceId instance, DeviceId deviceId, MastershipRole role);
+
+    /**
+     * Adds or updates the mastership information for a device.
+     *
+     * @param instance controller instance identifier
+     * @param deviceId device identifier
+     * @param role     new role
+     * @return a mastership event
+     */
+    MastershipEvent addOrUpdateDevice(
+            InstanceId instance, DeviceId deviceId, MastershipRole role);
+
+    /**
+     * Returns the master for a device.
+     *
+     * @param deviceId the device identifier
+     * @return the instance identifier of the master
+     */
+    InstanceId getMaster(DeviceId deviceId);
+
+    /**
+     * Returns the devices that a controller instance is master of.
+     *
+     * @param  instanceId the instance identifier
+     * @return a set of device identifiers
+     */
+    Set<DeviceId> getDevices(InstanceId instanceId);
+
+    /**
+     * Returns the role of a device for a specific controller instance.
+     *
+     * @param instanceId the instance identifier
+     * @param deviceId the device identifiers
+     * @return the role
+     */
+    MastershipRole getRole(InstanceId instanceId, DeviceId deviceId);
+}
diff --git a/core/api/src/main/java/org/onlab/onos/net/device/DeviceAdminService.java b/core/api/src/main/java/org/onlab/onos/net/device/DeviceAdminService.java
index 8aec28a..23856ab 100644
--- a/core/api/src/main/java/org/onlab/onos/net/device/DeviceAdminService.java
+++ b/core/api/src/main/java/org/onlab/onos/net/device/DeviceAdminService.java
@@ -13,7 +13,9 @@
      *
      * @param deviceId device identifier
      * @param role     requested role
+     * @deprecated Will be removed in favor of MastershipAdminService.setRole()
      */
+    @Deprecated
     void setRole(DeviceId deviceId, MastershipRole role);
 
     /**