added more mastership-related interfaces

Change-Id: I3c5da1e2a4346d6e557232c5f896b32a7268ec39

+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);
+
+}

@@ -4,7 +4,7 @@ import org.onlab.onos.event.AbstractEvent;
 import org.onlab.onos.net.DeviceId;
 
 /**
- * Describes infrastructure device event.
+ * Describes a device mastership event.
  */
 public class MastershipEvent extends AbstractEvent<MastershipEvent.Type, DeviceId> {
 

@@ -5,6 +5,6 @@ import org.onlab.onos.event.EventListener;
 /**
  * Entity capable of receiving device mastership-related events.
  */
-public interface MastershipListener extends EventListener<MastershipEvent>{
+public interface MastershipListener extends EventListener<MastershipEvent> {
 
 }

@@ -49,6 +49,6 @@ public interface MastershipService {
      *
      * @param listener the mastership listener
      */
-    void removeListemer(MastershipListener listener);
+    void removeListener(MastershipListener listener);
 
 }

+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);
+}

@@ -13,7 +13,9 @@ public interface DeviceAdminService {
      *
      * @param deviceId device identifier
      * @param role     requested role
+     * @deprecated Will be removed in favor of MastershipAdminService.setRole()
      */
+    @Deprecated
     void setRole(DeviceId deviceId, MastershipRole role);
 
     /**