Sketching SB & NB API.

Modified onos-of-api pom to subsume openflowj loxi-generated stuff.

@@ -7,4 +7,5 @@
 .javacp*
 .javacp*
 target
 target
 *.iml
 *.iml
+dependency-reduced-pom.xml
 .idea
 .idea

@@ -6,7 +6,6 @@
     <feature name="onos-thirdparty-base" version="1.0.0"
     <feature name="onos-thirdparty-base" version="1.0.0"
              description="ONOS 3rd party dependencies">
              description="ONOS 3rd party dependencies">
         <bundle>mvn:com.google.guava/guava/17.0</bundle>
         <bundle>mvn:com.google.guava/guava/17.0</bundle>
-        <bundle>mvn:io.netty/netty/3.9.2.Final</bundle>
     </feature>
     </feature>
 
 
     <feature name="onos-thirdparty-web" version="1.0.0"
     <feature name="onos-thirdparty-web" version="1.0.0"
@@ -55,7 +54,6 @@
             description="ONOS OpenFlow API, Controller &amp; Providers">
             description="ONOS OpenFlow API, Controller &amp; Providers">
         <feature>onos-core</feature>
         <feature>onos-core</feature>
         <bundle>mvn:io.netty/netty/3.9.2.Final</bundle>
         <bundle>mvn:io.netty/netty/3.9.2.Final</bundle>
-        <bundle>mvn:com.google.guava/guava/15.0</bundle>
 
 
         <bundle>mvn:org.onlab.onos/openflow-api/1.0.0-SNAPSHOT</bundle>
         <bundle>mvn:org.onlab.onos/openflow-api/1.0.0-SNAPSHOT</bundle>
         <bundle>mvn:org.onlab.onos/openflow-ctl/1.0.0-SNAPSHOT</bundle>
         <bundle>mvn:org.onlab.onos/openflow-ctl/1.0.0-SNAPSHOT</bundle>

+package org.onlab.onos.event;
+
+/**
+ * Base abstraction of an event.
+ */
+public class AbstractEvent<T extends Enum, S extends Object> implements Event<T, S> {
+
+    private final long time;
+    private final T type;
+    private S subject;
+
+    /**
+     * Creates an event of a given type and for the specified subject and the
+     * current time.
+     *
+     * @param type    event type
+     * @param subject event subject
+     */
+    protected AbstractEvent(T type, S subject) {
+        this(type, subject, System.currentTimeMillis());
+    }
+
+    /**
+     * Creates an event of a given type and for the specified subject and time.
+     *
+     * @param type    event type
+     * @param subject event subject
+     * @param time    occurrence time
+     */
+    protected AbstractEvent(T type, S subject, long time) {
+        this.type = type;
+        this.subject = subject;
+        this.time = time;
+    }
+
+    @Override
+    public long time() {
+        return time;
+    }
+
+    @Override
+    public T type() {
+        return type;
+    }
+
+    @Override
+    public S subject() {
+        return subject;
+    }
+
+}

+package org.onlab.onos.event;
+
+/**
+ * Abstraction of an event.
+ */
+public interface Event<T extends Enum, S extends Object> {
+
+    /**
+     * Returns the timestamp of when the event occurred, given in milliseconds
+     * since the start of epoch.
+     *
+     * @return timestamp in milliseconds
+     */
+    long time();
+
+    /**
+     * Returns the type of the event.
+     *
+     * @return event type
+     */
+    T type();
+
+    /**
+     * Returns the subject of the event.
+     *
+     * @return subject to which this event pertains
+     */
+    S subject();
+
+}

+package org.onlab.onos.event;
+
+/**
+ * Entity capable of receiving events.
+ */
+public interface EventListener<E extends Event> {
+
+    /**
+     * Reacts to the specified event.
+     *
+     * @param event event to be processed
+     */
+    void event(E event);
+
+}

+package org.onlab.onos.net;
+
+/**
+ * Representation of an network infrastructure device.
+ */
+public class Device {
+
+    // type, e.g. switch, router, firewall, ips, controller
+
+    // id (uri within)
+
+    // ports
+
+}

+package org.onlab.onos.net;
+
+/**
+ * Abstraction of an end-station host on the network, essentially a NIC.
+ */
+public class Host {
+
+    // MAC, IP(s), optional VLAN ID
+
+    // Location (current, recent locations?
+
+}

+package org.onlab.onos.net;
+
+/**
+ * Representation of a relationship role of a controller instance to a device
+ * or a region of network environment.
+ */
+public enum MastershipRole {
+
+    /**
+     * Represents a relationship where the controller instance is the master
+     * to a device or a region of network environment.
+     */
+    MASTER,
+
+    /**
+     * Represents a relationship where the controller instance is the standby,
+     * i.e. potential master to a device or a region of network environment.
+     */
+    STANDBY,
+
+    /**
+     * Represents that the controller instance is not eligible to be the master
+     * to a device or a region of network environment.
+     */
+    NONE
+
+}

+package org.onlab.onos.net.device;
+
+import org.onlab.onos.event.AbstractEvent;
+import org.onlab.onos.net.Device;
+
+/**
+ * Describes infrastructure device event.
+ */
+public class DeviceEvent extends AbstractEvent<DeviceEvent.Type, Device> {
+
+    /**
+     * Type of device events.
+     */
+    public enum Type {
+        /** Signifies that a new device has been detected. */
+        DEVICE_ADDED,
+
+        /** Signifies that a device has been removed. */
+        DEVICE_REMOVED,
+
+        /** Signifies that a device has been administratively suspended. */
+        DEVICE_SUSPENDED,
+
+        /** Signifies that a device has come online or has gone offline. */
+        DEVICE_AVAILABILITY_CHANGED,
+
+        /**
+         * Signifies that the current controller instance relationship has
+         * changed with respect to a device.
+         */
+        DEVICE_MASTERSHIP_CHANGED
+    }
+
+    /**
+     * Creates an event of a given type and for the specified subject and the
+     * current time.
+     *
+     * @param type    event type
+     * @param subject event subject
+     */
+    public DeviceEvent(Type type, Device subject) {
+        super(type, subject);
+    }
+
+    /**
+     * Creates an event of a given type and for the specified subject and time.
+     *
+     * @param type    event type
+     * @param subject event subject
+     * @param time    occurrence time
+     */
+    public DeviceEvent(Type type, Device subject, long time) {
+        super(type, subject, time);
+    }
+
+}

+package org.onlab.onos.net.device;
+
+/**
+ * Entity capable of receiving device related events.
+ */
+public interface DeviceListener {
+}

 package org.onlab.onos.net.device;
 package org.onlab.onos.net.device;
 
 
-import org.onlab.onos.net.Provider;
+import org.onlab.onos.net.Device;
+import org.onlab.onos.net.MastershipRole;
+import org.onlab.onos.provider.Provider;
 
 
 /**
 /**
  * Abstraction of a device information provider.
  * Abstraction of a device information provider.
  */
  */
 public interface DeviceProvider extends Provider {
 public interface DeviceProvider extends Provider {
+
+    // TODO: consider how dirty the triggerProbe gets; if it costs too much, let's drop it
+
+    /**
+     * Triggers an asynchronous probe of the specified device, intended to
+     * determine whether the host is present or not. An indirect result of this
+     * should be invocation of
+     * {@link org.onlab.onos.net.device.DeviceProviderService#deviceConnected(DeviceDescription)} )} or
+     * {@link org.onlab.onos.net.device.DeviceProviderService#deviceDisconnected(DeviceDescription)}
+     * at some later point in time.
+     *
+     * @param device device to be probed
+     */
+    void triggerProbe(Device device);
+
+    /**
+     * Notifies the provider of a mastership role change for the specified
+     * device as decided by the core.
+     *
+     * @param device  affected device
+     * @param newRole newly determined mastership role
+     */
+    void roleChanged(Device device, MastershipRole newRole);
+
 }
 }

 package org.onlab.onos.net.device;
 package org.onlab.onos.net.device;
 
 
-import org.onlab.onos.net.ProviderBroker;
+import org.onlab.onos.provider.ProviderBroker;
 
 
 /**
 /**
  * Abstraction of a device provider brokerage.
  * Abstraction of a device provider brokerage.

 package org.onlab.onos.net.device;
 package org.onlab.onos.net.device;
 
 
-import org.onlab.onos.net.ProviderService;
+import org.onlab.onos.net.MastershipRole;
+import org.onlab.onos.provider.ProviderService;
 
 
 import java.util.List;
 import java.util.List;
 
 
@@ -16,8 +17,9 @@ public interface DeviceProviderService extends ProviderService {
      * Signals the core that a device has connected or has been detected somehow.
      * Signals the core that a device has connected or has been detected somehow.
      *
      *
      * @param deviceDescription information about network device
      * @param deviceDescription information about network device
+     * @return mastership role chosen by the provider service
      */
      */
-    void deviceConnected(DeviceDescription deviceDescription);
+    MastershipRole deviceConnected(DeviceDescription deviceDescription);
 
 
     /**
     /**
      * Signals the core that a device has disconnected or is no longer reachable.
      * Signals the core that a device has disconnected or is no longer reachable.

+package org.onlab.onos.net.device;
+
+import org.onlab.onos.net.Device;
+import org.onlab.onos.net.DeviceId;
+import org.onlab.onos.net.MastershipRole;
+
+/**
+ * Service for interacting with the inventory of infrastructure devices.
+ */
+public interface DeviceService {
+
+    /**
+     * Returns the current mastership role for the specified device.
+     *
+     * @param deviceId device identifier
+     * @return designated mastership role
+     */
+    MastershipRole getRole(DeviceId deviceId);
+
+    /**
+     * Returns an iterable collection of the currently known infrastructure
+     * devices.
+     *
+     * @return collection of devices
+     */
+    Iterable<Device> getDevices();
+
+    /**
+     * Returns the device with the specified identifier.
+     *
+     * @param deviceId device identifier
+     * @return device or null if one with the given identifier is not known
+     */
+    Device getDevice(DeviceId deviceId);
+
+
+//    List<Port> getPorts(DeviceId deviceId);
+
+    /**
+     * Adds the specified device listener.
+     *
+     * @param listener device listener
+     */
+    void addListener(DeviceListener listener);
+
+    /**
+     * Removes the specified device listener.
+     *
+     * @param listener device listener
+     */
+    void removeListener(DeviceListener listener);
+}

 package org.onlab.onos.net.flow;
 package org.onlab.onos.net.flow;
 
 
-import org.onlab.onos.net.Provider;
+import org.onlab.onos.provider.Provider;
 
 
 /**
 /**
  * Abstraction of a flow rule provider.
  * Abstraction of a flow rule provider.
  */
  */
 public interface FlowRuleProvider extends Provider {
 public interface FlowRuleProvider extends Provider {
+
+    // TODO: pushFlowRule
+
 }
 }

 package org.onlab.onos.net.flow;
 package org.onlab.onos.net.flow;
 
 
-import org.onlab.onos.net.ProviderBroker;
+import org.onlab.onos.provider.ProviderBroker;
 
 
 /**
 /**
  * Abstraction for a flow rule provider brokerage.
  * Abstraction for a flow rule provider brokerage.

 package org.onlab.onos.net.flow;
 package org.onlab.onos.net.flow;
 
 
-import org.onlab.onos.net.ProviderService;
+import org.onlab.onos.provider.ProviderService;
 
 
 /**
 /**
  * Service through which flowrule providers can inject flowrule information into
  * Service through which flowrule providers can inject flowrule information into

 package org.onlab.onos.net.host;
 package org.onlab.onos.net.host;
 
 
-import org.onlab.onos.net.Provider;
+import org.onlab.onos.net.Host;
+import org.onlab.onos.provider.Provider;
 
 
 /**
 /**
  * Provider of information about hosts and their location on the network.
  * Provider of information about hosts and their location on the network.
  */
  */
 public interface HostProvider extends Provider {
 public interface HostProvider extends Provider {
+
+    // TODO: consider how dirty the triggerProbe gets; if it costs too much, let's drop it
+
+    /**
+     * Triggers an asynchronous probe of the specified host, intended to
+     * determine whether the host is present or not. An indirect result of this
+     * should be invocation of {@link org.onlab.onos.net.host.HostProviderService#hostDetected(HostDescription)} or
+     * {@link org.onlab.onos.net.host.HostProviderService#hostNotDetected(HostDescription)}
+     * at some later point in time.
+     *
+     * @param host host to probe
+     */
+    void triggerProbe(Host host);
+
 }
 }

 package org.onlab.onos.net.host;
 package org.onlab.onos.net.host;
 
 
-import org.onlab.onos.net.ProviderBroker;
+import org.onlab.onos.provider.ProviderBroker;
 
 
 /**
 /**
  * Abstraction of a host provider brokerage.
  * Abstraction of a host provider brokerage.

 package org.onlab.onos.net.host;
 package org.onlab.onos.net.host;
 
 
-import org.onlab.onos.net.ProviderService;
+import org.onlab.onos.provider.ProviderService;
 
 
 /**
 /**
  * Means of conveying host information to the core.
  * Means of conveying host information to the core.
  */
  */
 public interface HostProviderService extends ProviderService {
 public interface HostProviderService extends ProviderService {
 
 
+    /**
+     * Notifies the core when a host has been detected on a network along with
+     * information that identifies the hoot location.
+     *
+     * @param hostDescription description of host and its location
+     */
     void hostDetected(HostDescription hostDescription);
     void hostDetected(HostDescription hostDescription);
 
 
+    /**
+     * Notifies the core when a host is no longer detected on a network.
+     *
+     * @param hostDescription description of host
+     */
+    void hostNotDetected(HostDescription hostDescription);
+
 }
 }

 package org.onlab.onos.net.link;
 package org.onlab.onos.net.link;
 
 
-import org.onlab.onos.net.Provider;
+import org.onlab.onos.provider.Provider;
 
 
 /**
 /**
  * Abstraction of an entity providing information about infrastructure links
  * Abstraction of an entity providing information about infrastructure links

 package org.onlab.onos.net.link;
 package org.onlab.onos.net.link;
 
 
-import org.onlab.onos.net.ProviderBroker;
+import org.onlab.onos.provider.ProviderBroker;
 
 
 /**
 /**
  * Abstraction of an infrastructure link provider brokerage.
  * Abstraction of an infrastructure link provider brokerage.

 package org.onlab.onos.net.link;
 package org.onlab.onos.net.link;
 
 
-import org.onlab.onos.net.ProviderService;
+import org.onlab.onos.provider.ProviderService;
 
 
 /**
 /**
  * Means for injecting link information into the core.
  * Means for injecting link information into the core.

 package org.onlab.onos.net.topology;
 package org.onlab.onos.net.topology;
 
 
-import org.onlab.onos.net.Provider;
+import org.onlab.onos.provider.Provider;
 
 
 /**
 /**
  * Means for injecting topology information into the core.
  * Means for injecting topology information into the core.

 package org.onlab.onos.net.topology;
 package org.onlab.onos.net.topology;
 
 
-import org.onlab.onos.net.ProviderBroker;
+import org.onlab.onos.provider.ProviderBroker;
 
 
 /**
 /**
  * Abstraction of a network topology provider brokerage.
  * Abstraction of a network topology provider brokerage.

 package org.onlab.onos.net.topology;
 package org.onlab.onos.net.topology;
 
 
-import org.onlab.onos.net.ProviderService;
+import org.onlab.onos.provider.ProviderService;
 
 
 /**
 /**
  * Means for injecting topology information into the core.
  * Means for injecting topology information into the core.

-package org.onlab.onos.net;
+package org.onlab.onos.provider;
 
 
 /**
 /**
  * Abstraction of a provider of information about network environment.
  * Abstraction of a provider of information about network environment.

-package org.onlab.onos.net;
+package org.onlab.onos.provider;
 
 
 /**
 /**
  * Broker used for registering/unregistering information providers with the core.
  * Broker used for registering/unregistering information providers with the core.

-package org.onlab.onos.net;
+package org.onlab.onos.provider;
 
 
 /**
 /**
  * Notion of provider identity.
  * Notion of provider identity.

-package org.onlab.onos.net;
+package org.onlab.onos.provider;
 
 
 /**
 /**
  * Abstraction of a service through which providers can inject information
  * Abstraction of a service through which providers can inject information

@@ -16,4 +16,42 @@
 
 
     <description>ONOS OpenFlow controller subsystem API</description>
     <description>ONOS OpenFlow controller subsystem API</description>
 
 
+    <dependencies>
+        <dependency>
+            <groupId>org.projectfloodlight</groupId>
+            <artifactId>openflowj</artifactId>
+            <version>0.3.8-SNAPSHOT</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>2.3</version>
+                <configuration>
+                    <artifactSet>
+                        <excludes>
+                            <exclude>io.netty:netty</exclude>
+                            <exclude>com.google.guava:guava</exclude>
+                            <exclude>org.slf4j:slfj-api</exclude>
+                            <exclude>ch.qos.logback:logback-core</exclude>
+                            <exclude>ch.qos.logback:logback-classic</exclude>
+                            <exclude>com.google.code.findbugs:annotations</exclude>
+                        </excludes>
+                    </artifactSet>
+                </configuration>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
 </project>
 </project>

@@ -193,9 +193,7 @@
                     </configuration>
                     </configuration>
                 </plugin>
                 </plugin>
 
 
-
                 <!-- TODO: add jacoco plugin for unit test coverage; for explicit invocation only -->
                 <!-- TODO: add jacoco plugin for unit test coverage; for explicit invocation only -->
-
                 <!-- TODO: add findbugs plugin for static code analysis; for explicit invocation only -->
                 <!-- TODO: add findbugs plugin for static code analysis; for explicit invocation only -->
                 <!-- TODO: add sonarqube plugin for code analysis; for explicit invocation only -->
                 <!-- TODO: add sonarqube plugin for code analysis; for explicit invocation only -->
 
 
@@ -205,6 +203,11 @@
         <plugins>
         <plugins>
             <plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+            </plugin>
+
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-checkstyle-plugin</artifactId>
                 <artifactId>maven-checkstyle-plugin</artifactId>
                 <version>2.12.1</version>
                 <version>2.12.1</version>
                 <dependencies>
                 <dependencies>