Cleanup and rearrangements in Match structure and fields.
1. Added full documentation for the Match interface
2. Added Builder into Match interface and removed the separate class
3. Added ability to declare field prerequisites in the MatchField class and then check that they are
met using a given Match object
4. Fixed some small issues in value types and added a value type for Metadata
diff --git a/java_gen/pre-written/src/main/java/org/openflow/protocol/match/Match.java b/java_gen/pre-written/src/main/java/org/openflow/protocol/match/Match.java
index d35f709..8f17845 100644
--- a/java_gen/pre-written/src/main/java/org/openflow/protocol/match/Match.java
+++ b/java_gen/pre-written/src/main/java/org/openflow/protocol/match/Match.java
@@ -4,89 +4,190 @@
import org.openflow.types.Masked;
import org.openflow.types.OFValueType;
-public interface Match extends OFObject {
-
- /*
- * Preconditions
- * On preconditions (from the OF1.1 spec, page 28, the OF1.0 spec failed to explicitly
- * specify this, but it is the behavior of Of1.0 switches):
- * Protocol-specific fields within ofp_match will be ignored within a single table when
- * the corresponding protocol is not specified in the match. The MPLS match fields will
- * be ignored unless the Ethertype is specified as MPLS. Likewise, the IP header and
- * transport header fields will be ignored unless the Ethertype is specified as either
- * IPv4 or ARP. The tp_src and tp_dst fields will be ignored unless the network protocol
- * specified is as TCP, UDP or SCTP. Fields that are ignored don�t need to be wildcarded
- * and should be set to 0.
- */
+/**
+ * Generic interface for version-agnostic immutable Match structure.
+ * The Match structure is defined in the OpenFlow protocol, and it contains information on
+ * the fields to be matched in a specific flow record.
+ * This interface does not assume anything on the fields in the Match structure. If in
+ * some version, the match structure cannot handle a certain field, it may return <code>false</code>
+ * for <code>supports(...)</code> calls, and throw <code>UnsupportedOperationException</code> from all
+ * other methods in such cases.
+ * <br><br>
+ * On wildcards and masks:<br>
+ * This interface defines the following masking notations for fields:
+ * <ul>
+ * <li><b>Exact</b>: field is matched exactly against a single, fixed value (no mask, or mask is all ones).
+ * <li><b>Wildcarded</b>: field is not being matched. It is fully masked (mask=0) and any value of it
+ * will match the flow record having this match.
+ * <li><b>Partially masked</b>: field is matched using a specified mask which is neither 0 nor all ones. Mask can
+ * be either arbitrary or require some specific structure.
+ * </ul>
+ * Implementing classes may or may not support all types of these masking types. They may also support
+ * them in part. For example, OF1.0 supports exact match and (full) wildcarding for all fields, but it
+ * does only supports partial masking for IP source/destination fields, and this partial masking must be
+ * in the CIDR prefix format. Thus, OF1.0 implementation may throw <code>UnsupportedOperationException</code> if given
+ * in <code>setMaksed</code> an IP mask of, for example, 255.0.255.0, or if <code>setMasked</code> is called for any field
+ * which is not IP source/destination address.
+ * <br><br>
+ * On prerequisites:<br>
+ * From the OF1.1 spec, page 28, the OF1.0 spec failed to explicitly specify this, but it
+ * is the behavior of OF1.0 switches:
+ * "Protocol-specific fields within ofp_match will be ignored within a single table when
+ * the corresponding protocol is not specified in the match. The MPLS match fields will
+ * be ignored unless the Ethertype is specified as MPLS. Likewise, the IP header and
+ * transport header fields will be ignored unless the Ethertype is specified as either
+ * IPv4 or ARP. The tp_src and tp_dst fields will be ignored unless the network protocol
+ * specified is as TCP, UDP or SCTP. Fields that are ignored donÕt need to be wildcarded
+ * and should be set to 0."
+ * <br><br>
+ * This interface uses generics to assure type safety in users code. However, implementing classes may have to suppress
+ * 'unchecked cast' warnings while making sure they correctly cast base on their implementation details.
+ *
+ * @author Yotam Harchol (yotam.harchol@bigswitch.com)
+ */
+public interface Match extends OFObject {
/**
- * Returns the value for the given field from this match.
- *
+ * Returns a value for the given field if:
+ * <ul>
+ * <li>Field is supported
+ * <li>Field is not fully wildcarded
+ * <li>Prerequisites are ok
+ * </ul>
+ * If one of the above conditions does not hold, returns null. Value is returned masked if partially wildcarded.
+ *
* @param field Match field to retrieve
- * @return Value of match field
+ * @return Value of match field (may be masked), or <code>null</code> if field is one of the conditions above does not hold.
+ * @throws UnsupportedOperationException If field is not supported.
*/
public <F extends OFValueType<F>> F get(MatchField<F> field) throws UnsupportedOperationException;
/**
- * Returns the masked value for the given field from this match.
- * Precondition: field is partially wildcarded.
- *
- * @param field Match field to retrieve
- * @return Masked value of match field or null if no mask
+ * Returns the masked value for the given field from this match, along with the mask itself.
+ * Prerequisite: field is partially masked.
+ * If prerequisite is not met, a <code>null</code> is returned.
+ *
+ * @param field Match field to retrieve.
+ * @return Masked value of match field or null if no mask is set.
+ * @throws UnsupportedOperationException If field is not supported.
*/
public <F extends OFValueType<F>> Masked<F> getMasked(MatchField<F> field) throws UnsupportedOperationException;
/**
- * Returns true if this match object supports the given match field.
- *
+ * Returns true if and only if this match object supports the given match field.
+ *
* @param field Match field
- * @return
+ * @return true if field is supported, false otherwise.
*/
public boolean supports(MatchField<?> field);
/**
- * true iff field supports a bitmask mask that wildcards part of the field
+ * Returns true if and only if this match object supports partially bitmasking of the given field.
* (note: not all possible values of this bitmask have to be acceptable)
- *
- * @param field Match field
- * @return
+ *
+ * @param field Match field.
+ * @return true if field can be partially masked, false otherwise.
+ * @throws UnsupportedOperationException If field is not supported.
*/
- public boolean supportsMasked(MatchField<?> field);
+ public boolean supportsMasked(MatchField<?> field) throws UnsupportedOperationException;
/**
- * True iff this field is currently fully specified in the match, i.e., the
- * match will only select packets that match the exact value of getField(field).
- *
- * @param field Match field
- * @return
+ * Returns true if and only if this field is currently specified in the match with an exact value and
+ * no mask. I.e., the specified match will only select packets that match the exact value of getValue(field).
+ *
+ * @param field Match field.
+ * @return true if field has a specific exact value, false if not.
+ * @throws UnsupportedOperationException If field is not supported.
*/
- public boolean isExact(MatchField<?> field);
+ public boolean isExact(MatchField<?> field) throws UnsupportedOperationException;
/**
- * True if this field is currently logically unspecified in the match, i.e, the
- * value returned by getValue(f) has no impact on whether a packet will be selected
+ * True if and only if this field is currently logically unspecified in the match, i.e, the
+ * value returned by getValue(f) has no impact on whether a packet will be selected
* by the match or not.
- *
- * @param field
- * @return
+ *
+ * @param field Match field.
+ * @return true if field is fully wildcarded, false if not.
+ * @throws UnsupportedOperationException If field is not supported.
*/
- public boolean isFullyWildcarded(MatchField<?> field);
+ public boolean isFullyWildcarded(MatchField<?> field) throws UnsupportedOperationException;
/**
- * True if this field is currently partially specified in the match, i.e, the
- * match will select packets that match (p.value & getMask(field)) == getValue(field).
- *
- * @param field
- * @return
+ * True if and only if this field is currently partially specified in the match, i.e, the
+ * match will only select packets that match (p.value & getMask(field)) == getValue(field),
+ * and getMask(field) != 0.
+ *
+ * @param field Match field.
+ * @return true if field is partially masked, false if not.
+ * @throws UnsupportedOperationException If field is not supported.
*/
- public boolean isPartiallyMasked(MatchField<?> field);
-
+ public boolean isPartiallyMasked(MatchField<?> field) throws UnsupportedOperationException;
+
/**
* Returns a builder to build new instances of this type of match object.
* @return Match builder
*/
- public MatchBuilder createBuilder();
+ public Builder createBuilder();
- interface Builder extends MatchBuilder {
+ /**
+ * Builder interface for Match objects.
+ * Builder is used to create new Match objects and it creates the match according to the version it
+ * corresponds to. The builder uses the same notation of wildcards and masks, and can also throw
+ * <code>UnsupportedOperationException</code> if it is asked to create some matching that is not supported in
+ * the version it represents.
+ *
+ * While used, MatchBuilder may not be consistent in terms of field prerequisites. However, user must
+ * solve these before using the generated Match object as these prerequisites should be enforced in the
+ * getters.
+ *
+ * @author Yotam Harchol (yotam.harchol@bigswitch.com)
+ */
+ interface Builder extends Match {
+ /**
+ * Sets a specific exact value for a field.
+ *
+ * @param field Match field to set.
+ * @param value Value of match field.
+ * @return the Builder instance used.
+ * @throws UnsupportedOperationException If field is not supported.
+ */
+ public <F extends OFValueType<F>> Builder setExact(MatchField<F> field, F value) throws UnsupportedOperationException;
+
+ /**
+ * Sets a masked value for a field.
+ *
+ * @param field Match field to set.
+ * @param value Value of field.
+ * @param mask Mask value.
+ * @return the Builder instance used.
+ * @throws UnsupportedOperationException If field is not supported, if field is supported but does not support masking, or if mask structure is not supported.
+ */
+ public <F extends OFValueType<F>> Builder setMasked(MatchField<F> field, F value, F mask) throws UnsupportedOperationException;
+
+ /**
+ * Sets a masked value for a field.
+ *
+ * @param field Match field to set.
+ * @param valueWithMask Compound Masked object contains the value and the mask.
+ * @return the Builder instance used.
+ * @throws UnsupportedOperationException If field is not supported, if field is supported but does not support masking, or if mask structure is not supported.
+ */
+ public <F extends OFValueType<F>> Builder setMasked(MatchField<F> field, Masked<F> valueWithMask) throws UnsupportedOperationException;
+
+ /**
+ * Unsets any value given for the field and wildcards it so that it matches any value.
+ *
+ * @param field Match field to unset.
+ * @return the Builder instance used.
+ * @throws UnsupportedOperationException If field is not supported.
+ */
+ public <F extends OFValueType<F>> Builder wildcard(MatchField<F> field) throws UnsupportedOperationException;
+
+ /**
+ * Returns the match created by this builder.
+ *
+ * @return a Match object.
+ */
+ public Match getMatch();
}
-}
+}
\ No newline at end of file