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/BgpRoute.java b/src/main/java/net/onrc/onos/apps/bgproute/BgpRoute.java
index 78f7a61..8f42605 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/BgpRoute.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/BgpRoute.java
@@ -337,7 +337,7 @@
}
@Override
- public String getBGPdRestIp() {
+ public String getBgpdRestIp() {
return bgpdRestIp;
}
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/BgpRouteResource.java b/src/main/java/net/onrc/onos/apps/bgproute/BgpRouteResource.java
index 7580d51..9dd4b9b 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/BgpRouteResource.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/BgpRouteResource.java
@@ -61,7 +61,7 @@
// the dest here refers to router-id
// bgpdRestIp includes port number, such as 1.1.1.1:8080
- String bgpdRestIp = bgpRoute.getBGPdRestIp();
+ String bgpdRestIp = bgpRoute.getBgpdRestIp();
String url = "http://" + bgpdRestIp + "/wm/bgp/" + dest;
// Doesn't actually do anything with the response
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/BgpRouteResourceSynch.java b/src/main/java/net/onrc/onos/apps/bgproute/BgpRouteResourceSynch.java
index f83ad8b..6c46b71 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/BgpRouteResourceSynch.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/BgpRouteResourceSynch.java
@@ -33,7 +33,7 @@
String mask = (String) getRequestAttributes().get("mask");
String nexthop = (String) getRequestAttributes().get("nexthop");
- String bgpdRestIp = bgpRoute.getBGPdRestIp();
+ String bgpdRestIp = bgpRoute.getBgpdRestIp();
// bgpdRestIp includes port number, e.g. 1.1.1.1:8080
RestClient.post("http://" + bgpdRestIp + "/wm/bgp/" + routerId + "/" + prefix + "/"
@@ -65,7 +65,7 @@
StringBuilder reply = new StringBuilder();
- String bgpdRestIp = bgpRoute.getBGPdRestIp();
+ String bgpdRestIp = bgpRoute.getBgpdRestIp();
RestClient.delete("http://" + bgpdRestIp + "/wm/bgp/" + routerId + "/" + prefix + "/"
+ mask + "/" + nextHop);
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/Configuration.java b/src/main/java/net/onrc/onos/apps/bgproute/Configuration.java
index 314324d..ce97f50 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/Configuration.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/Configuration.java
@@ -8,6 +8,10 @@
import org.codehaus.jackson.annotate.JsonProperty;
import org.openflow.util.HexString;
+/**
+ * Contains the configuration data for SDN-IP that has been read from a
+ * JSON-formatted configuration file.
+ */
public class Configuration {
private long bgpdAttachmentDpid;
private short bgpdAttachmentPort;
@@ -17,68 +21,146 @@
private List<Interface> interfaces;
private List<BgpPeer> peers;
+ /**
+ * Default constructor.
+ */
public Configuration() {
// TODO Auto-generated constructor stub
}
+ /**
+ * Gets the switch that BGPd is attached to.
+ *
+ * @return the dpid of BGPd's attachment point
+ */
public long getBgpdAttachmentDpid() {
return bgpdAttachmentDpid;
}
+ /**
+ * Sets the switch that BGPd is attached to.
+ *
+ * @param bgpdAttachmentDpid the dpid of BGPd's attachment point
+ */
@JsonProperty("bgpdAttachmentDpid")
public void setBgpdAttachmentDpid(String bgpdAttachmentDpid) {
this.bgpdAttachmentDpid = HexString.toLong(bgpdAttachmentDpid);
}
+ /**
+ * Gets the port that BGPd is attached to.
+ *
+ * @return the port number on the switch where BGPd is attached
+ */
public short getBgpdAttachmentPort() {
return bgpdAttachmentPort;
}
+ /**
+ * Sets the port that BGPd is attached to.
+ *
+ * @param bgpdAttachmentPort the port number on the switch where BGPd is
+ * attached
+ */
@JsonProperty("bgpdAttachmentPort")
public void setBgpdAttachmentPort(short bgpdAttachmentPort) {
this.bgpdAttachmentPort = bgpdAttachmentPort;
}
+ /**
+ * Gets the MAC address of the BGPd host interface.
+ *
+ * @return the MAC address
+ */
public MACAddress getBgpdMacAddress() {
return bgpdMacAddress;
}
+ /**
+ * Sets the MAC address of the BGPd host interface.
+ *
+ * @param strMacAddress the MAC address
+ */
@JsonProperty("bgpdMacAddress")
public void setBgpdMacAddress(String strMacAddress) {
this.bgpdMacAddress = MACAddress.valueOf(strMacAddress);
}
+ /**
+ * Gets a list of the DPIDs of all switches in the system. The DPIDs are
+ * in String format represented in hexadecimal.
+ *
+ * @return the list of DPIDs
+ */
public List<String> getSwitches() {
return Collections.unmodifiableList(switches);
}
- @JsonProperty("vlan")
- public void setVlan(short vlan) {
- this.vlan = vlan;
- }
-
- public short getVlan() {
- return vlan;
- }
-
+ /**
+ * Sets a list of DPIDs of all switches in the system.
+ *
+ * @param switches the list of DPIDs
+ */
@JsonProperty("switches")
public void setSwitches(List<String> switches) {
this.switches = switches;
}
+ /**
+ * Gets the VLAN number of the VLAN the system is running in, if any.
+ * 0 means we are not running in a VLAN.
+ *
+ * @return the VLAN number if we are running in a VLAN, otherwise 0
+ */
+ public short getVlan() {
+ return vlan;
+ }
+
+ /**
+ * Sets the VLAN number of the VLAN the system is running in.
+ *
+ * @param vlan the VLAN number
+ */
+ @JsonProperty("vlan")
+ public void setVlan(short vlan) {
+ this.vlan = vlan;
+ }
+
+ /**
+ * Gets a list of interfaces in the system, represented by
+ * {@link Interface} objects.
+ *
+ * @return the list of interfaces
+ */
public List<Interface> getInterfaces() {
return Collections.unmodifiableList(interfaces);
}
+ /**
+ * Sets a list of interfaces in the system.
+ *
+ * @param interfaces the list of interfaces
+ */
@JsonProperty("interfaces")
public void setInterfaces(List<Interface> interfaces) {
this.interfaces = interfaces;
}
+ /**
+ * Gets a list of BGP peers we are configured to peer with. Peers are
+ * represented by {@link BgpPeer} objects.
+ *
+ * @return the list of BGP peers
+ */
public List<BgpPeer> getPeers() {
return Collections.unmodifiableList(peers);
}
+ /**
+ * Sets a list of BGP peers we are configured to peer with.
+ *
+ * @param peers the list of BGP peers
+ */
@JsonProperty("bgpPeers")
public void setPeers(List<BgpPeer> peers) {
this.peers = peers;
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/IBgpRouteService.java b/src/main/java/net/onrc/onos/apps/bgproute/IBgpRouteService.java
index 04223eb..fa2d3fc 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/IBgpRouteService.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/IBgpRouteService.java
@@ -2,27 +2,47 @@
import net.floodlightcontroller.core.module.IFloodlightService;
+/**
+ * The API exported by the main SDN-IP class. This is the interface between the
+ * REST handlers and the SDN-IP module.
+ */
public interface IBgpRouteService extends IFloodlightService {
- //public RibEntry lookupRib(byte[] dest);
-
- //public Ptree getPtree();
+ /**
+ * Gets a reference to SDN-IP's PATRICIA tree which stores the route table.
+ *
+ * XXX This is a poor API because it exposes internal state of SDN-IP.
+ *
+ * @return the PATRICIA tree.
+ */
public IPatriciaTrie<RibEntry> getPtree();
- public String getBGPdRestIp();
+ /**
+ * Gets the IP address of REST server on the BGPd side. This is used to
+ * communicate with BGPd.
+ *
+ * @return the IP address as a String
+ */
+ public String getBgpdRestIp();
+ /**
+ * Gets the router ID, which is sent to BGPd to identify the route table
+ * we're interested in.
+ *
+ * @return the router ID as a String
+ */
public String getRouterId();
+ /**
+ * Clears SDN-IP's route table.
+ */
public void clearPtree();
/**
* Pass a RIB update to the {@link IBgpRouteService}.
*
- * @param update
+ * @param update a {@link RibUpdate} object containing details of the
+ * update
*/
public void newRibUpdate(RibUpdate update);
-
- //TODO This functionality should be provided by some sort of Ptree listener framework
- //public void prefixAdded(PtreeNode node);
- //public void prefixDeleted(PtreeNode node);
}
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/IPatriciaTrie.java b/src/main/java/net/onrc/onos/apps/bgproute/IPatriciaTrie.java
index bd4508a..32a7d2e 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/IPatriciaTrie.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/IPatriciaTrie.java
@@ -2,20 +2,99 @@
import java.util.Iterator;
+/**
+ * A PATRICIA tree is data structure for storing data where entries aggregate
+ * based on shared prefixes. They provide lookups in O(k) where k is the
+ * maximum length of the strings in the tree. They work well for storing IP
+ * addresses.
+ * <p/>
+ * SDN-IP uses a patricia tree to store routes learnt from BGPd. BGPd sends
+ * route updates in the form:
+ * {@code <prefix, next_hop>},
+ * e.g. {@code <192.168.1.0/24, 10.0.0.1>}
+ * <p/>
+ * These updates are stored in the patricia trie, which acts as a map from
+ * {@code prefix} to {@code next_hop}. {@code next_hop} values can be looked up
+ * by prefix.
+ *
+ * @param <V> The class of the data to stored in the patricia tree
+ *
+ * @see <a href="http://en.wikipedia.org/wiki/Patricia_trie">Patricia tree</a>
+ */
public interface IPatriciaTrie<V> {
+ /**
+ * Puts a new mapping into the patricia tree.
+ *
+ * @param prefix the Prefix which is the key for this entry
+ * @param value the value that maps to the Prefix
+ * @return the old value that was mapped to the Prefix, or null if there
+ * was no such mapping
+ */
public V put(Prefix prefix, V value);
+ /**
+ * Searches the tree for a prefix that exactly matches the argument. If an
+ * exact match for the prefix is found in the tree, the value it maps to is
+ * returned. Otherwise, null is returned.
+ *
+ * @param prefix the prefix to look up in the tree
+ * @return the value if the prefix was found, otherwise null
+ */
public V lookup(Prefix prefix);
+ /**
+ * Searches the tree for the closest containing prefix of the supplied
+ * argument. If an exact match is found, that will be returned. Otherwise,
+ * the value of the most specific prefix that contains the argument prefix
+ * will be returned. If no such prefix is found, null is returned.
+ *
+ * @param prefix the prefix to find the closest containing match for in the
+ * tree
+ * @return the value of the match if one was found, otherwise null
+ */
public V match(Prefix prefix);
+ /**
+ * Removes a prefix to value mapping from the tree. The prefix argument is
+ * first looked up in the same way as the {@link #lookup(Prefix)} method.
+ * If an exact match to the prefix is found in the tree, its value is
+ * is checked to see if it matches the supplied argument value. The prefix
+ * and value will be removed only if both the prefix and value arguments
+ * match a mapping in the tree.
+ *
+ * @param prefix the prefix to remove from the tree
+ * @param value the value that must be mapped to the prefix for it to be
+ * removed
+ * @return true if a mapping was removed, otherwise false
+ */
public boolean remove(Prefix prefix, V value);
+ /**
+ * Gets an iterator over all mappings in the tree.
+ *
+ * @return an iterator that will iterate over all entries in the tree
+ */
public Iterator<Entry<V>> iterator();
+ /**
+ * Represents an entry in the patricia tree. The {@code Entry} is a mapping
+ * from {@link Prefix} to a {@link V} value object.
+ *
+ * @param <V> the class of objects stored in the tree
+ */
interface Entry<V> {
+ /**
+ * Gets the {@link Prefix} object for this entry.
+ *
+ * @return the prefix for this entry
+ */
public Prefix getPrefix();
+ /**
+ * Gets the value of this entry.
+ *
+ * @return the value object of this entry
+ */
public V getValue();
}
}
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/Interface.java b/src/main/java/net/onrc/onos/apps/bgproute/Interface.java
index 0339401..4316bc0 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/Interface.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/Interface.java
@@ -12,6 +12,21 @@
import com.google.common.net.InetAddresses;
+/**
+ * Represents an interface, which is an external-facing switch port that
+ * connects to another network.
+ *
+ * SDN-IP treats external-facing ports similarly to router ports. Logically, it
+ * assigns an IP address to these ports which is used for communication with
+ * the BGP peers, for example, the BGP peering session. The other peer will be
+ * configured to peer with the IP address (logically) assigned to the
+ * interface. The logical {@code Interface} construct maps on to a physical port in the
+ * data plane, which of course has no notion of IP addresses.
+ *
+ * Each interface has a name, which is a unique identifying String that is used
+ * to reference this interface in the configuration (for example, to map
+ * {@link BgpPeers} to {@code Interfaces}.
+ */
public class Interface {
private final String name;
private final long dpid;
@@ -19,6 +34,15 @@
private final InetAddress ipAddress;
private final int prefixLength;
+ /**
+ * Class constructor used by the JSON library to create an object.
+ *
+ * @param name the name of the interface
+ * @param dpid the dpid of the switch
+ * @param port the port on the switch
+ * @param ipAddress the IP address logically assigned to the interface
+ * @param prefixLength the length of the network prefix of the IP address
+ */
@JsonCreator
public Interface(@JsonProperty("name") String name,
@JsonProperty("dpid") String dpid,
@@ -32,28 +56,58 @@
this.prefixLength = prefixLength;
}
+ /**
+ * Gets the name of the interface.
+ *
+ * @return the name of the interface
+ */
public String getName() {
return name;
}
+ /**
+ * Gets the {@link SwitchPort} that this interface maps to.
+ *
+ * @return the switch port
+ */
public SwitchPort getSwitchPort() {
//TODO SwitchPort, Dpid and Port are mutable, but they could probably
//be made immutable which would prevent the need to copy
return new SwitchPort(new Dpid(dpid), new Port(port));
}
+ /**
+ * Gets the DPID of the switch.
+ *
+ * @return the DPID of the switch
+ */
public long getDpid() {
return dpid;
}
+ /**
+ * Gets the port number this interface maps to.
+ *
+ * @return the port number
+ */
public short getPort() {
return port;
}
+ /**
+ * Gets the IP address which is logically assigned to the switch port.
+ *
+ * @return the IP address
+ */
public InetAddress getIpAddress() {
return ipAddress;
}
+ /**
+ * Gets the prefix length of the interface's IP address.
+ *
+ * @return the prefix length
+ */
public int getPrefixLength() {
return prefixLength;
}
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;
}
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/PatriciaTrie.java b/src/main/java/net/onrc/onos/apps/bgproute/PatriciaTrie.java
index 54f8129..0c64502 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/PatriciaTrie.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/PatriciaTrie.java
@@ -3,6 +3,12 @@
import java.util.Iterator;
import java.util.NoSuchElementException;
+/**
+ * Implements a patricia tree. See {@link IPatriciaTrie} for a description of
+ * how the tree works and its usage.
+ *
+ * @param <V> the type of objects that will be stored in the tree
+ */
public class PatriciaTrie<V> implements IPatriciaTrie<V> {
private final byte[] maskBits = {(byte) 0x00, (byte) 0x80, (byte) 0xc0, (byte) 0xe0, (byte) 0xf0,
(byte) 0xf8, (byte) 0xfc, (byte) 0xfe, (byte) 0xff};
@@ -11,6 +17,14 @@
private Node top;
+ /**
+ * Class constructor which takes the maximum length of strings that can be
+ * stored in the tree. This is used as a sanity check to prevent
+ * excessively long strings from being added, as this could slow down
+ * lookups.
+ *
+ * @param maxPrefixLength the maximum length of prefixes
+ */
public PatriciaTrie(int maxPrefixLength) {
this.maxPrefixLength = maxPrefixLength;
}
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/Prefix.java b/src/main/java/net/onrc/onos/apps/bgproute/Prefix.java
index 49bbcac..834ea29 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/Prefix.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/Prefix.java
@@ -6,18 +6,47 @@
import com.google.common.net.InetAddresses;
+/**
+ * Represents an IP prefix.
+ * <p/>
+ * It is made up of an IP address and a number of significant bits in the
+ * prefix (i.e. the size of the network part of the address).
+ * E.g. {@code 192.168.0.0/16}.
+ * <p/>
+ * Currently only IPv4 is supported, so a prefix length can be up to 32 bits.
+ */
public class Prefix {
- private static final int MAX_BYTES = 4;
+ /**
+ * The length of addresses this class can represent prefixes of, in bytes.
+ */
+ public static final int ADDRESS_LENGTH = 4;
private final int prefixLength;
private final byte[] address;
- //For verifying the arguments and pretty printing
+ // For verifying the arguments and pretty printing
private final InetAddress inetAddress;
+ /**
+ * Class constructor, taking an byte array representing and IP address and
+ * a prefix length.
+ * <p/>
+ * The valid values for addr and prefixLength are bounded by
+ * {@link #ADDRESS_LENGTH}.
+ * <p/>
+ * A valid addr array satisfies
+ * {@code addr.length == }{@value #ADDRESS_LENGTH}.
+ * <p/>
+ * A valid prefixLength satisfies
+ * {@code (prefixLength > 0 && prefixLength <=} {@link Byte#SIZE}
+ * {@code * }{@value #ADDRESS_LENGTH}{@code )}.
+ *
+ * @param addr a byte array representing the address
+ * @param prefixLength length of the prefix of the specified address
+ */
public Prefix(byte[] addr, int prefixLength) {
- if (addr == null || addr.length != MAX_BYTES ||
- prefixLength < 0 || prefixLength > MAX_BYTES * Byte.SIZE) {
+ if (addr == null || addr.length != ADDRESS_LENGTH ||
+ prefixLength < 0 || prefixLength > ADDRESS_LENGTH * Byte.SIZE) {
throw new IllegalArgumentException();
}
@@ -31,12 +60,19 @@
}
}
+ /**
+ * Class constructor, taking an address in String format and a prefix
+ * length. The address must be in dot-notation form (e.g. {@code 0.0.0.0}).
+ *
+ * @param strAddress a String representing the address
+ * @param prefixLength length of the prefix of the specified address
+ */
public Prefix(String strAddress, int prefixLength) {
byte[] addr = null;
addr = InetAddresses.forString(strAddress).getAddress();
- if (addr == null || addr.length != MAX_BYTES ||
- prefixLength < 0 || prefixLength > MAX_BYTES * Byte.SIZE) {
+ if (addr == null || addr.length != ADDRESS_LENGTH ||
+ prefixLength < 0 || prefixLength > ADDRESS_LENGTH * Byte.SIZE) {
throw new IllegalArgumentException();
}
@@ -55,7 +91,7 @@
byte[] result = new byte[addressValue.length];
if (prefixLengthValue == 0) {
- for (int i = 0; i < MAX_BYTES; i++) {
+ for (int i = 0; i < ADDRESS_LENGTH; i++) {
result[i] = 0;
}
@@ -66,7 +102,7 @@
//Set all bytes after the end of the prefix to 0
int lastByteIndex = (prefixLengthValue - 1) / Byte.SIZE;
- for (int i = lastByteIndex; i < MAX_BYTES; i++) {
+ for (int i = lastByteIndex; i < ADDRESS_LENGTH; i++) {
result[i] = 0;
}
@@ -85,10 +121,20 @@
return result;
}
+ /**
+ * Gets the length of the prefix of the address.
+ *
+ * @return the prefix length
+ */
public int getPrefixLength() {
return prefixLength;
}
+ /**
+ * Gets the address.
+ *
+ * @return the address as a byte array
+ */
public byte[] getAddress() {
return Arrays.copyOf(address, address.length);
}
@@ -118,6 +164,11 @@
return inetAddress.getHostAddress() + "/" + prefixLength;
}
+ /**
+ * Print the prefix to a String showing the bits of the address.
+ *
+ * @return the bit-string of the prefix
+ */
public String printAsBits() {
StringBuilder result = new StringBuilder();
for (int i = 0; i < address.length; i++) {
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/PushedFlowMod.java b/src/main/java/net/onrc/onos/apps/bgproute/PushedFlowMod.java
index eaee857..137c22f 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/PushedFlowMod.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/PushedFlowMod.java
@@ -2,16 +2,21 @@
import org.openflow.protocol.OFFlowMod;
+// TODO This functionality should be handled by ONOS's flow layer in future.
/**
- * Wraps up a DPID and a OFFlowMod so we know how to delete
- * the flow if we have to.
- * <p/>
- * TODO This functionality should be handled by ONOS's flow layer in future.
+ * Collects together the DPID and OFFlowMod of a pushed flow mod. This
+ * information is used if the flow mod has to be deleted in the future.
*/
public class PushedFlowMod {
private final long dpid;
private OFFlowMod flowMod;
+ /**
+ * Class constructor, taking a DPID and a flow mod.
+ *
+ * @param dpid the DPID of the switch the flow mod was pushed to
+ * @param flowMod the OFFlowMod that was pushed to the switch
+ */
public PushedFlowMod(long dpid, OFFlowMod flowMod) {
this.dpid = dpid;
try {
@@ -21,10 +26,20 @@
}
}
+ /**
+ * Gets the DPID of the switch the flow mod was pushed to.
+ *
+ * @return the DPID of the switch
+ */
public long getDpid() {
return dpid;
}
+ /**
+ * Gets the OFFlowMod that was pushed to the switch.
+ *
+ * @return the OFFlowMod object
+ */
public OFFlowMod getFlowMod() {
return flowMod;
}
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/RestClient.java b/src/main/java/net/onrc/onos/apps/bgproute/RestClient.java
index f1fc370..c7ff195 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/RestClient.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/RestClient.java
@@ -12,18 +12,30 @@
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * A simple HTTP client. It is used to make REST calls to the BGPd process.
+ */
public final class RestClient {
private static final Logger log = LoggerFactory.getLogger(RestClient.class);
+ /**
+ * Default constructor.
+ */
private RestClient() {
// Private constructor to prevent instantiation
}
- public static String get(String str) {
+ /**
+ * Issues a HTTP GET request to the specified URL.
+ *
+ * @param strUrl the URL to make the request to
+ * @return a String containing any data returned by the server
+ */
+ public static String get(String strUrl) {
StringBuilder response = new StringBuilder();
try {
- URL url = new URL(str);
+ URL url = new URL(strUrl);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setConnectTimeout(2 * 1000); // 2 seconds
conn.setRequestMethod("GET");
@@ -36,7 +48,7 @@
}
if (!conn.getContentType().equals("application/json")) {
- log.warn("The content received from {} is not json", str);
+ log.warn("The content received from {} is not json", strUrl);
}
BufferedReader br = new BufferedReader(new InputStreamReader(
@@ -60,10 +72,15 @@
return response.toString();
}
- public static void post(String str) {
+ /**
+ * Issues a HTTP POST request to the specified URL.
+ *
+ * @param strUrl the URL to make the request to
+ */
+ public static void post(String strUrl) {
try {
- URL url = new URL(str);
+ URL url = new URL(strUrl);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
@@ -84,10 +101,15 @@
}
}
- public static void delete(String str) {
+ /**
+ * Issues a HTTP DELETE request to the specified URL.
+ *
+ * @param strUrl the URL to make the request to
+ */
+ public static void delete(String strUrl) {
try {
- URL url = new URL(str);
+ URL url = new URL(strUrl);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("DELETE");
conn.setRequestProperty("Accept", "application/json");
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/RibEntry.java b/src/main/java/net/onrc/onos/apps/bgproute/RibEntry.java
index ae16c8f..7ad1d3d 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/RibEntry.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/RibEntry.java
@@ -4,6 +4,14 @@
import com.google.common.net.InetAddresses;
+/**
+ * Represents an entry in the Routing Information Base (RIB) of a router.
+ * <p/>
+ * A route update from the BGP daemon contains a prefix and a RibEntry
+ * containing the next hop for the route. The RibEntry also contains
+ * information related to the synchronization mechanism between BGPd and
+ * SDN-IP, such as sequence numbers.
+ */
public class RibEntry {
private final InetAddress routerId;
private final InetAddress nextHop;
@@ -24,6 +32,14 @@
*/
private static final long NULL_TIME = -1;
+ /**
+ * Class constructor, taking the router ID and next hop IP address as
+ * {@link InetAddress} objects.
+ *
+ * @param routerId the router ID which identifies the route table in BGPd
+ * that this update came from
+ * @param nextHop next hop IP address for this route entry
+ */
public RibEntry(InetAddress routerId, InetAddress nextHop) {
this.routerId = routerId;
this.nextHop = nextHop;
@@ -31,6 +47,15 @@
sysUpTime = NULL_TIME;
}
+ /**
+ * Class constructor, taking the router ID and next hop IP address as
+ * Strings. The addresses must be in dot-notation form
+ * (e.g. {@code 0.0.0.0}).
+ *
+ * @param routerId the router ID which identifies the route table in BGPd
+ * that this update came from
+ * @param nextHop next hop IP address for this route entry
+ */
public RibEntry(String routerId, String nextHop) {
this.routerId = InetAddresses.forString(routerId);
this.nextHop = InetAddresses.forString(nextHop);
@@ -38,22 +63,49 @@
sysUpTime = NULL_TIME;
}
- public RibEntry(String routerId, String nextHop, long sysUpTime
- , long sequenceNum) {
+ /**
+ * Class constructor, taking the router ID and next hop IP address as
+ * Strings, as well as the sequence numbers of the updates. Sequence
+ * numbers are used to establish ordering of updates from BGPd. The
+ * addresses must be in dot-notation form (e.g. {@code 0.0.0.0}).
+ *
+ * @param routerId the router ID which identifies the route table in BGPd
+ * that this update came from
+ * @param nextHop next hop IP address for this route entry
+ * @param sysUpTime the sysuptime parameter on the update from BGPd
+ * @param sequenceNum the sequencenum parameter on the update from BGPd
+ */
+ public RibEntry(String routerId, String nextHop, long sysUpTime,
+ long sequenceNum) {
this.routerId = InetAddresses.forString(routerId);
this.nextHop = InetAddresses.forString(nextHop);
this.sequenceNum = sequenceNum;
this.sysUpTime = sysUpTime;
}
+ /**
+ * Gets the next hop IP address of this route entry.
+ *
+ * @return the next hop IP address
+ */
public InetAddress getNextHop() {
return nextHop;
}
+ /**
+ * Gets the sysuptime parameter sent with the update from BGPd.
+ *
+ * @return the sysuptime parameter
+ */
public long getSysUpTime() {
return sysUpTime;
}
+ /**
+ * Gets the sequencenum parameter sent with the update from BGPd.
+ *
+ * @return the sequencenum parameter
+ */
public long getSequenceNum() {
return sequenceNum;
}
diff --git a/src/main/java/net/onrc/onos/apps/bgproute/RibUpdate.java b/src/main/java/net/onrc/onos/apps/bgproute/RibUpdate.java
index 58ebdf1..3f74a08 100644
--- a/src/main/java/net/onrc/onos/apps/bgproute/RibUpdate.java
+++ b/src/main/java/net/onrc/onos/apps/bgproute/RibUpdate.java
@@ -1,29 +1,72 @@
package net.onrc.onos.apps.bgproute;
+/**
+ * Represents a route update received from BGPd. An update has an operation
+ * describing whether the update is adding a route or revoking a route. It also
+ * contains the route prefix, and {@link RibEntry} containing next hop and
+ * sequence number information for the update.
+ */
public class RibUpdate {
private final Operation operation;
private final Prefix prefix;
private final RibEntry ribEntry;
+ /**
+ * Updates can either add new routes or revoke old routes. The
+ * {@link Operation} enum descibes which action is being taken.
+ */
public enum Operation {
+ /**
+ * Represents a route update. ONOS should update its route information
+ * for this prefix to the new information provided in this
+ * {@link RibUpdate}. This means either add a new prefix, or update
+ * the information for an existing prefix.
+ */
UPDATE,
+ /**
+ * Represents a route delete. ONOS should remove this prefix and route
+ * information from its route table.
+ */
DELETE
}
+ /**
+ * Class constructor, taking the operation of the update, the route prefix
+ * and the {@link RibEntry} describing the update.
+ *
+ * @param operation the operation of the update
+ * @param prefix the route prefix
+ * @param ribEntry the update entry
+ */
public RibUpdate(Operation operation, Prefix prefix, RibEntry ribEntry) {
this.operation = operation;
this.prefix = prefix;
this.ribEntry = ribEntry;
}
+ /**
+ * Gets the operation of the update.
+ *
+ * @return the operation
+ */
public Operation getOperation() {
return operation;
}
+ /**
+ * Gets the route prefix of the update.
+ *
+ * @return the prefix
+ */
public Prefix getPrefix() {
return prefix;
}
+ /**
+ * Gets the {@link RibEntry} of the update.
+ *
+ * @return the entry
+ */
public RibEntry getRibEntry() {
return ribEntry;
}