Adding model abstractions to help flesh-out the concepts.

@@ -22,7 +22,7 @@ public interface DeviceService {
     MastershipRole getRole(DeviceId deviceId);
 
     /**
-     * Returns an iterable collection of the currently known infrastructure
+     * Returns a collection of the currently known infrastructure
      * devices.
      *
      * @return collection of devices

+package org.onlab.onos.net.host;
+
+import org.onlab.onos.net.ConnectPoint;
+import org.onlab.onos.net.DeviceId;
+import org.onlab.onos.net.ElementId;
+import org.onlab.onos.net.Host;
+
+import java.util.Set;
+
+/**
+ * Service for interacting with the inventory of end-station hosts.
+ */
+public interface HostService {
+
+    /**
+     * Returns a collection of all end-station hosts.
+     *
+     * @return collection of hosts
+     */
+    Iterable<Host> getHosts();
+
+    /**
+     * Returns the host with the specified identifier.
+     *
+     * @param hostId host identifier
+     * @return host or null if one with the given identifier is not known
+     */
+    Host getHost(ElementId hostId); // TODO: change to HostId
+
+    // TODO: determine which ones make sense or which we care to support
+    // Set<Host> getHostsByVlan(VlanId vlan);
+    // Set<Host> getHostsByMac(MacAddress mac);
+    // Set<Host> getHostsByIp(IpAddress ip);
+
+    /**
+     * Returns the set of hosts whose most recent location is the specified
+     * connection point.
+     *
+     * @param connectPoint connection point
+     * @return set of hosts connected to the connection point
+     */
+    Set<Host> getConnectedHosts(ConnectPoint connectPoint);
+
+    /**
+     * Returns the set of hosts whose most recent location is the specified
+     * infrastructure device.
+     *
+     * @param deviceId device identifier
+     * @return set of hosts connected to the device
+     */
+    Set<Host> getConnectedHosts(DeviceId deviceId);
+
+    /**
+     * Adds the specified host listener.
+     *
+     * @param listener host listener
+     */
+    void addListener(HostListener listener);
+
+    /**
+     * Removes the specified host listener.
+     *
+     * @param listener host listener
+     */
+    void removeListener(HostListener listener);
+
+}

+package org.onlab.onos.net.link;
+
+import org.onlab.onos.net.DeviceId;
+import org.onlab.onos.net.Link;
+
+import java.util.Set;
+
+/**
+ * Service for interacting with the inventory of infrastructure links.
+ */
+public interface LinkService {
+
+    /**
+     * Returns a collection of all known infrastructure links.
+     *
+     * @return all infrastructure links
+     */
+    Iterable<Link> getLinks();
+
+    /**
+     * Returns set of all infrastructure links leading to and from the
+     * specified device.
+     *
+     * @param deviceId device identifier
+     * @return set of device links
+     */
+    Set<Link> getDeviceLinks(DeviceId deviceId);
+
+    /**
+     * Returns set of all infrastructure links leading from the specified device.
+     *
+     * @param deviceId device identifier
+     * @return set of device egress links
+     */
+    Set<Link> getDeviceEgressLinks(DeviceId deviceId);
+
+    /**
+     * Returns set of all infrastructure links leading to the specified device.
+     *
+     * @param deviceId device identifier
+     * @return set of device ingress links
+     */
+    Set<Link> getDeviceInressLinks(DeviceId deviceId);
+
+    /**
+     * Adds the specified link listener.
+     *
+     * @param listener link listener
+     */
+    void addListener(LinkListener listener);
+
+    /**
+     * Removes the specified link listener.
+     *
+     * @param listener link listener
+     */
+    void removeListener(LinkListener listener);
+
+}

@@ -17,4 +17,14 @@ public interface TopologyDescription extends Description {
      */
     Collection<Description> details();
 
+    // Default topology provider/computor should do the following:
+    // create graph
+    // search graph for SCC clusters (Tarjan)
+    // search graph for all pairs shortest paths based on hop-count
+    //      this means all shortest paths, between all pairs; not just one shortest path
+    // optionally use path results to produce destination-rooted broadcast trees
+
+    // provide description with the graph, clusters, paths and trees upwards
+
 }
+

+package org.onlab.onos.net.topology;
+
+import org.onlab.onos.event.AbstractEvent;
+import org.onlab.onos.net.Topology;
+
+/**
+ * Describes network topology event.
+ */
+public class TopologyEvent extends AbstractEvent<TopologyEvent.Type, Topology> {
+
+    /**
+     * Type of topology events.
+     */
+    public enum Type {
+        /**
+         * Signifies that topology has changed.
+         */
+        TOPOLOGY_CHANGED
+    }
+
+    /**
+     * Creates an event of a given type and for the specified topology and the
+     * current time.
+     *
+     * @param type     topology event type
+     * @param topology event topology subject
+     */
+    public TopologyEvent(Type type, Topology topology) {
+        super(type, topology);
+    }
+
+    /**
+     * Creates an event of a given type and for the specified topology and time.
+     *
+     * @param type     link event type
+     * @param topology event topology subject
+     * @param time     occurrence time
+     */
+    public TopologyEvent(Type type, Topology topology, long time) {
+        super(type, topology, time);
+    }
+
+}

+package org.onlab.onos.net.topology;
+
+import org.onlab.onos.event.EventListener;
+
+/**
+ * Entity capable of receiving network topology related events.
+ */
+public interface TopologyListener extends EventListener<TopologyEvent> {
+}

+package org.onlab.onos.net.topology;
+
+import org.onlab.onos.net.Topology;
+
+/**
+ * Service for providing network topology information.
+ */
+public interface TopologyService {
+
+    /**
+     * Returns the current topology descriptor.
+     *
+     * @return current topology
+     */
+    Topology currentTopology();
+
+    // TODO: Figure out hot to best export graph traversal methods via Graph/Vertex/Edge
+    // TODO: figure out how we want this to be presented, via Topology or via TopologyService
+    // Set<TopologyCluster> getClusters(Topology topology);
+    // Set<Path> getPaths(Topology topology, DeviceId src, DeviceId dst);
+    // Set<Path> getPaths(Topology topology, DeviceId src, DeviceId dst, LinkWeight weight);
+    // boolean isInfrastructure(Topology topology, ConnectPoint connectPoint);
+    // boolean isInBroadcastTree(Topology topology, ConnectPoint connectPoint);
+
+    /**
+     * Adds the specified topology listener.
+     *
+     * @param listener topology listener
+     */
+    void addListener(TopologyListener listener);
+
+    /**
+     * Removes the specified topology listener.
+     *
+     * @param listener topology listener
+     */
+    void removeListener(TopologyListener listener);
+
+}