cleanup and javadoc for remaining files in onos.core.intent
Change-Id: I3bfe85579daa4bb35be6133b3221fabd80b10e00
diff --git a/src/main/java/net/onrc/onos/core/intent/ConstrainedBFSTree.java b/src/main/java/net/onrc/onos/core/intent/ConstrainedBFSTree.java
index 6cee929..69c0635 100644
--- a/src/main/java/net/onrc/onos/core/intent/ConstrainedBFSTree.java
+++ b/src/main/java/net/onrc/onos/core/intent/ConstrainedBFSTree.java
@@ -9,13 +9,11 @@
import net.onrc.onos.core.topology.Switch;
/**
- * This class creates bandwidth constrained breadth first tree
- * and returns paths from root switch to leaf switches
- * which satisfies the bandwidth condition.
- * If bandwidth parameter is not specified, the normal breadth first tree will be calculated.
- * The paths are snapshot paths at the point of the class instantiation.
- *
- * @author Toshio Koide (t-koide@onlab.us)
+ * This class creates bandwidth constrained breadth first tree and returns paths
+ * from root switch to leaf switches which satisfies the bandwidth condition. If
+ * bandwidth parameter is not specified, the normal breadth first tree will be
+ * calculated. The paths are snapshot paths at the point of the class
+ * instantiation.
*/
public class ConstrainedBFSTree {
LinkedList<Switch> switchQueue = new LinkedList<>();
@@ -26,11 +24,23 @@
PathIntentMap intents = null;
double bandwidth = 0.0; // 0.0 means no limit for bandwidth (normal BFS tree)
+ /**
+ * Constructor.
+ *
+ * @param rootSwitch root of the BFS tree
+ */
public ConstrainedBFSTree(Switch rootSwitch) {
this.rootSwitch = rootSwitch;
calcTree();
}
+ /**
+ * Constructor.
+ *
+ * @param rootSwitch root switch of the BFS tree
+ * @param intents map of Intents
+ * @param bandwidth
+ */
public ConstrainedBFSTree(Switch rootSwitch, PathIntentMap intents, double bandwidth) {
this.rootSwitch = rootSwitch;
this.intents = intents;
@@ -38,6 +48,9 @@
calcTree();
}
+ /**
+ * Calculates the BFS tree using any provided constraints and Intents.
+ */
protected void calcTree() {
switchQueue.add(rootSwitch);
switchSearched.add(rootSwitch);
@@ -49,7 +62,7 @@
continue;
}
if (intents != null &&
- intents.getAvailableBandwidth(link) < bandwidth) {
+ intents.getAvailableBandwidth(link) < bandwidth) {
continue;
}
switchQueue.add(reachedSwitch);
@@ -59,6 +72,12 @@
}
}
+ /**
+ * Return the computed path from the root switch to the leaf switch.
+ *
+ * @param leafSwitch the leaf switch
+ * @return the Path from the root switch to the leaf switch
+ */
public Path getPath(Switch leafSwitch) {
Path path = paths.get(leafSwitch);
Long rootSwitchDpid = rootSwitch.getDpid();
diff --git a/src/main/java/net/onrc/onos/core/intent/ConstrainedShortestPathIntent.java b/src/main/java/net/onrc/onos/core/intent/ConstrainedShortestPathIntent.java
index 1661c02..0d842eb 100644
--- a/src/main/java/net/onrc/onos/core/intent/ConstrainedShortestPathIntent.java
+++ b/src/main/java/net/onrc/onos/core/intent/ConstrainedShortestPathIntent.java
@@ -1,7 +1,9 @@
package net.onrc.onos.core.intent;
/**
- * @author Toshio Koide (t-koide@onlab.us)
+ * The ConstrainedShortestPathIntent is a "high-level" intent that allows
+ * applications to reserve bandwith along the shortest available path between
+ * specified endpoints.
*/
public class ConstrainedShortestPathIntent extends ShortestPathIntent {
protected double bandwidth;
@@ -12,6 +14,19 @@
protected ConstrainedShortestPathIntent() {
}
+ /**
+ * Constructor.
+ *
+ * @param id the ID for this Intent
+ * @param srcSwitch Source Switch DPID
+ * @param srcPort Source Port
+ * @param srcMac Source Host MAC Address
+ * @param dstSwitch Destination Switch DPID
+ * @param dstPort Destination Port
+ * @param dstMac Destination Host MAC Address
+ * @param bandwidth bandwidth which should be allocated for the path.
+ * If 0, no intent for bandwidth allocation (best effort).
+ */
// CHECKSTYLE:OFF suppress the warning about too many parameters
public ConstrainedShortestPathIntent(String id,
long srcSwitch, long srcPort, long srcMac,
@@ -22,19 +37,34 @@
this.bandwidth = bandwidth;
}
+ /**
+ * Get the bandwidth specified for this Intent.
+ * TODO: specify unit
+ *
+ * @return this Intent's bandwidth
+ */
public double getBandwidth() {
return bandwidth;
}
+ /**
+ * Generates a hash code using the Intent ID.
+ *
+ * @return hashcode
+ */
@Override
public int hashCode() {
- // TODO: Is this the intended behavior?
- return (super.hashCode());
+ return super.hashCode();
}
+ /**
+ * Compares two intent object by type (class) and Intent ID.
+ *
+ * @param obj other Intent
+ * @return true if equal, false otherwise
+ */
@Override
public boolean equals(Object obj) {
- // TODO: Is this the intended behavior?
- return (super.equals(obj));
+ return super.equals(obj);
}
}
diff --git a/src/main/java/net/onrc/onos/core/intent/ErrorIntent.java b/src/main/java/net/onrc/onos/core/intent/ErrorIntent.java
index c1722fd..7a5d04a 100644
--- a/src/main/java/net/onrc/onos/core/intent/ErrorIntent.java
+++ b/src/main/java/net/onrc/onos/core/intent/ErrorIntent.java
@@ -2,13 +2,22 @@
/**
* This class is instantiated by Run-times to express intent calculation error.
- *
- * @author Toshio Koide (t-koide@onlab.us)
*/
public class ErrorIntent extends Intent {
public enum ErrorType {
+ /**
+ * Intent not supported by runtime.
+ */
UNSUPPORTED_INTENT,
+
+ /**
+ * One or more of the switches refereneced by this Intent not found.
+ */
SWITCH_NOT_FOUND,
+
+ /**
+ * Path specified by Intent is not in the topology.
+ */
PATH_NOT_FOUND,
}
@@ -22,6 +31,13 @@
protected ErrorIntent() {
}
+ /**
+ * Constructor.
+ *
+ * @param errorType error type
+ * @param message human-readable error string
+ * @param parentIntent related parent Intent
+ */
public ErrorIntent(ErrorType errorType, String message, Intent parentIntent) {
super(parentIntent.getId());
this.errorType = errorType;
@@ -29,15 +45,24 @@
this.parentIntent = parentIntent;
}
+ /**
+ * Generates a hash code using the Intent ID.
+ *
+ * @return hashcode
+ */
@Override
public int hashCode() {
- // TODO: Is this the intended behavior?
- return (super.hashCode());
+ return super.hashCode();
}
+ /**
+ * Compares two intent object by type (class) and Intent ID.
+ *
+ * @param obj other Intent
+ * @return true if equal, false otherwise
+ */
@Override
public boolean equals(Object obj) {
- // TODO: Is this the intended behavior?
- return (super.equals(obj));
+ return super.equals(obj);
}
}
diff --git a/src/main/java/net/onrc/onos/core/intent/Intent.java b/src/main/java/net/onrc/onos/core/intent/Intent.java
index f90b6b0..b99a08c 100644
--- a/src/main/java/net/onrc/onos/core/intent/Intent.java
+++ b/src/main/java/net/onrc/onos/core/intent/Intent.java
@@ -5,17 +5,58 @@
import com.esotericsoftware.kryo.serializers.FieldSerializer.Optional;
/**
- * @author Toshio Koide (t-koide@onlab.us)
+ * This is the base class for the connectivity abstraction. It allows applications
+ * to specify end hosts, apply some basic filtering to traffic, and constrain traffic.
+ * <p>
+ * This class is subclassed to provide other "high level" intent types like shortest
+ * path connectivity and bandwidth constrained shortest path, as well as "low level"
+ * intent types like full specified/reserved path connectivity.
+ * <p>
+ * The reasoning behind "intent" is that the applications can provide some abstract
+ * representation of how traffic should flow be handled by the networking, allowing
+ * the network OS to compile, reserve and optimize the dataplane to satisfy those
+ * constraints.
*/
public class Intent {
public enum IntentState {
+ /**
+ * Intent has been created.
+ */
CREATED,
+
+ /**
+ * Installation of this intent has been requested.
+ */
INST_REQ,
+
+ /**
+ * Intent was not installed.
+ */
INST_NACK,
+
+ /**
+ * Intent has been successfully installed in the dataplane.
+ */
INST_ACK,
+
+ /**
+ * A delete/removal of the intent from this dataplane has been requested.
+ */
DEL_REQ,
+
+ /**
+ * The framework is in the process of removing this intent from the dataplane.
+ */
DEL_PENDING,
+
+ /**
+ * Intent has been successfully removed from the dataplane.
+ */
DEL_ACK,
+
+ /**
+ * Intent is pending reroute due to a network event.
+ */
REROUTE_REQ,
}
@@ -24,7 +65,7 @@
private boolean pathFrozen = false;
@Optional(value = "logs")
- private LinkedList<String> logs = new LinkedList<>();
+ private final LinkedList<String> logs = new LinkedList<>();
/**
* Default constructor for Kryo deserialization.
@@ -33,25 +74,53 @@
logs.add(String.format("created, time:%d", System.nanoTime())); // for measurement
}
+ /**
+ * Constructor.
+ *
+ * @param id Intent ID
+ */
public Intent(String id) {
logs.add(String.format("created, time:%d", System.nanoTime())); // for measurement
this.id = id;
}
+ /**
+ * Constructor.
+ *
+ * @param id Intent ID
+ * @param state current state of the new Intent
+ */
public Intent(String id, IntentState state) {
logs.add(String.format("created, time:%d", System.nanoTime())); // for measurement
setState(state);
this.id = id;
}
+ /**
+ * Gets the Intent ID.
+ *
+ * @return Intent ID
+ */
public String getId() {
return id;
}
+ /**
+ * Gets the current state of this Intent.
+ *
+ * @return current state of this Intent
+ */
public IntentState getState() {
return state;
}
+ /**
+ * Sets the new state for this Intent, and stores the new state in
+ * this Intent's log.
+ *
+ * @param newState new state for this Intent
+ * @return the old state for this Intent
+ */
public IntentState setState(IntentState newState) {
logs.add(String.format("setState, oldState:%s, newState:%s, time:%d",
state, newState, System.nanoTime())); // for measurement
@@ -63,23 +132,51 @@
return oldState;
}
+ /**
+ * Checks to see if this Intent's path is frozen.
+ * <p>
+ * Frozen paths will not be rerouted when the network topology changes.
+ *
+ * @return true if frozen, false otherwise
+ */
public boolean isPathFrozen() {
return pathFrozen;
}
+ /**
+ * Sets the new frozen state for this Intent.
+ *
+ * @param isFrozen the new frozen state for this Intent
+ */
public void setPathFrozen(boolean isFrozen) {
pathFrozen = isFrozen;
}
+ /**
+ * Retrieves the logs for this intent which includes creation and state changes.
+ *
+ * @return a list of String log entries
+ */
public LinkedList<String> getLogs() {
return logs;
}
+ /**
+ * Generates a hash code using the Intent ID.
+ *
+ * @return hashcode
+ */
@Override
public int hashCode() {
return (id == null) ? 0 : id.hashCode();
}
+ /**
+ * Compares two intent object by type (class) and Intent ID.
+ *
+ * @param obj other Intent
+ * @return true if equal, false otherwise
+ */
@Override
public boolean equals(Object obj) {
if (this == obj) {
@@ -99,6 +196,11 @@
return true;
}
+ /**
+ * Returns a String representation of this Intent.
+ *
+ * @return "Intent ID, State"
+ */
@Override
public String toString() {
return id.toString() + ", " + state.toString();
diff --git a/src/main/java/net/onrc/onos/core/intent/IntentMap.java b/src/main/java/net/onrc/onos/core/intent/IntentMap.java
index 7d87fa2..136e442 100644
--- a/src/main/java/net/onrc/onos/core/intent/IntentMap.java
+++ b/src/main/java/net/onrc/onos/core/intent/IntentMap.java
@@ -9,16 +9,19 @@
import net.onrc.onos.core.intent.Intent.IntentState;
import net.onrc.onos.core.intent.runtime.IntentStateList;
+
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
- * @author Toshio Koide (t-koide@onlab.us)
+ * The IntentMap contains all of the Intents in the system. It is also
+ * responsible for handling notifications to interested listeners when
+ * Intents are changed/updated.
*/
public class IntentMap {
- private HashSet<ChangedListener> listeners = new HashSet<>();
- private HashMap<String, Intent> intents = new HashMap<>();
- private LinkedList<ChangedEvent> events = new LinkedList<>();
+ private final HashSet<ChangedListener> listeners = new HashSet<>();
+ private final HashMap<String, Intent> intents = new HashMap<>();
+ private final LinkedList<ChangedEvent> events = new LinkedList<>();
private static final Logger log = LoggerFactory.getLogger(IntentMap.class);
public enum ChangedEventType {
@@ -42,7 +45,17 @@
STATE_CHANGED,
}
+ /**
+ * This class is a wrapper for Intent event notifications.
+ */
public static class ChangedEvent {
+
+ /**
+ * Constructor.
+ *
+ * @param eventType the type of event
+ * @param intent the affected Intent
+ */
public ChangedEvent(ChangedEventType eventType, Intent intent) {
this.eventType = eventType;
this.intent = intent;
@@ -71,6 +84,9 @@
}
}
+ /**
+ * An interface to listen to Intent updates.
+ */
public interface ChangedListener extends EventListener {
void intentsChange(LinkedList<ChangedEvent> events);
}
@@ -79,21 +95,26 @@
// public methods
//================================================================================
+ /**
+ * Performs the specified operations on a list of Intents.
+ *
+ * @param operations list of Intents and associated operations
+ */
public void executeOperations(IntentOperationList operations) {
for (IntentOperation operation : operations) {
switch (operation.operator) {
- case ADD:
- handleAddOperation(operation);
- break;
- case REMOVE:
- handleRemoveOperation(operation);
- break;
- case ERROR:
- handleErrorOperation(operation);
- break;
- default:
- log.error("Unknown intent operation {}", operation.operator);
- break;
+ case ADD:
+ handleAddOperation(operation);
+ break;
+ case REMOVE:
+ handleRemoveOperation(operation);
+ break;
+ case ERROR:
+ handleErrorOperation(operation);
+ break;
+ default:
+ log.error("Unknown intent operation {}", operation.operator);
+ break;
}
}
notifyEvents();
@@ -132,6 +153,11 @@
notifyEvents();
}
+ /**
+ * Update the states of intents in the map to match those provided.
+ *
+ * @param states list of new Intent states
+ */
public void changeStates(IntentStateList states) {
for (Entry<String, IntentState> state : states.entrySet()) {
setState(state.getKey(), state.getValue());
@@ -139,18 +165,39 @@
notifyEvents();
}
+ /**
+ * Get an Intent from the map.
+ *
+ * @param intentId ID of requested Intent
+ * @return Intent with specified ID
+ */
public Intent getIntent(String intentId) {
return intents.get(intentId);
}
+ /**
+ * Get all Intents from the map.
+ *
+ * @return a collection including all Intents
+ */
public Collection<Intent> getAllIntents() {
return intents.values();
}
+ /**
+ * Add a change listener.
+ *
+ * @param listener new listener to change events
+ */
public void addChangeListener(ChangedListener listener) {
listeners.add(listener);
}
+ /**
+ * Remove a change listener.
+ *
+ * @param listener the listener to be removed
+ */
public void removeChangedListener(ChangedListener listener) {
listeners.remove(listener);
}
@@ -159,6 +206,11 @@
// methods that affect intents map (protected)
//================================================================================
+ /**
+ * Put an intent in the map.
+ *
+ * @param intent intent to be added
+ */
protected void putIntent(Intent intent) {
if (intents.containsKey(intent.getId())) {
removeIntent(intent.getId());
@@ -167,6 +219,11 @@
events.add(new ChangedEvent(ChangedEventType.ADDED, intent));
}
+ /**
+ * Remove an intent from the map.
+ *
+ * @param intentId intent to be removed
+ */
protected void removeIntent(String intentId) {
Intent intent = intents.remove(intentId);
if (intent == null) {
@@ -175,6 +232,12 @@
events.add(new ChangedEvent(ChangedEventType.REMOVED, intent));
}
+ /**
+ * Change the state of an Intent in the map.
+ *
+ * @param intentId ID of the Intent to change
+ * @param state new state for the specified Intent
+ */
protected void setState(String intentId, IntentState state) {
Intent intent = intents.get(intentId);
if (intent == null) {
@@ -188,10 +251,20 @@
// helper methods (protected)
//================================================================================
+ /**
+ * Helper to add Intents to the map.
+ *
+ * @param operation the Intent to be added
+ */
protected void handleAddOperation(IntentOperation operation) {
putIntent(operation.intent);
}
+ /**
+ * Helper to remove Intents from the map.
+ *
+ * @param operation the Intent to be removed
+ */
protected void handleRemoveOperation(IntentOperation operation) {
Intent intent = getIntent(operation.intent.getId());
if (intent == null) {
@@ -202,6 +275,11 @@
}
}
+ /**
+ * Helper to handle Intents in the error state.
+ *
+ * @param operation the Intent to be resolved
+ */
protected void handleErrorOperation(IntentOperation operation) {
//TODO put error message into the intent
@@ -213,26 +291,29 @@
}
switch (targetIntent.getState()) {
- case CREATED:
- case INST_REQ:
- case INST_ACK:
- case REROUTE_REQ:
- setState(targetIntent.getId(), IntentState.INST_NACK);
- break;
- case DEL_REQ:
- setState(targetIntent.getId(), IntentState.DEL_PENDING);
- break;
- case INST_NACK:
- case DEL_PENDING:
- case DEL_ACK:
- // do nothing
- break;
- default:
- log.error("Unknown intent state {}", targetIntent.getState());
- break;
+ case CREATED:
+ case INST_REQ:
+ case INST_ACK:
+ case REROUTE_REQ:
+ setState(targetIntent.getId(), IntentState.INST_NACK);
+ break;
+ case DEL_REQ:
+ setState(targetIntent.getId(), IntentState.DEL_PENDING);
+ break;
+ case INST_NACK:
+ case DEL_PENDING:
+ case DEL_ACK:
+ // do nothing
+ break;
+ default:
+ log.error("Unknown intent state {}", targetIntent.getState());
+ break;
}
}
+ /**
+ * Notify all registered listeners of events in queue.
+ */
protected void notifyEvents() {
if (events.isEmpty()) {
return;
diff --git a/src/main/java/net/onrc/onos/core/intent/IntentOperation.java b/src/main/java/net/onrc/onos/core/intent/IntentOperation.java
index 0cb42ff..5233e26 100644
--- a/src/main/java/net/onrc/onos/core/intent/IntentOperation.java
+++ b/src/main/java/net/onrc/onos/core/intent/IntentOperation.java
@@ -1,7 +1,9 @@
package net.onrc.onos.core.intent;
/**
- * @author Toshio Koide (t-koide@onlab.us)
+ * This class is merely an Intent and an associated operation.
+ * <p>
+ * It exists so that the pair can be serialized for notifications and persistence.
*/
public class IntentOperation {
public enum Operator {
@@ -26,14 +28,28 @@
public Operator operator;
public Intent intent;
+ /**
+ * Default Constructor.
+ */
protected IntentOperation() {
}
+ /**
+ * Constructor.
+ *
+ * @param operator the operation to perform for this Intent
+ * @param intent the Intent
+ */
public IntentOperation(Operator operator, Intent intent) {
this.operator = operator;
this.intent = intent;
}
+ /**
+ * Returns a string representation of the operation and Intent.
+ *
+ * @return "operator, (Intent ID)"
+ */
@Override
public String toString() {
return operator.toString() + ", (" + intent.toString() + ")";
diff --git a/src/main/java/net/onrc/onos/core/intent/IntentOperationList.java b/src/main/java/net/onrc/onos/core/intent/IntentOperationList.java
index 7691c68..5f9154f 100644
--- a/src/main/java/net/onrc/onos/core/intent/IntentOperationList.java
+++ b/src/main/java/net/onrc/onos/core/intent/IntentOperationList.java
@@ -3,11 +3,19 @@
import java.util.LinkedList;
/**
- * @author Toshio Koide (t-koide@onlab.us)
+ * This class is simply a list of IntentOperations. It exists so
+ * that IntentOperations can be serialized for notifications and persistence.
*/
public class IntentOperationList extends LinkedList<IntentOperation> {
private static final long serialVersionUID = -3894081461861052610L;
+ /**
+ * Add an operator and Intent to the list.
+ *
+ * @param op operator for the Intent
+ * @param intent the Intent
+ * @return true
+ */
public boolean add(IntentOperation.Operator op, Intent intent) {
return add(new IntentOperation(op, intent));
}
diff --git a/src/main/java/net/onrc/onos/core/intent/Path.java b/src/main/java/net/onrc/onos/core/intent/Path.java
index e819290..1fa33cf 100644
--- a/src/main/java/net/onrc/onos/core/intent/Path.java
+++ b/src/main/java/net/onrc/onos/core/intent/Path.java
@@ -9,13 +9,11 @@
import net.onrc.onos.core.topology.LinkEvent;
/**
- * Base class for Path representation.
- *
- * @author Toshio Koide (t-koide@onlab.us)
+ * Base class for Path representation, which implements the List interface.
*/
public class Path implements List<LinkEvent> {
- private List<LinkEvent> links;
+ private final List<LinkEvent> links;
/**
* Default constructor to create an empty path.
@@ -24,6 +22,11 @@
links = new LinkedList<LinkEvent>();
}
+ /**
+ * Returns a string representation of the path.
+ *
+ * @return "[LinkEvent src->dst],..."
+ */
@Override
public String toString() {
StringBuilder builder = new StringBuilder();
diff --git a/src/main/java/net/onrc/onos/core/intent/PathIntent.java b/src/main/java/net/onrc/onos/core/intent/PathIntent.java
index 3a668bb..f2518a6 100644
--- a/src/main/java/net/onrc/onos/core/intent/PathIntent.java
+++ b/src/main/java/net/onrc/onos/core/intent/PathIntent.java
@@ -3,17 +3,33 @@
import java.util.Objects;
/**
- * @author Toshio Koide (t-koide@onlab.us)
+ * The PathIntent is a "low-level" intent that is the manifestation
+ * of a "high-level" intent. It contains the path through the network
+ * and a pointer to the "high-level" intent.
*/
public class PathIntent extends Intent {
protected Path path;
protected double bandwidth;
protected Intent parentIntent;
+ /**
+ * Generate the PathIntent ID for the first path for a
+ * parent Intent. It is derived from the parent Intent ID.
+ *
+ * @param parentId parent Intent ID
+ * @return new PathIntent ID
+ */
public static String createFirstId(String parentId) {
return String.format("%s___0", parentId);
}
+ /**
+ * Generate the PathIntent ID for subsequent paths used to
+ * satisfy a parent Intent. It is derived from the previous ID.
+ *
+ * @param currentId current PathIntent's ID
+ * @return new PathIntent ID
+ */
public static String createNextId(String currentId) {
String[] parts = currentId.split("___");
return String.format("%s___%d", parts[0], Long.parseLong(parts[1]) + 1);
@@ -26,11 +42,13 @@
}
/**
- * @param path
+ * Constructor.
+ *
+ * @param id the PathIntent ID
+ * @param path the path for this Intent
* @param bandwidth bandwidth which should be allocated for the path.
* If 0, no intent for bandwidth allocation (best effort).
* @param parentIntent parent intent. If null, this is root intent.
- * @param id
*/
public PathIntent(String id, Path path, double bandwidth, Intent parentIntent) {
super(id);
@@ -39,14 +57,30 @@
this.parentIntent = parentIntent;
}
+ /**
+ * Get the bandwidth specified for this Intent.
+ * TODO: specify unit
+ *
+ * @return this Intent's bandwidth
+ */
public double getBandwidth() {
return bandwidth;
}
+ /**
+ * Get the Path for this Intent.
+ *
+ * @return this Intent's Path
+ */
public Path getPath() {
return path;
}
+ /**
+ * Get the parent Intent.
+ *
+ * @return the parent Intent
+ */
public Intent getParentIntent() {
return parentIntent;
}
@@ -71,18 +105,32 @@
return Objects.equals(getParentIntent(), target.getParentIntent());
}
+ /**
+ * Generates a hash code using the Intent ID.
+ *
+ * @return hashcode
+ */
@Override
public int hashCode() {
- // TODO: Is this the intended behavior?
- return (super.hashCode());
+ return super.hashCode();
}
+ /**
+ * Compares two intent object by type (class) and Intent ID.
+ *
+ * @param obj other Intent
+ * @return true if equal, false otherwise
+ */
@Override
public boolean equals(Object obj) {
- // TODO: Is this the intended behavior?
- return (super.equals(obj));
+ return super.equals(obj);
}
+ /**
+ * Returns a String representation of this Intent.
+ *
+ * @return "Intent ID, State, Path"
+ */
@Override
public String toString() {
return String.format("%s, %s, %s", getId(), getState(), getPath());
diff --git a/src/main/java/net/onrc/onos/core/intent/PathIntentMap.java b/src/main/java/net/onrc/onos/core/intent/PathIntentMap.java
index de1f6e2..12c81c5 100644
--- a/src/main/java/net/onrc/onos/core/intent/PathIntentMap.java
+++ b/src/main/java/net/onrc/onos/core/intent/PathIntentMap.java
@@ -10,15 +10,27 @@
import net.onrc.onos.core.topology.PortEvent.SwitchPort;
/**
- * @author Toshio Koide (t-koide@onlab.us)
+ * In addition to maintaining the Intent ID to Intent mapping of its
+ * superclass, this class maintains a mapping from switch port to
+ * PathIntent. It is used to quickly identify Intents that are affected
+ * when a network event involves a particular switch port.
*/
public class PathIntentMap extends IntentMap {
- private HashMap<Long, HashMap<Long, HashSet<PathIntent>>> intents;
+ private final HashMap<Long, HashMap<Long, HashSet<PathIntent>>> intents;
+ /**
+ * Constructor.
+ */
public PathIntentMap() {
intents = new HashMap<>();
}
+ /**
+ * Retrieve all PathIntents that contain the specified switch port.
+ *
+ * @param swPort the switch port to retrieve Intents for.
+ * @return a set of all intents that contain swPort
+ */
private HashSet<PathIntent> get(SwitchPort swPort) {
Long dpid = swPort.getDpid();
Long port = swPort.getNumber();
@@ -35,10 +47,22 @@
return targetIntents;
}
+ /**
+ * Add a PathIntent to a particular switch port.
+ *
+ * @param swPort switch port
+ * @param intent Path Intent
+ */
private void put(SwitchPort swPort, PathIntent intent) {
get(swPort).add(intent);
}
+ /**
+ * Add a PathIntent to the map. The function will automatically
+ * update the map with all switch ports contained in the Intent.
+ *
+ * @param intent the PathIntent
+ */
@Override
protected void putIntent(Intent intent) {
if (!(intent instanceof PathIntent)) {
@@ -53,6 +77,11 @@
}
}
+ /**
+ * Removes a PathIntent from the map, including all switch ports.
+ *
+ * @param intentId the ID of the PathIntent to be removed
+ */
@Override
protected void removeIntent(String intentId) {
PathIntent intent = (PathIntent) getIntent(intentId);
@@ -63,12 +92,25 @@
super.removeIntent(intentId);
}
+ /**
+ * Retrieve all intents that use a particular link.
+ *
+ * @param linkEvent the link to look up
+ * @return a collection of PathIntents that use the link
+ */
public Collection<PathIntent> getIntentsByLink(LinkEvent linkEvent) {
return getIntentsByPort(
linkEvent.getSrc().getDpid(),
linkEvent.getSrc().getNumber());
}
+ /**
+ * Retrieve all intents that use a particular port.
+ *
+ * @param dpid the switch's DPID
+ * @param port the switch's port
+ * @return a collection of PathIntents that use the port
+ */
public Collection<PathIntent> getIntentsByPort(Long dpid, Long port) {
HashMap<Long, HashSet<PathIntent>> portToIntents = intents.get(dpid);
if (portToIntents != null) {
@@ -80,6 +122,12 @@
return new HashSet<>();
}
+ /**
+ * Retrieve all intents that use a particular switch.
+ *
+ * @param dpid the switch's DPID
+ * @return a collection of PathIntents that use the switch
+ */
public Collection<PathIntent> getIntentsByDpid(Long dpid) {
HashSet<PathIntent> result = new HashSet<>();
HashMap<Long, HashSet<PathIntent>> portToIntents = intents.get(dpid);
@@ -92,10 +140,10 @@
}
/**
- * calculate available bandwidth of specified link.
+ * Calculate available bandwidth of specified link.
*
- * @param link
- * @return
+ * @param link the Link
+ * @return the available bandwidth
*/
public Double getAvailableBandwidth(Link link) {
if (link == null) {
diff --git a/src/main/java/net/onrc/onos/core/intent/ShortestPathIntent.java b/src/main/java/net/onrc/onos/core/intent/ShortestPathIntent.java
index 5c4e961..b77652f 100644
--- a/src/main/java/net/onrc/onos/core/intent/ShortestPathIntent.java
+++ b/src/main/java/net/onrc/onos/core/intent/ShortestPathIntent.java
@@ -6,7 +6,9 @@
import org.codehaus.jackson.map.annotate.JsonSerialize;
/**
- * @author Toshio Koide (t-koide@onlab.us)
+ * The ShortestPathIntent is a simple, "high-level" intent that
+ * provides shortest path connectivity between two end points in
+ * the network.
*/
@JsonSerialize(using = ShortestPathIntentSerializer.class)
public class ShortestPathIntent extends Intent {
@@ -44,17 +46,29 @@
* @param dstMac Destination Host MAC Address
*/
public ShortestPathIntent(String id,
- long srcSwitch, long srcPort, long srcMac,
- long dstSwitch, long dstPort, long dstMac) {
- //super(id);
+ long srcSwitch, long srcPort, long srcMac,
+ long dstSwitch, long dstPort, long dstMac) {
this(id, srcSwitch, srcPort, srcMac, EMPTYIPADDRESS, dstSwitch, dstPort, dstMac, EMPTYIPADDRESS);
}
+ /**
+ * Constructor.
+ *
+ * @param id Intent ID
+ * @param srcSwitch Source Switch DPID
+ * @param srcPort Source Port
+ * @param srcMac Source Host MAC Address
+ * @param srcIp Source IP Address
+ * @param dstSwitch Destination Switch DPID
+ * @param dstPort Destination Port
+ * @param dstMac Destination Host MAC Address
+ * @param dstIp Destination IP Address
+ */
// CHECKSTYLE:OFF suppress the warning about too many parameters
public ShortestPathIntent(String id,
- long srcSwitch, long srcPort, long srcMac, int srcIp,
- long dstSwitch, long dstPort, long dstMac, int dstIp ) {
- // CHECKSTYLE:ON
+ long srcSwitch, long srcPort, long srcMac, int srcIp,
+ long dstSwitch, long dstPort, long dstMac, int dstIp ) {
+ // CHECKSTYLE:ON
super(id);
this.srcSwitchDpid = srcSwitch;
this.srcPortNumber = srcPort;
@@ -120,10 +134,38 @@
return dstMacAddress;
}
- public void setPathIntent(PathIntent pathIntent) {
+ /**
+ * Get the source IP address.
+ *
+ * @return source IP address
+ */
+ public int getSrcIp() {
+ return srcIpAddress;
+ }
+
+ /**
+ * Get the destination IP address.
+ *
+ * @return destination IP address
+ */
+ public int getDstIp() {
+ return dstIpAddress;
+ }
+
+ /**
+ * Set the low-level PathIntent ID.
+ *
+ * @param pathIntent new PathIntent
+ */
+ public void setPathIntentId(PathIntent pathIntent) {
pathIntentId = pathIntent.getId();
}
+ /**
+ * Get the low-level PathIntent ID.
+ *
+ * @return the ID of the low-level PathIntent
+ */
public String getPathIntentId() {
return pathIntentId;
}
@@ -168,18 +210,32 @@
this.firstSwitchHardTimeout = firstSwitchHardTimeout;
}
+ /**
+ * Generates a hash code using the Intent ID.
+ *
+ * @return hashcode
+ */
@Override
public int hashCode() {
- // TODO: Is this the intended behavior?
- return (super.hashCode());
+ return super.hashCode();
}
+ /**
+ * Compares two intent object by type (class) and Intent ID.
+ *
+ * @param obj other Intent
+ * @return true if equal, false otherwise
+ */
@Override
public boolean equals(Object obj) {
- // TODO: Is this the intended behavior?
- return (super.equals(obj));
+ return super.equals(obj);
}
+ /**
+ * Returns a String representation of this Intent.
+ *
+ * @return comma separated list of Intent parameters
+ */
@Override
public String toString() {
return String.format("id:%s, state:%s, srcDpid:%s, srcPort:%d, " +
@@ -191,11 +247,4 @@
MACAddress.valueOf(dstMacAddress), Integer.toString(dstIpAddress));
}
- public int getSrcIp() {
- return srcIpAddress;
- }
-
- public int getDstIp() {
- return dstIpAddress;
- }
}
diff --git a/src/main/java/net/onrc/onos/core/intent/runtime/PathCalcRuntime.java b/src/main/java/net/onrc/onos/core/intent/runtime/PathCalcRuntime.java
index 8d7f6a6..e1b95e2 100644
--- a/src/main/java/net/onrc/onos/core/intent/runtime/PathCalcRuntime.java
+++ b/src/main/java/net/onrc/onos/core/intent/runtime/PathCalcRuntime.java
@@ -115,7 +115,7 @@
// create and add operation(s)
if (oldPathIntentId == null) {
// operation for new path-intent
- spIntent.setPathIntent(newPathIntent);
+ spIntent.setPathIntentId(newPathIntent);
pathIntentOpList.add(Operator.ADD, newPathIntent);
log.debug("new intent:{}", newPathIntent);
} else {
@@ -126,7 +126,7 @@
log.debug("skip intent:{}", newPathIntent);
} else {
// update existing path-intent (reroute)
- spIntent.setPathIntent(newPathIntent);
+ spIntent.setPathIntentId(newPathIntent);
pathIntentOpList.add(Operator.REMOVE, oldPathIntent);
pathIntentOpList.add(Operator.ADD, newPathIntent);
log.debug("update intent:{} -> {}", oldPathIntent, newPathIntent);