Sketching more topology related stuff.
Added overview.html for Java API docs.
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/ClusterId.java b/net/api/src/main/java/org/onlab/onos/net/topology/ClusterId.java
new file mode 100644
index 0000000..af8f122
--- /dev/null
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/ClusterId.java
@@ -0,0 +1,49 @@
+package org.onlab.onos.net.topology;
+
+import java.util.Objects;
+
+import static com.google.common.base.MoreObjects.toStringHelper;
+
+/**
+ * Representation of the topology cluster identity.
+ */
+public final class ClusterId {
+
+ private final int id;
+
+ // Public construction is prohibit
+ private ClusterId(int id) {
+ this.id = id;
+ }
+
+ /**
+ * Returns the cluster identifier, represented by the specified integer
+ * serial number.
+ *
+ * @param id integer serial number
+ * @return cluster identifier
+ */
+ public static ClusterId clusterId(int id) {
+ return new ClusterId(id);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(id);
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (obj instanceof ClusterId) {
+ final ClusterId other = (ClusterId) obj;
+ return Objects.equals(this.id, other.id);
+ }
+ return false;
+ }
+
+ @Override
+ public String toString() {
+ return toStringHelper(this).add("id", id).toString();
+ }
+
+}
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/DefaultTopologyCluster.java b/net/api/src/main/java/org/onlab/onos/net/topology/DefaultTopologyCluster.java
new file mode 100644
index 0000000..f33dcf7
--- /dev/null
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/DefaultTopologyCluster.java
@@ -0,0 +1,81 @@
+package org.onlab.onos.net.topology;
+
+import org.onlab.onos.net.DeviceId;
+
+import java.util.Objects;
+
+import static com.google.common.base.MoreObjects.toStringHelper;
+
+/**
+ * Default implementation of a network topology cluster.
+ */
+public class DefaultTopologyCluster implements TopologyCluster {
+
+ private final ClusterId id;
+ private final int deviceCount;
+ private final int linkCount;
+ private final DeviceId root;
+
+ /**
+ * Creates a new topology cluster descriptor with the specified attributes.
+ *
+ * @param id cluster id
+ * @param deviceCount number of devices in the cluster
+ * @param linkCount number of links in the cluster
+ * @param root cluster root node
+ */
+ public DefaultTopologyCluster(ClusterId id, int deviceCount, int linkCount,
+ DeviceId root) {
+ this.id = id;
+ this.deviceCount = deviceCount;
+ this.linkCount = linkCount;
+ this.root = root;
+ }
+
+ @Override
+ public ClusterId id() {
+ return id;
+ }
+
+ @Override
+ public int deviceCount() {
+ return deviceCount;
+ }
+
+ @Override
+ public int linkCount() {
+ return linkCount;
+ }
+
+ @Override
+ public DeviceId root() {
+ return root;
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(id, deviceCount, linkCount, root);
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (obj instanceof DefaultTopologyCluster) {
+ final DefaultTopologyCluster other = (DefaultTopologyCluster) obj;
+ return Objects.equals(this.id, other.id) &&
+ Objects.equals(this.deviceCount, other.deviceCount) &&
+ Objects.equals(this.linkCount, other.linkCount) &&
+ Objects.equals(this.root, other.root);
+ }
+ return false;
+ }
+
+ @Override
+ public String toString() {
+ return toStringHelper(this)
+ .add("id", id)
+ .add("deviceCount", deviceCount)
+ .add("linkCount", linkCount)
+ .add("root", root)
+ .toString();
+ }
+}
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/Topology.java b/net/api/src/main/java/org/onlab/onos/net/topology/Topology.java
new file mode 100644
index 0000000..f71a5ec
--- /dev/null
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/Topology.java
@@ -0,0 +1,50 @@
+package org.onlab.onos.net.topology;
+
+import org.onlab.onos.net.Provided;
+
+/**
+ * Represents a network topology computation snapshot.
+ */
+public interface Topology extends Provided {
+
+ /**
+ * Returns the time, specified in milliseconds since start of epoch,
+ * when the topology became active and made available.
+ *
+ * @return time in milliseconds since start of epoch
+ */
+ long time();
+
+ /**
+ * Returns the number of SCCs (strongly connected components) in the
+ * topology.
+ *
+ * @return number of clusters
+ */
+ int clusterCount();
+
+ /**
+ * Returns the number of infrastructure devices in the topology.
+ *
+ * @return number of devices
+ */
+ int deviceCount();
+
+
+ /**
+ * Returns the number of infrastructure links in the topology.
+ *
+ * @return number of links
+ */
+ int linkCount();
+
+ /**
+ * Returns the number of infrastructure paths computed between devices
+ * in the topology. This means the number of all the shortest paths
+ * (hop-count) between all device pairs.
+ *
+ * @return number of paths
+ */
+ int pathCount();
+
+}
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyCluster.java b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyCluster.java
index e58c784..46c9872 100644
--- a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyCluster.java
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyCluster.java
@@ -1,10 +1,38 @@
package org.onlab.onos.net.topology;
+import org.onlab.onos.net.DeviceId;
+
/**
* Representation of an SCC (strongly-connected component) in a network topology.
*/
public interface TopologyCluster {
- // TODO: add stuff in here: id, deviceCount, linkCount
+ /**
+ * Returns the cluster id.
+ *
+ * @return cluster identifier
+ */
+ ClusterId id();
+
+ /**
+ * Returns the number of devices in the cluster.
+ *
+ * @return number of cluster devices
+ */
+ int deviceCount();
+
+ /**
+ * Returns the number of infrastructure links in the cluster.
+ *
+ * @return number of cluster links
+ */
+ int linkCount();
+
+ /**
+ * Returns the device identifier of the cluster root device.
+ *
+ * @return cluster root device identifier
+ */
+ DeviceId root();
}
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 d9ec746..dd0102d 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
@@ -1,8 +1,12 @@
package org.onlab.onos.net.topology;
+import org.onlab.graph.Graph;
+import org.onlab.graph.GraphPathSearch;
import org.onlab.onos.net.Description;
+import org.onlab.onos.net.DeviceId;
+import org.onlab.onos.net.Link;
-import java.util.Collection;
+import java.util.Set;
/**
* Describes attribute(s) of a network topology.
@@ -10,21 +14,58 @@
public interface TopologyDescription extends Description {
/**
- * A collection of Device, Link, and Host descriptors that describe
- * the changes tha have occurred in the network topology.
+ * Returns the creation timestamp of the topology description. This is
+ * expressed in system nanos to allow proper sequencing.
*
- * @return network element descriptions describing topology change
+ * @return topology description creation timestamp
*/
- Collection<Description> details();
+ long timestamp();
- // 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
+ /**
+ * Returns the topology graph.
+ *
+ * @return network graph
+ */
+ Graph<TopoVertex, TopoEdge> graph();
- // provide description with the graph, clusters, paths and trees upwards
+ /**
+ * Returns the results of the path search through the network graph. This
+ * is assumed to contain results of seach fro the given device to all
+ * other devices.
+ *
+ * @param srcDeviceId source device identifier
+ * @return path search result for the given source node
+ */
+ GraphPathSearch.Result pathResults(DeviceId srcDeviceId);
+
+ /**
+ * Returns the set of topology SCC clusters.
+ *
+ * @return set of SCC clusters
+ */
+ Set<TopologyCluster> clusters();
+
+ /**
+ * Returns the set of devices contained by the specified topology cluster.
+ *
+ * @return set of devices that belong to the specified cluster
+ */
+ Set<DeviceId> clusterDevices(TopologyCluster cluster);
+
+ /**
+ * Returns the set of infrastructure links contained by the specified cluster.
+ *
+ * @return set of links that form the given cluster
+ */
+ Set<Link> clusterLinks(TopologyCluster cluster);
+
+ /**
+ * Returns the topology SCC cluster which contains the given device.
+ *
+ * @param deviceId device identifier
+ * @return topology cluster that contains the specified device
+ */
+ TopologyCluster clusterFor(DeviceId deviceId);
}
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
index fcbe858..0be5323 100644
--- 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
@@ -1,7 +1,6 @@
package org.onlab.onos.net.topology;
import org.onlab.onos.event.AbstractEvent;
-import org.onlab.onos.net.Topology;
/**
* Describes network topology event.
diff --git a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyProviderService.java b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyProviderService.java
index b3d85ad..0e03767 100644
--- a/net/api/src/main/java/org/onlab/onos/net/topology/TopologyProviderService.java
+++ b/net/api/src/main/java/org/onlab/onos/net/topology/TopologyProviderService.java
@@ -1,7 +1,10 @@
package org.onlab.onos.net.topology;
+import org.onlab.onos.event.Event;
import org.onlab.onos.net.provider.ProviderService;
+import java.util.List;
+
/**
* Means for injecting topology information into the core.
*/
@@ -14,7 +17,9 @@
* Signals the core that some aspect of the topology has changed.
*
* @param topoDescription information about topology
+ * @param reasons events that triggered topology change
*/
- void topologyChanged(TopologyDescription topoDescription);
+ void topologyChanged(TopologyDescription topoDescription,
+ List<Event> reasons);
}
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
index a6962a2..36ee666 100644
--- 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
@@ -4,7 +4,6 @@
import org.onlab.onos.net.ConnectPoint;
import org.onlab.onos.net.DeviceId;
import org.onlab.onos.net.Path;
-import org.onlab.onos.net.Topology;
import java.util.Set;
@@ -37,8 +36,8 @@
Graph<TopoVertex, TopoEdge> getGraph(Topology topology);
/**
- * Returns the set of all shortest paths, in terms of hop-count, between
- * the specified source and destination devices.
+ * Returns the set of all shortest paths, precomputed in terms of hop-count,
+ * between the specified source and destination devices.
*
* @param topology topology descriptor
* @param src source device
@@ -71,7 +70,8 @@
/**
- * Indicates whether the specified connection point allows broadcast.
+ * Indicates whether the specified connection point belong to the
+ * broadcast tree.
*
* @param topology topology descriptor
* @param connectPoint connection point