Adding model abstractions to help flesh-out the concepts.
diff --git a/net/api/src/main/java/org/onlab/onos/net/device/DeviceService.java b/net/api/src/main/java/org/onlab/onos/net/device/DeviceService.java
index ac2f4a4..42b9a31 100644
--- a/net/api/src/main/java/org/onlab/onos/net/device/DeviceService.java
+++ b/net/api/src/main/java/org/onlab/onos/net/device/DeviceService.java
@@ -22,7 +22,7 @@
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
diff --git a/net/api/src/main/java/org/onlab/onos/net/host/HostService.java b/net/api/src/main/java/org/onlab/onos/net/host/HostService.java
new file mode 100644
index 0000000..ed94522
--- /dev/null
+++ b/net/api/src/main/java/org/onlab/onos/net/host/HostService.java
@@ -0,0 +1,67 @@
+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);
+
+}
diff --git a/net/api/src/main/java/org/onlab/onos/net/link/LinkService.java b/net/api/src/main/java/org/onlab/onos/net/link/LinkService.java
new file mode 100644
index 0000000..fadecdb
--- /dev/null
+++ b/net/api/src/main/java/org/onlab/onos/net/link/LinkService.java
@@ -0,0 +1,59 @@
+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);
+
+}
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyDescription.java b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyDescription.java
index 0c55314..d9ec746 100644
--- a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyDescription.java
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyDescription.java
@@ -17,4 +17,14 @@
*/
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
+
}
+
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyEvent.java b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyEvent.java
new file mode 100644
index 0000000..fcbe858
--- /dev/null
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyEvent.java
@@ -0,0 +1,43 @@
+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);
+ }
+
+}
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyListener.java b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyListener.java
new file mode 100644
index 0000000..bcc2cf3
--- /dev/null
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyListener.java
@@ -0,0 +1,9 @@
+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> {
+}
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyService.java b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyService.java
new file mode 100644
index 0000000..4e1211a
--- /dev/null
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyService.java
@@ -0,0 +1,39 @@
+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);
+
+}