org.projectfloodlight.openflow.protocol.match

Interface Match

All Superinterfaces:

OFObject, PrimitiveSinkable, Writeable

All Known Subinterfaces:

OFMatchV1, OFMatchV2, OFMatchV3

public interface Match
extends OFObject

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 (yotam.harchol@bigswitch.com)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Match.Builder Builder interface for Match objects.

Method Summary

Methods

Modifier and Type	Method and Description
Match.Builder	createBuilder() Returns a builder to build new instances of this type of match object.
<F extends OFValueType<F>> F	get(MatchField<F> field) 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.
<F extends OFValueType<F>> Masked<F>	getMasked(MatchField<F> field) Returns the masked value for the given field from this match, along with the mask itself.
Iterable<MatchField<?>>	getMatchFields() Get an Iterable over the match fields that have been specified for the match.
boolean	isExact(MatchField<?> field) Returns true if and only if this field is currently specified in the match with an exact value and no mask.
boolean	isFullyWildcarded(MatchField<?> field) 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.
boolean	isPartiallyMasked(MatchField<?> field) 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.
boolean	supports(MatchField<?> field) Returns true if and only if this match object supports the given match field.
boolean	supportsMasked(MatchField<?> field) Returns true if and only if this match object supports partially bitmasking of the given field.

Methods inherited from interface org.projectfloodlight.openflow.protocol.OFObject

getVersion

Methods inherited from interface org.projectfloodlight.openflow.protocol.Writeable

writeTo

Methods inherited from interface org.projectfloodlight.openflow.types.PrimitiveSinkable

putTo

Method Detail

get

<F extends OFValueType<F>> F get(MatchField<F> field)
                          throws UnsupportedOperationException

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.

Type Parameters:

F - MatchField type

Parameters:

field - Match field to retrieve

Returns:

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.

getMasked

<F extends OFValueType<F>> Masked<F> getMasked(MatchField<F> 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.

Type Parameters:

F - MatchField type

Parameters:

field - Match field to retrieve.

Returns:

Masked value of match field or null if no mask is set.

Throws:

UnsupportedOperationException - If field is not supported.

supports

boolean supports(MatchField<?> field)

Returns true if and only if this match object supports the given match field.

Parameters:

field - Match field

Returns:

true if field is supported, false otherwise.

supportsMasked

boolean supportsMasked(MatchField<?> field)
                       throws UnsupportedOperationException

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)

Parameters:

field - Match field.

Returns:

true if field can be partially masked, false otherwise.

Throws:

UnsupportedOperationException - If field is not supported.

isExact

boolean isExact(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).

Parameters:

field - Match field.

Returns:

true if field has a specific exact value, false if not.

Throws:

UnsupportedOperationException - If field is not supported.

isFullyWildcarded

boolean isFullyWildcarded(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.

Parameters:

field - Match field.

Returns:

true if field is fully wildcarded, false if not.

Throws:

UnsupportedOperationException - If field is not supported.

isPartiallyMasked

boolean isPartiallyMasked(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.

Parameters:

field - Match field.

Returns:

true if field is partially masked, false if not.

Throws:

UnsupportedOperationException - If field is not supported.

getMatchFields

Iterable<MatchField<?>> getMatchFields()

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).

Returns:

the Iterable of MatchField

createBuilder

Match.Builder createBuilder()

Returns a builder to build new instances of this type of match object.

Returns:

Match builder