2 * Copyright (c) 2013 Cisco Systems, Inc. and others. All rights reserved.
4 * This program and the accompanying materials are made available under the
5 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6 * and is available at http://www.eclipse.org/legal/epl-v10.html
9 package org.opendaylight.controller.sal.match;
11 import java.io.Serializable;
12 import java.net.Inet4Address;
13 import java.net.Inet6Address;
14 import java.net.InetAddress;
15 import java.util.ArrayList;
16 import java.util.Arrays;
17 import java.util.Collection;
18 import java.util.Collections;
19 import java.util.HashMap;
20 import java.util.List;
22 import java.util.Map.Entry;
23 import java.util.TreeMap;
24 import java.util.concurrent.ConcurrentMap;
25 import java.util.concurrent.ConcurrentHashMap;
27 import javax.xml.bind.annotation.XmlAccessType;
28 import javax.xml.bind.annotation.XmlAccessorType;
29 import javax.xml.bind.annotation.XmlElement;
30 import javax.xml.bind.annotation.XmlRootElement;
32 import org.opendaylight.controller.sal.core.Property;
33 import org.opendaylight.controller.sal.utils.EtherTypes;
34 import org.opendaylight.controller.sal.utils.IPProtocols;
35 import org.opendaylight.controller.sal.utils.NetUtils;
38 * Represents the generic match criteria for a network frame/packet/message
39 * It contains a collection of individual field match
43 @XmlAccessorType(XmlAccessType.NONE)
44 public class Match implements Cloneable, Serializable {
45 private static final long serialVersionUID = 1L;
46 private static final Map<MatchType, MatchType> reversableMatches;
48 Map<MatchType, MatchType> map = new HashMap<MatchType, MatchType>();
49 map.put(MatchType.DL_SRC, MatchType.DL_DST);
50 map.put(MatchType.DL_DST, MatchType.DL_SRC);
51 map.put(MatchType.NW_SRC, MatchType.NW_DST);
52 map.put(MatchType.NW_DST, MatchType.NW_SRC);
53 map.put(MatchType.TP_SRC, MatchType.TP_DST);
54 map.put(MatchType.TP_DST, MatchType.TP_SRC);
55 reversableMatches = Collections.unmodifiableMap(map);
57 private Map<MatchType, MatchField> fields;
58 private int matches; // concise way to tell which fields the match
59 // is set for (may remove if not needed)
60 private ConcurrentMap<String, Property> props;
63 fields = new HashMap<MatchType, MatchField>();
67 public Match(Match match) {
68 fields = new HashMap<MatchType, MatchField>(match.fields);
69 matches = match.matches;
73 * Gets the list of metadata currently registered with this match
75 * @return List of metadata currently registered
77 public List <Property> getMetadatas() {
78 if (this.props != null) {
79 // Return all the values in the map
80 Collection res = this.props.values();
82 return Collections.emptyList();
84 return new ArrayList<Property>(res);
86 return Collections.emptyList();
90 * Gets the metadata registered with a name if present
92 * @param name the name of the property to be extracted
94 * @return List of metadata currently registered
96 public Property getMetadata(String name) {
100 if (this.props != null) {
101 // Return the Property associated to the name
102 return this.props.get(name);
108 * Sets the metadata associated to a name. If the name or prop is NULL,
109 * an exception NullPointerException will be raised.
111 * @param name the name of the property to be set
112 * @param prop, property to be set
114 public void setMetadata(String name, Property prop) {
115 if (this.props == null) {
116 props = new ConcurrentHashMap<String, Property>();
119 if (this.props != null) {
120 this.props.put(name, prop);
125 * Remove the metadata associated to a name. If the name is NULL,
126 * nothing will be removed.
128 * @param name the name of the property to be set
129 * @param prop, property to be set
131 * @return List of metadata currently registered
133 public void removeMetadata(String name) {
134 if (this.props == null) {
138 if (this.props != null) {
139 this.props.remove(name);
141 // It's intentional to keep the this.props still allocated
142 // till the parent data structure will be alive, so to avoid
143 // unnecessary allocation/deallocation, even if it's holding
148 * Generic setter for frame/packet/message's header fields against which to match
149 * Note: For MAC addresses, please pass the cloned value to this function
151 * @param type packet's header field type
152 * @param value field's value to assign to the match
153 * @param mask field's bitmask to apply to the match (has to be of the same class type of value)
155 public void setField(MatchType type, Object value, Object mask) {
156 MatchField field = new MatchField(type, value, mask);
157 if (field.isValid()) {
158 fields.put(type, field);
159 matches |= type.getIndex();
164 * Generic setter for frame/packet/message's header fields against which to match
165 * Note: For MAC addresses, please pass the cloned value to this function
167 * @param type packet's header field type
168 * @param value field's value to assign to the match
170 public void setField(MatchType type, Object value) {
171 MatchField field = new MatchField(type, value);
172 if (field.isValid()) {
173 fields.put(type, field);
174 matches |= type.getIndex();
179 * Generic setter for frame/packet/message's header field against which to match
181 * @param field the fields parameters as MAtchField object
183 public void setField(MatchField field) {
184 if (field.isValid()) {
185 fields.put(field.getType(), field);
186 matches |= field.getType().getIndex();
191 * Generic method to clear a field from the match
193 public void clearField(MatchType type) {
195 matches &= ~type.getIndex();
199 * Generic getter for fields against which the match is programmed
201 * @param type frame/packet/message's header field type
204 public MatchField getField(MatchType type) {
205 return fields.get(type);
209 * Returns the fields the match is set for in a bitmask fashion
210 * Each bit represents a field the match is configured for
212 * @return the 32 bit long mask (Refer to {@code}org.opendaylight.controller.sal.match.MatchElement)
214 public int getMatches() {
219 * Returns the list of MatchType fields the match is set for
221 * @return List of individual MatchType fields.
223 public List<MatchType> getMatchesList() {
224 return new ArrayList<MatchType>(fields.keySet());
228 * Returns the list of MatchFields the match is set for
230 * @return List of individual MatchField values.
232 @XmlElement(name="matchField")
233 public List<MatchField> getMatchFields() {
234 return new ArrayList<MatchField>(fields.values());
238 * Returns whether this match is for an IPv6 flow
240 public boolean isIPv6() {
241 return (isPresent(MatchType.DL_TYPE)
242 && ((Short) getField(MatchType.DL_TYPE).getValue())
243 .equals(EtherTypes.IPv6.shortValue())
244 || isPresent(MatchType.NW_PROTO)
245 && ((Byte) getField(MatchType.NW_PROTO).getValue())
246 .equals(IPProtocols.IPV6ICMP.byteValue())
247 || isPresent(MatchType.NW_SRC)
248 && getField(MatchType.NW_SRC).getValue() instanceof Inet6Address || isPresent(MatchType.NW_DST)
249 && getField(MatchType.NW_DST).getValue() instanceof Inet6Address);
253 * Returns whether this match is for an IPv4 flow
255 public boolean isIPv4() {
260 * Returns whether for the specified field type the match is to be considered "any"
261 * Equivalent to say this match does not care about the value of the specified field
266 public boolean isAny(MatchType type) {
267 //return ((fields.get(type) == null) || (fields.get(type).getBitMask() == 0L));
268 return !fields.containsKey(type);
272 * Returns whether a match for the specified field type is configured
277 public boolean isPresent(MatchType type) {
278 return (fields.get(type) != null);
282 public Match clone() {
285 cloned = (Match) super.clone();
286 cloned.matches = matches;
287 cloned.fields = new HashMap<MatchType, MatchField>();
288 for (Entry<MatchType, MatchField> entry : this.fields.entrySet()) {
289 cloned.fields.put(entry.getKey(), entry.getValue().clone());
291 } catch (CloneNotSupportedException e) {
292 throw new RuntimeException(e);
298 * Returns a reversed version of this match
299 * For example, in the reversed version the network source and destination
300 * addresses will be exchanged. Non symmetric match field will not be
301 * copied over into the reversed match version, like input port.
305 public Match reverse() {
306 // Copy over all fields
307 Match reverse = this.clone();
309 // Flip symmetric fields
310 for (Map.Entry<MatchType, MatchType> entry : Match.reversableMatches.entrySet()) {
311 MatchType from = entry.getKey();
312 MatchType to = entry.getValue();
313 if (this.isPresent(from)) {
314 reverse.setField(to, this.getField(from).getValue(), this.getField(from).getMask());
315 if (!this.isPresent(to)) {
316 reverse.clearField(from);
321 // Reset asymmetric fields
322 reverse.clearField(MatchType.IN_PORT);
328 * Check whether the current match conflicts with the passed filter match
329 * This match conflicts with the filter if for at least a MatchType defined
330 * in the filter match, the respective MatchFields differ or are not
333 * In other words the function returns true if the set of packets described
334 * by one match and the set of packets described by the other match are
335 * disjoint. Equivalently, if the intersection of the two sets of packets
336 * described by the two matches is an empty.
338 * For example, Let's suppose the filter has the following MatchFields:
340 * NW_DST = 172.20.30.110/24
342 * while this match has the following MatchFields:
344 * NW_DST = 172.20.30.45/24
347 * Then the function would return false as the two Match are not
350 * Note: the mask value is taken into account only for MatchType.NW_SRC and
354 * the Match describing the filter
355 * @return true if the set of packets described by one match and the set of
356 * packets described by the other match are disjoint, false
359 public boolean conflictWithFilter(Match filter) {
360 return !this.intersetcs(filter);
364 * Merge the current Match fields with the fields of the filter Match. A
365 * check is first run to see if this Match is compatible with the filter
366 * Match. If it is not, the merge is not attempted.
368 * The result is the match object representing the intersection of the set
369 * of packets described by this match with the set of packets described by
370 * the filter match. If the intersection of the two sets is empty, the
371 * return match will be null.
374 * the match with which attempting the merge
375 * @return a new Match object describing the set of packets represented by
376 * the intersection of this and the filter matches. null if the
377 * intersection is empty.
379 public Match mergeWithFilter(Match filter) {
380 return this.getIntersection(filter);
384 * Return the match representing the intersection of the set of packets
385 * described by this match with the set of packets described by the other
386 * match. Such as m.getIntersection(m) == m, m.getIntersection(u) == m and
387 * m.getIntersection(o) == o where u is an empty match (universal set, all
388 * packets) and o is the null match (empty set).
391 * the match with which computing the intersection
392 * @return a new Match object representing the intersection of the set of
393 * packets described by this match with the set of packets described
394 * by the other match. null when the intersection is the empty set.
396 public Match getIntersection(Match other) {
397 // If no intersection, return the empty set
398 if (!this.intersetcs(other)) {
401 // Check if any of the two is the universal match
402 if (this.getMatches() == 0) {
403 return other.clone();
405 if (other.getMatches() == 0) {
408 // Derive the intersection
409 Match intersection = new Match();
410 for (MatchType type : MatchType.values()) {
411 if (this.isAny(type) && other.isAny(type)) {
414 if (this.isAny(type)) {
415 intersection.setField(other.getField(type).clone());
417 } else if (other.isAny(type)) {
418 intersection.setField(this.getField(type).clone());
421 // Either they are equal or it is about IP address
423 // When it is about IP address, take the wider prefix address
427 MatchField thisField = this.getField(type);
428 MatchField otherField = other.getField(type);
429 InetAddress thisAddress = (InetAddress) thisField.getValue();
430 InetAddress otherAddress = (InetAddress) otherField.getValue();
431 InetAddress thisMask = (InetAddress) thisField.getMask();
432 InetAddress otherMask = (InetAddress) otherField.getMask();
434 int thisMaskLen = (thisMask == null) ? ((thisAddress instanceof Inet4Address) ? 32 : 128) : NetUtils
435 .getSubnetMaskLength(thisMask);
436 int otherMaskLen = (otherMask == null) ? ((otherAddress instanceof Inet4Address) ? 32 : 128) : NetUtils
437 .getSubnetMaskLength(otherMask);
438 if (thisMaskLen < otherMaskLen) {
439 intersection.setField(new MatchField(type, NetUtils.getSubnetPrefix(otherAddress, otherMaskLen),
442 intersection.setField(new MatchField(type, NetUtils.getSubnetPrefix(thisAddress, thisMaskLen),
447 // this and other match field are equal for this type, pick this
449 intersection.setField(this.getField(type).clone());
456 * Checks whether the intersection of the set of packets described by this
457 * match with the set of packets described by the other match is non empty
459 * For example, if this match is: DL_SRC = 00:cc:bb:aa:11:22
461 * and the other match is: DL_TYPE = 0x800 NW_SRC = 1.2.3.4
463 * then their respective matching packets set intersection is non empty:
464 * DL_SRC = 00:cc:bb:aa:11:22 DL_TYPE = 0x800 NW_SRC = 1.2.3.4
467 * the other match with which testing the intersection
468 * @return true if the intersection of the respective matching packets sets
471 public boolean intersetcs(Match other) {
472 // No intersection with the empty set
476 // Always intersection with the universal set
477 if (this.getMatches() == 0 || other.getMatches() == 0) {
480 // Iterate through the MatchType defined in the filter
481 for (MatchType type : MatchType.values()) {
482 if (this.isAny(type) || other.isAny(type)) {
486 MatchField thisField = this.getField(type);
487 MatchField otherField = other.getField(type);
492 if (!Arrays.equals((byte[]) thisField.getValue(), (byte[]) otherField.getValue())) {
498 InetAddress thisAddress = (InetAddress) thisField.getValue();
499 InetAddress otherAddress = (InetAddress) otherField.getValue();
501 if (thisAddress instanceof Inet4Address && otherAddress instanceof Inet6Address
502 || thisAddress instanceof Inet6Address && otherAddress instanceof Inet4Address) {
505 InetAddress thisMask = (InetAddress) thisField.getMask();
506 InetAddress otherMask = (InetAddress) otherField.getMask();
507 if (NetUtils.inetAddressConflict(thisAddress, otherAddress, thisMask, otherMask)
508 && NetUtils.inetAddressConflict(otherAddress, thisAddress, otherMask, thisMask)) {
513 if (!thisField.getValue().equals(otherField.getValue())) {
522 public int hashCode() {
523 final int prime = 31;
525 if (this.fields == null) {
526 result = prime * result;
528 // use a tree map as the order of hashMap is not guaranteed.
529 // 2 Match objects with fields in different order are still equal.
530 // Hence the hashCode should be the same too.
531 TreeMap<MatchType, MatchField> tm = new TreeMap<MatchType, MatchField>(this.fields);
532 for (MatchType field : tm.keySet()) {
533 MatchField f = tm.get(field);
534 int fieldHashCode = (field==null ? 0 : field.calculateConsistentHashCode()) ^
535 (f==null ? 0 : f.hashCode());
536 result = prime * result + fieldHashCode;
539 result = prime * result + matches;
544 public boolean equals(Object obj) {
551 if (getClass() != obj.getClass()) {
554 Match other = (Match) obj;
555 if (fields == null) {
556 if (other.fields != null) {
559 } else if (!fields.equals(other.fields)) {
562 if (matches != other.matches) {
569 public String toString() {
570 StringBuilder builder = new StringBuilder();
571 builder.append("Match [fields=");
572 builder.append(fields);
573 builder.append(", matches=");
574 builder.append(matches);
576 return builder.toString();