Added javadoc for all the helper classes in SDN-IP.
Also changed a couple of names to better reflect the usage or comply with
naming standards:
in IBgpRouteService.java: getBGPdRestIp -> getBgpdRestIp
in Prefix.java: MAX_BYTES -> ADDRESS_LENGTH
Change-Id: Id23b6bb077d79d671d21e2490ab410f322d7c166
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/Path.java b/src/main/java/net/onrc/onos/apps/bgproute/Path.java
index f96e0b0..c6f3539 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/Path.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/Path.java
@@ -4,13 +4,33 @@
import java.util.Collections;
import java.util.List;
-/*
- * A path is always assumed to be from all other interfaces (external-facing
- * switchports) to the destination interface.
+/**
+ * A {@link Path} represents paths within a network that forward traffic from
+ * ingress port to egress port. For every {@code next_hop} received in route
+ * updates from BGPd, we need to push forwarding paths from every other
+ * possible ingress port to the egress port connected to the {@code next_hop}.
+ * <p/>
+ * The {@link Path} object doesn't contain lists of hops along the path.
+ * Rather, it contains details about the egress {@link Interface} and
+ * {@code next_hop} IP address. Implicitly, it represents paths from every
+ * other ingress port to the {@Interface}.
+ * <p/>
+ * Once flow mods are pushed to realize the path in the network, the
+ * {@link Path} object will contain a list of pushed flow mods. These are used
+ * if the path ever needs to be deleted.
+ * <p/>
+ * On startup, paths are pushed to all configured BGP peers, on the assumption
+ * that they're likely to advertise routes to us. These paths are permanent
+ * because the list of peers can't currently change at runtime. If we receive
+ * a route for a {@code next_hop} which is not a peer, a temporary path will
+ * be installed. These paths are temporary because they are removed if all
+ * routes that use them are removed.
+ * <p/>
+ * Finally, the {@link Path} object counts references of prefixes that make use
+ * of the path. If the reference count drops to zero as prefixes are deleted,
+ * the path is no longer useful and will be removed from the network.
*/
-
public class Path {
-
private final Interface dstInterface;
private final InetAddress dstIpAddress;
private int numUsers; // initialized to 0
@@ -18,43 +38,94 @@
private List<PushedFlowMod> flowMods; // initialized to null
private boolean permanent; // initialized to false
+ /**
+ * Class constructor, taking the destination {@link Interface} and
+ * destination IP address for the path.
+ *
+ * @param dstInterface the destination interface
+ * @param dstIpAddress the destination IP address
+ */
public Path(Interface dstInterface, InetAddress dstIpAddress) {
this.dstInterface = dstInterface;
this.dstIpAddress = dstIpAddress;
}
+ /**
+ * Gets the destination {@link Interface} of the path.
+ *
+ * @return the destination interface
+ */
public Interface getDstInterface() {
return dstInterface;
}
+ /**
+ * Gets the destination IP address.
+ *
+ * @return the destination IP address
+ */
public InetAddress getDstIpAddress() {
return dstIpAddress;
}
+ /**
+ * Increments the count of prefixes that use this path.
+ */
public void incrementUsers() {
numUsers++;
}
+ /**
+ * Decrements the count of prefixes that use this path.
+ */
public void decrementUsers() {
numUsers--;
}
+ /**
+ * Gets the count of prefixes that use this path.
+ *
+ * @return the number of prefixes currently using the path
+ */
public int getUsers() {
return numUsers;
}
+ /**
+ * Gets the list of flow mods that were installed to realize this path in
+ * the network.
+ *
+ * @return the list of {@link PushedFlowMods}
+ */
public List<PushedFlowMod> getFlowMods() {
return Collections.unmodifiableList(flowMods);
}
+ /**
+ * Sets the list of flow mods that were installed to realize this path in
+ * the network.
+ *
+ * @param flowMods the list of {@link PushedFlowMods}
+ */
public void setFlowMods(List<PushedFlowMod> flowMods) {
this.flowMods = flowMods;
}
+ /**
+ * Signifies whether the path is permanent and shouldn't be deleted when
+ * the number of users drops to zero.
+ *
+ * @return true if the path is permanent, false if not
+ */
public boolean isPermanent() {
return permanent;
}
+ /**
+ * Set the permanent status of the path to true. Paths are not permanent
+ * by default when constructed, and this method can be used to designate
+ * them as permanent.
+ */
public void setPermanent() {
permanent = true;
}