Merge into master from pull request #221:
java_gen: add documentation to string-parsing 'of' methods (https://github.com/floodlight/loxigen/pull/221)
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 d9993b0..6ca39fe 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
@@ -1,5 +1,7 @@
package org.projectfloodlight.openflow.types;
+import javax.annotation.Nonnull;
+
public abstract class IPAddress<F extends IPAddress<F>> implements OFValueType<F> {
public abstract IPVersion getIpVersion();
@@ -53,7 +55,17 @@
@Override
public abstract int hashCode();
- public static IPAddress<?> of(String ip) {
+ /** parse an IPv4Address or IPv6Address from their conventional string representation.
+ * For details on supported representations, refer to {@link IPv4Address#of(String)}
+ * and {@link IPv6Address#of(String)}
+ *
+ * @param ip a string representation of an IP address
+ * @return the parsed IP address
+ * @throws NullPointerException if ip is null
+ * @throws IllegalArgumentException if string is not a valid IP address
+ */
+ @Nonnull
+ public static IPAddress<?> of(@Nonnull String ip) {
if (ip == null) {
throw new NullPointerException("String ip must not be null");
}
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 43fefac..865fb79 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
@@ -2,6 +2,8 @@
import java.util.Arrays;
+import javax.annotation.Nonnull;
+
import org.jboss.netty.buffer.ChannelBuffer;
import com.google.common.hash.PrimitiveSink;
@@ -112,13 +114,27 @@
return IPv4Address.of(raw);
}
+ /** construct an IPv4Address from a 32-bit integer value.
+ *
+ * @param raw the IPAdress represented as a 32-bit integer
+ * @return the constructed IPv4Address
+ */
public static IPv4Address of(final int raw) {
if(raw == NONE_VAL)
return NONE;
return new IPv4Address(raw);
}
- public static IPv4Address of(final String string) {
+ /** parse an IPv4Address from the canonical dotted-quad representation
+ * (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
+ */
+ @Nonnull
+ public static IPv4Address of(@Nonnull final String string) throws IllegalArgumentException {
if (string == null) {
throw new NullPointerException("String must not be null");
}
diff --git a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv6Address.java b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv6Address.java
index 1ee9e89..83fb31a 100644
--- a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv6Address.java
+++ b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/IPv6Address.java
@@ -3,6 +3,8 @@
import java.util.Arrays;
import java.util.regex.Pattern;
+import javax.annotation.Nonnull;
+
import org.jboss.netty.buffer.ChannelBuffer;
import org.projectfloodlight.openflow.exceptions.OFParseError;
@@ -169,7 +171,22 @@
private final static Pattern colonPattern = Pattern.compile(":");
- public static IPv6Address of(final String string) {
+ /** parse an IPv6Address from its conventional string representation.
+ * <p>
+ * Expects up to 8 groups of 16-bit hex words seperated by colons
+ * (e.g., 2001:db8:85a3:8d3:1319:8a2e:370:7348).
+ * <p>
+ * Supports zero compression (e.g., 2001:db8::7348).
+ * Does <b>not</b> currently support embedding a dotted-quad IPv4 address
+ * into the IPv6 address (e.g., 2001:db8::192.168.0.1).
+ *
+ * @param string a string representation of an IPv6 address
+ * @return the parsed IPv6 address
+ * @throws NullPointerException if string is null
+ * @throws IllegalArgumentException if string is not a valid IPv6Address
+ */
+ @Nonnull
+ public static IPv6Address of(@Nonnull final String string) throws IllegalArgumentException {
if (string == null) {
throw new NullPointerException("String must not be null");
}
@@ -225,6 +242,13 @@
return builder.getIPv6();
}
+ /** construct an IPv6 adress from two 64 bit integers representing the first and
+ * second 8-byte blocks of the address.
+ *
+ * @param raw1 - the first 8 byte block of the address
+ * @param raw2 - the second 8 byte block of the address
+ * @return the constructed IPv6Address
+ */
public static IPv6Address of(final long raw1, final long raw2) {
if(raw1==NONE_VAL1 && raw2 == NONE_VAL2)
return NONE;
diff --git a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/MacAddress.java b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/MacAddress.java
index f592ea8..d7f044e 100644
--- a/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/MacAddress.java
+++ b/java_gen/pre-written/src/main/java/org/projectfloodlight/openflow/types/MacAddress.java
@@ -2,6 +2,8 @@
import java.util.Arrays;
+import javax.annotation.Nonnull;
+
import org.jboss.netty.buffer.ChannelBuffer;
import org.projectfloodlight.openflow.exceptions.OFParseError;
import org.projectfloodlight.openflow.util.HexString;
@@ -55,27 +57,38 @@
return new MacAddress(raw);
}
- public static MacAddress of(final String string) {
+ /** Parse a mac adress from the canonical string representation as
+ * 6 hex bytes separated by colons (01:02:03:04:05:06).
+ *
+ * @param macString - a mac address in canonical string representation
+ * @return the parsed MacAddress
+ * @throws IllegalArgumentException if macString is not a valid mac adddress
+ */
+ @Nonnull
+ public static MacAddress of(@Nonnull final String macString) throws IllegalArgumentException {
+ if (macString == null) {
+ throw new NullPointerException("macString must not be null");
+ }
int index = 0;
int shift = 40;
final String FORMAT_ERROR = "Mac address is not well-formed. " +
"It must consist of 6 hex digit pairs separated by colons: ";
long raw = 0;
- if (string.length() != 6 * 2 + 5)
- throw new IllegalArgumentException(FORMAT_ERROR + string);
+ if (macString.length() != 6 * 2 + 5)
+ throw new IllegalArgumentException(FORMAT_ERROR + macString);
while (shift >= 0) {
- int digit1 = Character.digit(string.charAt(index++), 16);
- int digit2 = Character.digit(string.charAt(index++), 16);
+ int digit1 = Character.digit(macString.charAt(index++), 16);
+ int digit2 = Character.digit(macString.charAt(index++), 16);
if ((digit1 < 0) || (digit2 < 0))
- throw new IllegalArgumentException(FORMAT_ERROR + string);
+ throw new IllegalArgumentException(FORMAT_ERROR + macString);
raw |= ((long) (digit1 << 4 | digit2)) << shift;
if (shift == 0)
break;
- if (string.charAt(index++) != ':')
- throw new IllegalArgumentException(FORMAT_ERROR + string);
+ if (macString.charAt(index++) != ':')
+ throw new IllegalArgumentException(FORMAT_ERROR + macString);
shift -= 8;
}
return MacAddress.of(raw);