Javadoc updates and consistency fixes; force IPAddress subclasses to override toString(); Nonnull annotations updates
diff --git a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPAddress.java b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPAddress.java
index 8831ee1..0fdf0f3 100644
--- a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPAddress.java
+++ b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPAddress.java
@@ -10,6 +10,11 @@
public abstract class IPAddress<F extends IPAddress<F>> implements OFValueType<F> {
+ /**
+ * Returns the Internet Protocol (IP) version of this object
+ *
+ * @return the Internet Protocol (IP) version of this object
+ */
public abstract IPVersion getIpVersion();
/**
@@ -55,9 +60,22 @@
*/
public abstract F not();
+ /**
+ * Returns the raw IP address of this {@code IPAddress} object. The result
+ * is in network byte order: the highest order byte of the address is in
+ * {@code getBytes()[0]}.
+ * <p>
+ * Similar to {@link InetAddress#getAddress()}
+ *
+ * @return the raw IP address of this object
+ * @see InetAddress#getAddress()
+ */
public abstract byte[] getBytes();
@Override
+ public abstract String toString();
+
+ @Override
public abstract boolean equals(Object other);
@Override
@@ -101,6 +119,13 @@
return IPAddress.of(address.getHostAddress());
}
+ /**
+ * Factory function for InetAddress values.
+ * @param address the InetAddress you wish to parse into an IPAddress object.
+ * @return the IPAddress object.
+ * @throws NullPointerException if address is null
+ * @deprecated replaced by {@link #of(InetAddress)}
+ */
@Deprecated
@Nonnull
public static IPAddress<?> fromInetAddress(@Nonnull InetAddress address) {
diff --git a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv4Address.java b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv4Address.java
index e845521..fab20aa 100644
--- a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv4Address.java
+++ b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv4Address.java
@@ -1,6 +1,7 @@
package org.projectfloodlight.openflow.types;
import java.net.Inet4Address;
+import java.net.InetAddress;
import java.util.Arrays;
import javax.annotation.Nonnull;
@@ -99,6 +100,23 @@
return IPv4Address.of(~rawValue);
}
+ /**
+ * Returns an {@code IPv4Address} object that represents the given
+ * raw IP address. The argument is in network byte order: the highest
+ * order byte of the address is in {@code address[0]}.
+ * <p>
+ * The address byte array must be 4 bytes long (32 bits long).
+ * <p>
+ * Similar to {@link InetAddress#getByAddress(byte[])}.
+ *
+ * @param address the raw IP address in network byte order
+ * @return an {@code IPv4Address} object that represents the given
+ * raw IP address
+ * @throws NullPointerException if the given address was {@code null}
+ * @throws IllegalArgumentException if the given address was of an invalid
+ * byte array length
+ * @see InetAddress#getByAddress(byte[])
+ */
@Nonnull
public static IPv4Address of(@Nonnull final byte[] address) {
Preconditions.checkNotNull(address, "address must not be null");
@@ -114,10 +132,13 @@
return IPv4Address.of(raw);
}
- /** construct an IPv4Address from a 32-bit integer value.
+ /**
+ * Returns an {@code IPv4Address} object that represents the given
+ * raw IP address represented as a 32-bit integer.
*
- * @param raw the IPAdress represented as a 32-bit integer
- * @return the constructed IPv4Address
+ * @param raw the raw IP address represented as a 32-bit integer
+ * @return an {@code IPv4Address} object that represents the given
+ * raw IP address
*/
@Nonnull
public static IPv4Address of(final int raw) {
@@ -126,13 +147,17 @@
return new IPv4Address(raw);
}
- /** parse an IPv4Address from the canonical dotted-quad representation
- * (1.2.3.4).
+ /**
+ * Returns an {@code IPv4Address} object that represents the given
+ * IP address in the canonical dotted-quad notation. For example,
+ * {@code 1.2.3.4}.
*
- * @param string an IPv4 address in dotted-quad representation
- * @return the parsed IPv4 address
- * @throws NullPointerException if string is null
- * @throws IllegalArgumentException if string is not a valid IPv4Address
+ * @param string the IP address in the dotted-quad notation
+ * @return an {@code IPv4Address} object that represents the given
+ * dotted-quad textual IP address
+ * @throws NullPointerException if given string was {@code null}
+ * @throws IllegalArgumentException if given string was not a valid
+ * IPv4 address
*/
@Nonnull
public static IPv4Address of(@Nonnull final String string) throws IllegalArgumentException {
@@ -161,12 +186,33 @@
return IPv4Address.of(raw);
}
+ /**
+ * Returns an {@code IPv4Address} object that represents the
+ * IP address represented by the given {@code Inet4Address} object.
+ *
+ * @param address the {@code Inet4Address} object
+ * @return an {@code IPv4Address} object that represents the
+ * given IP address
+ * @throws NullPointerException if the {@code Inet4Address} object
+ * was {@code null}
+ */
@Nonnull
public static IPv4Address of(@Nonnull final Inet4Address address) {
Preconditions.checkNotNull(address, "address must not be null");
return IPv4Address.of(address.getAddress());
}
+ /**
+ * Returns an {@code IPv4Address} object that represents the
+ * CIDR subnet mask of the given prefix length, that is, the
+ * number of leading one-bits.
+ *
+ * @param cidrMaskLength the prefix length of the CIDR subnet mask,
+ * where {@code 0 <= cidrMaskLength <= 32}
+ * @return an {@code IPv4Address} object that represents the
+ * CIDR subnet mask of the given prefix length
+ * @throws IllegalArgumentException if the given prefix length was invalid
+ */
@Nonnull
public static IPv4Address ofCidrMaskLength(final int cidrMaskLength) {
Preconditions.checkArgument(
@@ -183,23 +229,93 @@
}
}
- public IPv4AddressWithMask withMask(@Nonnull byte[] mask) {
+ /**
+ * Returns an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the given raw IP address mask. The argument is in
+ * network byte order: the highest order byte of the address is in
+ * {@code mask[0]}.
+ * <p>
+ * The address byte array must be 4 bytes long (32 bits long).
+ *
+ * @param mask the raw IP address mask in network byte order
+ * @return an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the given raw IP address mask
+ * @throws NullPointerException if the given mask was {@code null}
+ * @throws IllegalArgumentException if the given mask was of an invalid
+ * byte array length
+ * @see #of(byte[])
+ */
+ @Nonnull
+ public IPv4AddressWithMask withMask(@Nonnull final byte[] mask) {
return IPv4AddressWithMask.of(this, IPv4Address.of(mask));
}
- public IPv4AddressWithMask withMask(int mask) {
+ /**
+ * Returns an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the given raw IP address mask represented as a
+ * 32-bit integer.
+ *
+ * @param mask the raw IP address mask represented as a 32-bit integer
+ * @return an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the given raw IP address mask
+ * @see #of(int)
+ */
+ @Nonnull
+ public IPv4AddressWithMask withMask(final int mask) {
return IPv4AddressWithMask.of(this, IPv4Address.of(mask));
}
- public IPv4AddressWithMask withMask(@Nonnull String mask) {
+ /**
+ * Returns an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the given IP address mask in the canonical
+ * dotted-quad notation. For example, {@code 255.255.255.0}.
+ *
+ * @param mask the IP address mask in the dotted-quad notation
+ * @return an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the given dotted-quad textual IP
+ * address mask
+ * @throws NullPointerException if the given string was {@code null}
+ * @throws IllegalArgumentException if the given string was not a valid
+ * IPv4 address mask
+ * @see #of(String)
+ */
+ @Nonnull
+ public IPv4AddressWithMask withMask(@Nonnull final String mask) {
return IPv4AddressWithMask.of(this, IPv4Address.of(mask));
}
- public IPv4AddressWithMask withMask(@Nonnull Inet4Address mask) {
+ /**
+ * Returns an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the IP address mask represented by the given
+ * {@code Inet4Address} object.
+ *
+ * @param mask the {@code Inet4Address} object
+ * @return an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the given IP address mask
+ * @throws NullPointerException if the {@code Inet4Address} object
+ * was {@code null}
+ * @see #of(Inet4Address)
+ */
+ @Nonnull
+ public IPv4AddressWithMask withMask(@Nonnull final Inet4Address mask) {
return IPv4AddressWithMask.of(this, IPv4Address.of(mask));
}
- public IPv4AddressWithMask withMaskOfLength(int cidrMaskLength) {
+ /**
+ * Returns an {@code IPv4AddressWithMask} object that represents this
+ * IP address masked by the CIDR subnet mask of the given prefix length,
+ * that is, the number of leading one-bits.
+ *
+ * @param cidrMaskLength the prefix length of the CIDR subnet mask,
+ * where {@code 0 <= cidrMaskLength <= 32}
+ * @return an {@code IPv4AddressWithMask} object that
+ * represents this IP address masked by the CIDR
+ * subnet mask of the given prefix length
+ * @throws IllegalArgumentException if the given prefix length was invalid
+ * @see #ofCidrMaskLength(int)
+ */
+ @Nonnull
+ public IPv4AddressWithMask withMaskOfLength(final int cidrMaskLength) {
return IPv4AddressWithMask.of(this,
IPv4Address.ofCidrMaskLength(cidrMaskLength));
}
@@ -210,6 +326,7 @@
private volatile byte[] bytesCache = null;
+ @Override
public byte[] getBytes() {
if (bytesCache == null) {
synchronized (this) {
diff --git a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv4AddressWithMask.java b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv4AddressWithMask.java
index b7f0037..31b4455 100644
--- a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv4AddressWithMask.java
+++ b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv4AddressWithMask.java
@@ -1,5 +1,7 @@
package org.projectfloodlight.openflow.types;
+import javax.annotation.Nonnull;
+
import com.google.common.base.Preconditions;
@@ -19,18 +21,69 @@
return IPVersion.IPv4;
}
- public static IPv4AddressWithMask of(int rawValue, int rawMask) {
+ /**
+ * Returns an {@code IPv4AddressWithMask} object that represents the given
+ * raw IP address masked by the given raw IP address mask, with both
+ * represented as 32-bit integers.
+ *
+ * @param rawValue the raw IP address to be masked
+ * @param rawMask the raw IP address mask
+ * @return an {@code IPv4AddressWithMask} object that represents
+ * the given raw IP address masked by the given raw IP
+ * address mask
+ */
+ @Nonnull
+ public static IPv4AddressWithMask of(final int rawValue, final int rawMask) {
return new IPv4AddressWithMask(rawValue, rawMask);
}
- public static IPv4AddressWithMask of(IPv4Address value, IPv4Address mask) {
+ /**
+ * Returns an {@code IPv4AddressWithMask} object that represents the given
+ * IP address masked by the given IP address mask, with both represented
+ * as {@code IPv4Address} objects.
+ *
+ * @param value the IP address to be masked
+ * @param mask the IP address mask
+ * @return an {@code IPv4AddressWithMask} object that represents
+ * the given IP address masked by the given IP address mask
+ * @throws NullPointerException if any of the given {@code IPv4Address}
+ * objects were {@code null}
+ */
+ @Nonnull
+ public static IPv4AddressWithMask of(
+ @Nonnull final IPv4Address value,
+ @Nonnull final IPv4Address mask) {
Preconditions.checkNotNull(value, "value must not be null");
Preconditions.checkNotNull(mask, "mask must not be null");
return new IPv4AddressWithMask(value, mask);
}
- public static IPv4AddressWithMask of(final String string) {
+ /**
+ * Returns an {@code IPv4AddressWithMask} object that corresponds to
+ * the given string in CIDR notation or other notations as specified
+ * below
+ * <p>
+ * The following notations are accepted.
+ * <table><tr>
+ * <th>Notation</th><th>Example</th><th>Notes</th>
+ * </tr><tr>
+ * <td>IPv4 address only</td><td>{@code 1.2.3.4}</td><td>The subnet mask of
+ * prefix length 32 (i.e. {@code 255.255.255.255}) is assumed.</td>
+ * </tr><tr>
+ * <td>IPv4 address/mask</td><td>{@code 1.2.3.4/255.255.255.0}</td>
+ * </tr><tr>
+ * <td>CIDR notation</td><td>{@code 1.2.3.4/24}</td>
+ * </tr></table>
+ *
+ * @param string the string in acceptable notations
+ * @return an {@code IPv4AddressWithMask} object that corresponds to
+ * the given string in acceptable notations
+ * @throws NullPointerException if the given string was {@code null}
+ * @throws IllegalArgumentException if the given string was malformed
+ */
+ @Nonnull
+ public static IPv4AddressWithMask of(@Nonnull final String string) {
Preconditions.checkNotNull(string, "string must not be null");
int slashPos;