Merge branch 'master' of ssh://gerrit.onlab.us:29418/onos-next

+package org.onlab.onos.cluster;
+
+import org.onlab.onos.event.AbstractEvent;
+import org.onlab.onos.net.DeviceId;
+
+/**
+ * Describes infrastructure device event.
+ */
+public class MastershipEvent extends AbstractEvent<MastershipEvent.Type, DeviceId> {
+
+    InstanceId master;
+
+    /**
+     * Type of mastership events.
+     */
+    public enum Type {
+        /**
+         * Signifies that the master for a device has changed.
+         */
+        MASTER_CHANGED
+    }
+
+    /**
+     * Creates an event of a given type and for the specified device, master,
+     * and the current time.
+     *
+     * @param type   device event type
+     * @param device event device subject
+     * @param master master ID subject
+     */
+    protected MastershipEvent(Type type, DeviceId device, InstanceId master) {
+        super(type, device);
+        this.master = master;
+    }
+
+    /**
+     * 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 master master ID subject
+     * @param time   occurrence time
+     */
+    protected MastershipEvent(Type type, DeviceId device, InstanceId master, long time) {
+        super(type, device, time);
+        this.master = master;
+    }
+
+    /**
+     * Returns the current master's ID as a subject.
+     *
+     * @return master ID subject
+     */
+    public InstanceId master() {
+        return master;
+    }
+}

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

 package org.onlab.onos.cluster;
 
+import java.util.Set;
+
+import org.onlab.onos.net.DeviceId;
+import org.onlab.onos.net.MastershipRole;
+
 /**
  * Service responsible for determining the controller instance mastership of
  * a device in a clustered environment. This is the central authority for
@@ -8,12 +13,42 @@ package org.onlab.onos.cluster;
  */
 public interface MastershipService {
 
-    // InstanceId getMasterFor(DeviceId deviceId)
-    // Set<DeviceId> getDevicesOf(InstanceId instanceId);
+    /**
+     * 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
+     */
+    InstanceId getMasterFor(DeviceId deviceId);
 
-    // MastershipRole requestRoleFor(DeviceId deviceId);
+    /**
+     * Returns the devices for which a controller is master.
+     *
+     * @param instanceId the ID of the controller
+     * @return a set of device IDs
+     */
+    Set<DeviceId> getDevicesOf(InstanceId instanceId);
 
-    // addListener/removeLister(MastershipListener listener);
-        // types of events would be MASTER_CHANGED (subject ==> deviceId; master ==> instanceId)
+    /**
+     * Returns the mastership status of this controller for a given device.
+     *
+     * @param deviceId the the identifier of the device
+     * @return the role of this controller instance
+     */
+    MastershipRole requestRoleFor(DeviceId deviceId);
+
+    /**
+     * Adds the specified mastership listener.
+     *
+     * @param listener the mastership listener
+     */
+    void addListener(MastershipListener listener);
+
+    /**
+     * Removes the specified device listener.
+     *
+     * @param listener the mastership listener
+     */
+    void removeListemer(MastershipListener listener);
 
 }