| /* |
| * Copyright 2017-present Open Networking Laboratory |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.onosproject.lisp.ctl.impl.tree; |
| |
| import org.onlab.packet.IpAddress; |
| import org.onlab.packet.IpAddress.Version; |
| import org.onlab.packet.IpPrefix; |
| |
| import java.util.List; |
| |
| /** |
| * A radix tree that stores IP address as a key. |
| */ |
| public interface IpRadixTree<V> { |
| |
| /** |
| * Associates the specified value with the specified IP address in this |
| * radix tree. If the radix tree previously contained a mapping for the |
| * address, the old value is replaced by the specified value. |
| * |
| * @param prefix prefix with which the specified value is to be associated |
| * @param value value to be associated with the specified IP address |
| * @return The previous value associated with the key, |
| * if there was one, otherwise null |
| */ |
| V put(IpPrefix prefix, V value); |
| |
| /** |
| * If a value is not already associated with the given address in the radix |
| * tree, associates the given value with the address; otherwise if an |
| * existing value is already associated, returns the existing value and |
| * does not overwrite it. |
| * |
| * This operation is performed atomically. |
| * |
| * @param prefix prefix with which the specified value is to be associated |
| * @param value value to be associated with the specified IP address |
| * @return The existing value associated with the address, if there was one; |
| * otherwise null in which case the new value was successfully associated |
| */ |
| V putIfAbsent(IpPrefix prefix, V value); |
| |
| /** |
| * Removes the mapping for a address from this radix tree if it is present |
| * (optional operation). More formally, if this radix tree contains a |
| * mapping from address <tt>address</tt> to value <tt>v</tt> such that |
| * <code>(address==null ? address==null : address.equals(k))</code>, |
| * that mapping is removed. (The radix tree can contain at most one |
| * such mapping.) |
| * |
| * @param prefix prefix whose mapping is to be removed from the radix tree |
| * @return True if a value was removed (and therefore was associated with |
| * the address), false if no value was associated/removed |
| */ |
| boolean remove(IpPrefix prefix); |
| |
| /** |
| * Returns the value associated with the given address (exact match), |
| * or returns null if no such value is associated with the address. |
| * |
| * @param prefix The prefix with which a sought value might be associated |
| * @return A value associated with the given address (exact match), or null |
| * if no value was associated with the address |
| */ |
| V getValueForExactAddress(IpPrefix prefix); |
| |
| /** |
| * Returns the value associated with the closest parent address, |
| * or returns null if no such value is associated with the address. |
| * This method simply tries the exact match at the first time, if there is |
| * no associated value, it tries the exact match with the parent IP prefix. |
| * |
| * @param prefix The prefix with which a sought value might be associated |
| * @return A value associated with the closest parent address, or |
| * null if no value was associated with the address |
| */ |
| V getValueForClosestParentAddress(IpPrefix prefix); |
| |
| /** |
| * Returns a lazy collection which returns the set of addresses in the radix |
| * tree which start with the given prefix. |
| * |
| * This is <i>inclusive</i> - if the given prefix is an exact match for a |
| * address in the tree, that address is also returned. |
| * |
| * @param prefix A prefix of sought addresses in the tree |
| * @return A set of addresses in the tree which start with the given prefix |
| */ |
| List<IpAddress> getAddressesStartingWith(IpPrefix prefix); |
| |
| /** |
| * Returns a lazy collection which returns the set of values associated with |
| * addresses in the radix tree which start with the given prefix. |
| * |
| * This is <i>inclusive</i> - if the given prefix is an exact match for a |
| * address in the tree, the value associated with that address is |
| * also returned. |
| * |
| * Note that although the same value might originally have been associated |
| * with multiple addresses, the set returned does not contain duplicates |
| * (as determined by the value objects' implementation of |
| * {@link Object#equals(Object)}). |
| * |
| * @param prefix A prefix of addresses in the tree for which associated |
| * values are sought |
| * @return The set of values associated with addresses in the tree which |
| * start with the given prefix |
| */ |
| List<V> getValuesForAddressesStartingWith(IpPrefix prefix); |
| |
| /** |
| * Counts the number of addresses/values stored in the radix tree. |
| * |
| * In the current implementation, <b>this is an expensive operation</b>, |
| * having O(n) time complexity. |
| * |
| * @param version The version of IP address |
| * @return The number of addresses/values stored in the radix tree |
| */ |
| int size(Version version); |
| |
| /** |
| * Removes all of the mappings from this radix tree (optional operation). |
| * The radix tree will be empty after this call returns. |
| */ |
| void clear(); |
| } |