ConcurrentNavigableMap.java revision 51b1b6997fd3f980076b8081f7f1165ccc2a4008
1/* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25/* 26 * This file is available under and governed by the GNU General Public 27 * License version 2 only, as published by the Free Software Foundation. 28 * However, the following notice accompanied the original version of this 29 * file: 30 * 31 * Written by Doug Lea with assistance from members of JCP JSR-166 32 * Expert Group and released to the public domain, as explained at 33 * http://creativecommons.org/publicdomain/zero/1.0/ 34 */ 35 36package java.util.concurrent; 37import java.util.*; 38 39/** 40 * A {@link ConcurrentMap} supporting {@link NavigableMap} operations, 41 * and recursively so for its navigable sub-maps. 42 * 43 * <p>This interface is a member of the 44 * <a href="{@docRoot}/../technotes/guides/collections/index.html"> 45 * Java Collections Framework</a>. 46 * 47 * @author Doug Lea 48 * @param <K> the type of keys maintained by this map 49 * @param <V> the type of mapped values 50 * @since 1.6 51 */ 52public interface ConcurrentNavigableMap<K,V> 53 extends ConcurrentMap<K,V>, NavigableMap<K,V> 54{ 55 /** 56 * @throws ClassCastException {@inheritDoc} 57 * @throws NullPointerException {@inheritDoc} 58 * @throws IllegalArgumentException {@inheritDoc} 59 */ 60 ConcurrentNavigableMap<K,V> subMap(K fromKey, boolean fromInclusive, 61 K toKey, boolean toInclusive); 62 63 /** 64 * @throws ClassCastException {@inheritDoc} 65 * @throws NullPointerException {@inheritDoc} 66 * @throws IllegalArgumentException {@inheritDoc} 67 */ 68 ConcurrentNavigableMap<K,V> headMap(K toKey, boolean inclusive); 69 70 71 /** 72 * @throws ClassCastException {@inheritDoc} 73 * @throws NullPointerException {@inheritDoc} 74 * @throws IllegalArgumentException {@inheritDoc} 75 */ 76 ConcurrentNavigableMap<K,V> tailMap(K fromKey, boolean inclusive); 77 78 /** 79 * @throws ClassCastException {@inheritDoc} 80 * @throws NullPointerException {@inheritDoc} 81 * @throws IllegalArgumentException {@inheritDoc} 82 */ 83 ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey); 84 85 /** 86 * @throws ClassCastException {@inheritDoc} 87 * @throws NullPointerException {@inheritDoc} 88 * @throws IllegalArgumentException {@inheritDoc} 89 */ 90 ConcurrentNavigableMap<K,V> headMap(K toKey); 91 92 /** 93 * @throws ClassCastException {@inheritDoc} 94 * @throws NullPointerException {@inheritDoc} 95 * @throws IllegalArgumentException {@inheritDoc} 96 */ 97 ConcurrentNavigableMap<K,V> tailMap(K fromKey); 98 99 /** 100 * Returns a reverse order view of the mappings contained in this map. 101 * The descending map is backed by this map, so changes to the map are 102 * reflected in the descending map, and vice-versa. 103 * 104 * <p>The returned map has an ordering equivalent to 105 * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>. 106 * The expression {@code m.descendingMap().descendingMap()} returns a 107 * view of {@code m} essentially equivalent to {@code m}. 108 * 109 * @return a reverse order view of this map 110 */ 111 ConcurrentNavigableMap<K,V> descendingMap(); 112 113 /** 114 * Returns a {@link NavigableSet} view of the keys contained in this map. 115 * The set's iterator returns the keys in ascending order. 116 * The set is backed by the map, so changes to the map are 117 * reflected in the set, and vice-versa. The set supports element 118 * removal, which removes the corresponding mapping from the map, 119 * via the {@code Iterator.remove}, {@code Set.remove}, 120 * {@code removeAll}, {@code retainAll}, and {@code clear} 121 * operations. It does not support the {@code add} or {@code addAll} 122 * operations. 123 * 124 * <p>The view's {@code iterator} is a "weakly consistent" iterator 125 * that will never throw {@link ConcurrentModificationException}, 126 * and guarantees to traverse elements as they existed upon 127 * construction of the iterator, and may (but is not guaranteed to) 128 * reflect any modifications subsequent to construction. 129 * 130 * @return a navigable set view of the keys in this map 131 */ 132 public NavigableSet<K> navigableKeySet(); 133 134 /** 135 * Returns a {@link NavigableSet} view of the keys contained in this map. 136 * The set's iterator returns the keys in ascending order. 137 * The set is backed by the map, so changes to the map are 138 * reflected in the set, and vice-versa. The set supports element 139 * removal, which removes the corresponding mapping from the map, 140 * via the {@code Iterator.remove}, {@code Set.remove}, 141 * {@code removeAll}, {@code retainAll}, and {@code clear} 142 * operations. It does not support the {@code add} or {@code addAll} 143 * operations. 144 * 145 * <p>The view's {@code iterator} is a "weakly consistent" iterator 146 * that will never throw {@link ConcurrentModificationException}, 147 * and guarantees to traverse elements as they existed upon 148 * construction of the iterator, and may (but is not guaranteed to) 149 * reflect any modifications subsequent to construction. 150 * 151 * <p>This method is equivalent to method {@code navigableKeySet}. 152 * 153 * @return a navigable set view of the keys in this map 154 */ 155 NavigableSet<K> keySet(); 156 157 /** 158 * Returns a reverse order {@link NavigableSet} view of the keys contained in this map. 159 * The set's iterator returns the keys in descending order. 160 * The set is backed by the map, so changes to the map are 161 * reflected in the set, and vice-versa. The set supports element 162 * removal, which removes the corresponding mapping from the map, 163 * via the {@code Iterator.remove}, {@code Set.remove}, 164 * {@code removeAll}, {@code retainAll}, and {@code clear} 165 * operations. It does not support the {@code add} or {@code addAll} 166 * operations. 167 * 168 * <p>The view's {@code iterator} is a "weakly consistent" iterator 169 * that will never throw {@link ConcurrentModificationException}, 170 * and guarantees to traverse elements as they existed upon 171 * construction of the iterator, and may (but is not guaranteed to) 172 * reflect any modifications subsequent to construction. 173 * 174 * @return a reverse order navigable set view of the keys in this map 175 */ 176 public NavigableSet<K> descendingKeySet(); 177} 178