org.projectfloodlight.openflow.protocol.match.Match Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of openflowj Show documentation
OpenFlowJ API supporting OpenFlow versions 1.0 through 1.5.1, generated by LoxiGen
The newest version!
package org.projectfloodlight.openflow.protocol.match;

import org.projectfloodlight.openflow.protocol.OFObject;
import org.projectfloodlight.openflow.types.Masked;
import org.projectfloodlight.openflow.types.OFValueType;

/**
 * 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 false
 * for supports(...) calls, and throw UnsupportedOperationException from all
 * other methods in such cases.
 * 


 * On wildcards and masks:

 * This interface defines the following masking notations for fields:
 * 
 * Exact: field is matched exactly against a single, fixed value (no mask, or mask is all ones).
 * 
Wildcarded: field is not being matched. It is fully masked (mask=0) and any value of it
 * will match the flow record having this match.
 * 
Partially masked: field is matched using a specified mask which is neither 0 nor all ones. Mask can
 * be either arbitrary or require some specific structure.
 * 
 * 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 UnsupportedOperationException if given
 * in setMasked an IP mask of, for example, 255.0.255.0, or if setMasked is called for any field
 * which is not IP source/destination address.
 * 


 * On prerequisites:

 * 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."
 * 


 * 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 ([email protected])
 */
public interface Match extends OFObject {

    /**
     * Returns a value for the given field if:
     * 
     * Field is supported
     * 
Field is not fully wildcarded
     * 
Prerequisites are ok
     * 
     * If one of the above conditions does not hold, returns null. Value is returned masked if partially wildcarded.
     *
     * @param  MatchField type
     * @param field Match field to retrieve
     * @return Value of match field (may be masked), or null if field is one of the conditions above does not hold.
     * @throws UnsupportedOperationException If field is not supported.
     */
    public > F get(MatchField field) throws UnsupportedOperationException;

    /**
     * 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 null is returned.
     *
     * @param  MatchField type
     * @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 > Masked getMasked(MatchField field) throws UnsupportedOperationException;

    /**
     * Returns true if and only if this match object supports the given match field.
     *
     * @param field Match field
     * @return true if field is supported, false otherwise.
     */
    public boolean supports(MatchField 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 true if field can be partially masked, false otherwise.
     * @throws UnsupportedOperationException If field is not supported.
     */
    public boolean supportsMasked(MatchField field) throws UnsupportedOperationException;

    /**
     * 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) throws UnsupportedOperationException;

    /**
     * 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 Match field.
     * @return true if field is fully wildcarded, false if not.
     * @throws UnsupportedOperationException If field is not supported.
     */
    public boolean isFullyWildcarded(MatchField field) throws UnsupportedOperationException;

    /**
     * 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) throws UnsupportedOperationException;

    /**
     * Get an Iterable over the match fields that have been specified for the
     * match. This includes the match fields that are exact or masked match
     * (but not fully wildcarded).
     *
     * @return the Iterable of MatchField
     */
    public Iterable> getMatchFields();

    /**
     * Returns a builder to build new instances of this type of match object.
     * @return Match builder
     */
    public Builder createBuilder();

    /**
     * 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
     * UnsupportedOperationException 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 ([email protected])
     */
    interface Builder {
        public > F get(MatchField field) throws UnsupportedOperationException;

        public > Masked getMasked(MatchField field) throws UnsupportedOperationException;

        public boolean supports(MatchField field);

        public boolean supportsMasked(MatchField field) throws UnsupportedOperationException;

        public boolean isExact(MatchField field) throws UnsupportedOperationException;

        public boolean isFullyWildcarded(MatchField field) throws UnsupportedOperationException;

        public boolean isPartiallyMasked(MatchField field) throws UnsupportedOperationException;

        /**
         * Sets a specific exact value for a field.
         *
         * @param  MatchField and value type
         * @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 > Builder setExact(MatchField field, F value) throws UnsupportedOperationException;

        /**
         * Sets a masked value for a field.
         *
         * @param  MatchField, value, and mask type
         * @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 > Builder setMasked(MatchField field, F value, F mask) throws UnsupportedOperationException;

        /**
         * Sets a masked value for a field.
         *
         * @param  MatchField and value with mask type
         * @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 > Builder setMasked(MatchField field, Masked valueWithMask) throws UnsupportedOperationException;

        /**
         * Unsets any value given for the field and wildcards it so that it matches any value.
         *
         * @param  MatchField type
         * @param field Match field to unset.
         * @return the Builder instance used.
         * @throws UnsupportedOperationException If field is not supported.
         */
        public > Builder wildcard(MatchField field) throws UnsupportedOperationException;

        /**
         * Returns the match created by this builder.
         *
         * @return a Match object.
         */
        public Match build();
    }
}