Fix/update Javadoc comments for the topology event classes:
HostEvent, LinkEvent, MastershipEvent, PortEvent, SwitchEvent
No functional changes.
Change-Id: I31cab2f01b79b09f84726e975b72f1ccab17ddbc
diff --git a/src/main/java/net/onrc/onos/core/topology/HostEvent.java b/src/main/java/net/onrc/onos/core/topology/HostEvent.java
index 86d1751..4b7de52 100644
--- a/src/main/java/net/onrc/onos/core/topology/HostEvent.java
+++ b/src/main/java/net/onrc/onos/core/topology/HostEvent.java
@@ -45,7 +45,7 @@
}
/**
- * Creates the Host object.
+ * Constructor for a given host MAC address.
*
* @param mac the MAC address to identify the host
*/
@@ -55,9 +55,11 @@
}
/**
- * Creates an unfrozen copy of given Object.
+ * Copy constructor.
+ * <p>
+ * Creates an unfrozen copy of the given HostEvent object.
*
- * @param original to make copy of.
+ * @param original the object to make copy of
*/
public HostEvent(HostEvent original) {
super(original);
@@ -66,15 +68,29 @@
this.lastSeenTime = original.lastSeenTime;
}
-
+ /**
+ * Gets the host MAC address.
+ *
+ * @return the MAC address.
+ */
public MACAddress getMac() {
return mac;
}
+ /**
+ * Gets the switch attachment points.
+ *
+ * @return the switch attachment points
+ */
public List<SwitchPort> getAttachmentPoints() {
return Collections.unmodifiableList(attachmentPoints);
}
+ /**
+ * Sets the switch attachment points.
+ *
+ * @param attachmentPoints the switch attachment points to set
+ */
public void setAttachmentPoints(List<SwitchPort> attachmentPoints) {
if (isFrozen()) {
throw new IllegalStateException("Tried to modify frozen instance: " + this);
@@ -82,6 +98,11 @@
this.attachmentPoints = attachmentPoints;
}
+ /**
+ * Adds a switch attachment point.
+ *
+ * @param attachmentPoint the switch attachment point to add
+ */
public void addAttachmentPoint(SwitchPort attachmentPoint) {
if (isFrozen()) {
throw new IllegalStateException("Tried to modify frozen instance: " + this);
@@ -90,6 +111,11 @@
this.attachmentPoints.add(0, attachmentPoint);
}
+ /**
+ * Removes a switch attachment point.
+ *
+ * @param attachmentPoint the switch attachment point to remove
+ */
public boolean removeAttachmentPoint(SwitchPort attachmentPoint) {
if (isFrozen()) {
throw new IllegalStateException("Tried to modify frozen instance: " + this);
@@ -97,11 +123,21 @@
return this.attachmentPoints.remove(attachmentPoint);
}
-
+ /**
+ * Gets the host last seen time in milliseconds since the epoch.
+ *
+ * @return the host last seen time in milliseconds since the epoch
+ */
public long getLastSeenTime() {
return lastSeenTime;
}
+ /**
+ * Sets the host last seen time in milliseconds since the epoch.
+ *
+ * @param lastSeenTime the host last seen time in milliseconds since the
+ * epoch
+ */
public void setLastSeenTime(long lastSeenTime) {
if (isFrozen()) {
throw new IllegalStateException("Tried to modify frozen instance: " + this);
@@ -109,7 +145,15 @@
this.lastSeenTime = lastSeenTime;
}
- // Assuming mac is unique cluster-wide
+ /**
+ * Computes the host ID for a given host MAC address.
+ * <p>
+ * TODO: This method should be replaced with a method that uses
+ * MACAddress as an argument instead of a byte array.
+ *
+ * @param mac the host MAC address to use
+ * @return the host ID as a ByteBuffer
+ */
public static ByteBuffer getHostID(final byte[] mac) {
return (ByteBuffer) ByteBuffer.allocate(2 + mac.length)
.putChar('H').put(mac).flip();
diff --git a/src/main/java/net/onrc/onos/core/topology/LinkEvent.java b/src/main/java/net/onrc/onos/core/topology/LinkEvent.java
index bc5aa93..4296fee 100644
--- a/src/main/java/net/onrc/onos/core/topology/LinkEvent.java
+++ b/src/main/java/net/onrc/onos/core/topology/LinkEvent.java
@@ -22,6 +22,7 @@
@JsonSerialize(using = LinkEventSerializer.class)
public class LinkEvent extends TopologyElement<LinkEvent> {
+ public static final int LINKID_BYTES = 2 + PortEvent.PORTID_BYTES * 2;
private final LinkTuple id;
// TODO add LastSeenTime, Capacity if appropriate
@@ -37,62 +38,70 @@
}
/**
- * Creates the Link object.
+ * Constructor for given LinkTuple.
*
- * @param id link tuple to identify this link
+ * @param id the link tuple to identify the link
*/
public LinkEvent(LinkTuple id) {
this.id = checkNotNull(id);
}
/**
- * Creates the Link object.
+ * Constructor for given source and destination switch ports.
*
- * @param src source SwitchPort
- * @param dst destination SwitchPort
+ * @param src the source SwitchPort to use
+ * @param dst the destination SwitchPort to use
*/
public LinkEvent(SwitchPort src, SwitchPort dst) {
this(new LinkTuple(src, dst));
}
/**
- * Creates an unfrozen copy of given Object.
+ * Constructor for a given Link object.
+ * <p>
+ * TODO: This constructor should probably be removed.
*
- * @param original to make copy of.
+ * @param link the Link object to use.
*/
- public LinkEvent(LinkEvent original) {
- super(original);
- this.id = original.id;
- }
-
- // TODO probably want to remove this
public LinkEvent(Link link) {
this(link.getLinkTuple());
// FIXME losing attributes here
}
/**
- * Gets a {@link LinkTuple} that identifies this link.
+ * Copy constructor.
+ * <p>
+ * Creates an unfrozen copy of the given LinkEvent object.
*
- * @return a LinkTuple representing the Port
+ * @param original the object ot make copy of
+ */
+ public LinkEvent(LinkEvent original) {
+ super(original);
+ this.id = original.id;
+ }
+
+ /**
+ * Gets the LinkTuple that identifies this link.
+ *
+ * @return the LinkTuple identifying this link
*/
public LinkTuple getLinkTuple() {
return id;
}
/**
- * Gets the source SwitchPort.
+ * Gets the link source SwitchPort.
*
- * @return source SwitchPort.
+ * @return the link source SwitchPort
*/
public SwitchPort getSrc() {
return getLinkTuple().getSrc();
}
/**
- * Gets the destination SwitchPort.
+ * Gets the link destination SwitchPort.
*
- * @return destination SwitchPort.
+ * @return the link destination SwitchPort
*/
public SwitchPort getDst() {
return getLinkTuple().getDst();
@@ -100,9 +109,10 @@
/**
* Gets the link capacity.
+ * <p>
* TODO: What is the unit?
*
- * @return capacity
+ * @return the link capacity
*/
public Double getCapacity() {
return capacity;
@@ -110,9 +120,10 @@
/**
* Sets the link capacity.
+ * <p>
* TODO: What is the unit?
*
- * @param capacity capacity
+ * @param capacity the link capacity to set
*/
void setCapacity(Double capacity) {
if (isFrozen()) {
@@ -122,14 +133,35 @@
this.capacity = capacity;
}
- public static final int LINKID_BYTES = 2 + PortEvent.PORTID_BYTES * 2;
-
+ /**
+ * Computes the link ID for given source and destination switch DPID and
+ * port numbers.
+ *
+ * @param srcDpid the source switch DPID to use
+ * @param srcPortNo the source port number to use
+ * @param dstDpid the destination switch DPID to use
+ * @param dstPortNo the destination port number to use
+ * @return the link ID as a ByteBuffer
+ */
public static ByteBuffer getLinkID(Dpid srcDpid, PortNumber srcPortNo,
Dpid dstDpid, PortNumber dstPortNo) {
return getLinkID(srcDpid.value(), srcPortNo.value(),
dstDpid.value(), dstPortNo.value());
}
+ /**
+ * Computes the link ID for given source and destination switch DPID and
+ * port numbers.
+ * <p>
+ * TODO: This method should be removed and replaced with the corresponding
+ * getLinkID(Dpid, PortNumber, Dpid, PortNumber) method.
+ *
+ * @param srcDpid the source switch DPID to use
+ * @param srcPortNo the source port number to use
+ * @param dstDpid the destination switch DPID to use
+ * @param dstPortNo the destination port number to use
+ * @return the link ID as a ByteBuffer
+ */
public static ByteBuffer getLinkID(Long srcDpid, Long srcPortNo,
Long dstDpid, Long dstPortNo) {
return (ByteBuffer) ByteBuffer.allocate(LinkEvent.LINKID_BYTES)
diff --git a/src/main/java/net/onrc/onos/core/topology/MastershipEvent.java b/src/main/java/net/onrc/onos/core/topology/MastershipEvent.java
index 1d54a52..45578db 100644
--- a/src/main/java/net/onrc/onos/core/topology/MastershipEvent.java
+++ b/src/main/java/net/onrc/onos/core/topology/MastershipEvent.java
@@ -21,7 +21,6 @@
*/
@JsonSerialize(using = MastershipEventSerializer.class)
public class MastershipEvent extends TopologyElement<MastershipEvent> {
-
private final Dpid dpid;
private final OnosInstanceId onosInstanceId;
private final Role role;
@@ -37,11 +36,12 @@
}
/**
- * Creates the Switch Mastership object.
+ * Constructor for given switch DPID, ONOS Instance ID, and ONOS instance
+ * role for the switch.
*
- * @param dpid the Switch DPID
+ * @param dpid the switch DPID
* @param onosInstanceId the ONOS Instance ID
- * @param role the ONOS instance role for the switch.
+ * @param role the ONOS instance role for the switch
*/
public MastershipEvent(Dpid dpid, OnosInstanceId onosInstanceId,
Role role) {
@@ -51,9 +51,11 @@
}
/**
- * Creates an unfrozen copy of given Object.
+ * Copy constructor.
+ * <p>
+ * Creates an unfrozen copy of the given Switch MastershipEvent object.
*
- * @param original to make copy of.
+ * @param original the object to make copy of
*/
public MastershipEvent(MastershipEvent original) {
super(original);
@@ -65,7 +67,7 @@
/**
* Gets the Switch DPID.
*
- * @return the Switch DPID.
+ * @return the Switch DPID
*/
public Dpid getDpid() {
return dpid;
@@ -74,7 +76,7 @@
/**
* Gets the ONOS Instance ID.
*
- * @return the ONOS Instance ID.
+ * @return the ONOS Instance ID
*/
public OnosInstanceId getOnosInstanceId() {
return onosInstanceId;
@@ -83,7 +85,7 @@
/**
* Gets the ONOS Controller Role for the Switch.
*
- * @return the ONOS Controller Role for the Switch.
+ * @return the ONOS Controller Role for the Switch
*/
public Role getRole() {
return role;
@@ -112,8 +114,8 @@
* MastershipEvent objects are equal if they have same DPID and same
* ONOS Instance ID.
*
- * @param o another object to compare to this.
- * @return true if equal, false otherwise.
+ * @param o another object to compare to this
+ * @return true if equal, false otherwise
*/
@Override
public boolean equals(Object o) {
diff --git a/src/main/java/net/onrc/onos/core/topology/PortEvent.java b/src/main/java/net/onrc/onos/core/topology/PortEvent.java
index b4b0b1b..0961382 100644
--- a/src/main/java/net/onrc/onos/core/topology/PortEvent.java
+++ b/src/main/java/net/onrc/onos/core/topology/PortEvent.java
@@ -20,6 +20,7 @@
*/
@JsonSerialize(using = PortEventSerializer.class)
public class PortEvent extends TopologyElement<PortEvent> {
+ public static final int PORTID_BYTES = SwitchEvent.SWITCHID_BYTES + 2 + 8;
private final SwitchPort id;
// TODO Add Hardware Address
@@ -30,7 +31,6 @@
*/
public static final String DESCRIPTION = "description";
-
/**
* Default constructor for Serializer to use.
*/
@@ -40,28 +40,30 @@
}
/**
- * Creates the port object.
+ * Constructor for given SwitchPort.
*
- * @param switchPort SwitchPort to identify this port
+ * @param switchPort the SwitchPort to identify the port
*/
public PortEvent(SwitchPort switchPort) {
this.id = checkNotNull(switchPort);
}
/**
- * Creates the port object.
+ * Constructor for given switch DPID and port number.
*
- * @param dpid SwitchPort to identify this port
- * @param number PortNumber to identify this port
+ * @param dpid the DPID of the switch the port belongs to
+ * @param number the PortNumber to identify the port
*/
public PortEvent(Dpid dpid, PortNumber number) {
this.id = new SwitchPort(dpid, number);
}
/**
- * Creates an unfrozen copy of given Object.
+ * Copy constructor.
+ * <p>
+ * Creates an unfrozen copy of the given PortEvent object.
*
- * @param original to make copy of.
+ * @param original the object to make copy of
*/
public PortEvent(PortEvent original) {
super(original);
@@ -71,16 +73,16 @@
/**
* Gets the SwitchPort identifying this port.
*
- * @return SwitchPort
+ * @return the SwitchPort identifying this port
*/
public SwitchPort getSwitchPort() {
return id;
}
/**
- * Gets the Dpid of the switch this port belongs to.
+ * Gets the DPID of the switch this port belongs to.
*
- * @return DPID
+ * @return the DPID of the switch this port belongs to
*/
public Dpid getDpid() {
return id.getDpid();
@@ -89,20 +91,35 @@
/**
* Gets the port number.
*
- * @return port number
+ * @return the port number
*/
public PortNumber getPortNumber() {
return id.getPortNumber();
}
- public static final int PORTID_BYTES = SwitchEvent.SWITCHID_BYTES + 2 + 8;
-
+ /**
+ * Computes the port ID for a given switch DPID and a port number.
+ *
+ * @param dpid the switch DPID to use
+ * @param number the port number to use
+ * @return the port ID as a ByteBuffer
+ */
public static ByteBuffer getPortID(Dpid dpid, PortNumber number) {
checkNotNull(dpid);
checkNotNull(number);
return getPortID(dpid.value(), number.value());
}
+ /**
+ * Computes the port ID for a given switch DPID and a port number.
+ * <p>
+ * TODO: This method should be removed and replaced with the corresponding
+ * getPortID(Dpid, PortNumber) method.
+ *
+ * @param dpid the switch DPID to use
+ * @param number the port number to use
+ * @return the port ID as a ByteBuffer
+ */
public static ByteBuffer getPortID(Long dpid, Long number) {
if (dpid == null) {
throw new IllegalArgumentException("dpid cannot be null");
diff --git a/src/main/java/net/onrc/onos/core/topology/SwitchEvent.java b/src/main/java/net/onrc/onos/core/topology/SwitchEvent.java
index ad078c6..f89005d 100644
--- a/src/main/java/net/onrc/onos/core/topology/SwitchEvent.java
+++ b/src/main/java/net/onrc/onos/core/topology/SwitchEvent.java
@@ -18,6 +18,8 @@
*/
@JsonSerialize(using = SwitchEventSerializer.class)
public class SwitchEvent extends TopologyElement<SwitchEvent> {
+ public static final int SWITCHID_BYTES = 2 + 8;
+
private final Dpid dpid;
/**
@@ -29,18 +31,20 @@
}
/**
- * Creates the switch object.
+ * Constructor for given switch DPID.
*
- * @param dpid Dpid to identify this switch
+ * @param dpid the switch DPID to identify the switch
*/
public SwitchEvent(Dpid dpid) {
this.dpid = checkNotNull(dpid);
}
/**
- * Creates an unfrozen copy of given Object.
+ * Copy constructor.
+ * <p>
+ * Creates an unfrozen copy of the given SwitchEvent object.
*
- * @param original to make copy of.
+ * @param original the object to make copy of
*/
public SwitchEvent(SwitchEvent original) {
super(original);
@@ -50,18 +54,31 @@
/**
* Gets the DPID identifying this switch.
*
- * @return DPID
+ * @return the DPID identifying this switch
*/
public Dpid getDpid() {
return dpid;
}
- public static final int SWITCHID_BYTES = 2 + 8;
-
+ /**
+ * Computes the switch ID for a given switch DPID.
+ *
+ * @param dpid the switch DPID to use
+ * @return the switch ID as a ByteBuffer
+ */
public static ByteBuffer getSwitchID(Dpid dpid) {
return getSwitchID(dpid.value());
}
+ /**
+ * Computes the switch ID for a given switch DPID.
+ * <p>
+ * TODO: This method should be removed and replaced with the corresponding
+ * getSwitchID(Dpid) method.
+ *
+ * @param dpid the switch DPID to use
+ * @return the switch ID as a ByteBuffer
+ */
public static ByteBuffer getSwitchID(Long dpid) {
if (dpid == null) {
throw new IllegalArgumentException("dpid cannot be null");