001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file:
030 *
031 * Written by Doug Lea with assistance from members of JCP JSR-166
032 * Expert Group and released to the public domain, as explained at
033 * http://creativecommons.org/licenses/publicdomain
034 */
035
036 package java.util.concurrent;
037
038 import java.util.*;
039
040 /**
041 * A {@link ConcurrentMap} supporting {@link NavigableMap} operations,
042 * and recursively so for its navigable sub-maps.
043 *
044 * <p>This interface is a member of the
045 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
046 * Java Collections Framework</a>.
047 *
048 * @author Doug Lea
049 * @param <K> the type of keys maintained by this map
050 * @param <V> the type of mapped values
051 * @since 1.6
052 */
053 public interface ConcurrentNavigableMap<K, V> extends
054 ConcurrentMap<K, V>, NavigableMap<K, V> {
055 /**
056 * @throws ClassCastException {@inheritDoc}
057 * @throws NullPointerException {@inheritDoc}
058 * @throws IllegalArgumentException {@inheritDoc}
059 */
060 ConcurrentNavigableMap<K, V> subMap(K fromKey,
061 boolean fromInclusive, K toKey, boolean toInclusive);
062
063 /**
064 * @throws ClassCastException {@inheritDoc}
065 * @throws NullPointerException {@inheritDoc}
066 * @throws IllegalArgumentException {@inheritDoc}
067 */
068 ConcurrentNavigableMap<K, V> headMap(K toKey, boolean inclusive);
069
070 /**
071 * @throws ClassCastException {@inheritDoc}
072 * @throws NullPointerException {@inheritDoc}
073 * @throws IllegalArgumentException {@inheritDoc}
074 */
075 ConcurrentNavigableMap<K, V> tailMap(K fromKey, boolean inclusive);
076
077 /**
078 * @throws ClassCastException {@inheritDoc}
079 * @throws NullPointerException {@inheritDoc}
080 * @throws IllegalArgumentException {@inheritDoc}
081 */
082 ConcurrentNavigableMap<K, V> subMap(K fromKey, K toKey);
083
084 /**
085 * @throws ClassCastException {@inheritDoc}
086 * @throws NullPointerException {@inheritDoc}
087 * @throws IllegalArgumentException {@inheritDoc}
088 */
089 ConcurrentNavigableMap<K, V> headMap(K toKey);
090
091 /**
092 * @throws ClassCastException {@inheritDoc}
093 * @throws NullPointerException {@inheritDoc}
094 * @throws IllegalArgumentException {@inheritDoc}
095 */
096 ConcurrentNavigableMap<K, V> tailMap(K fromKey);
097
098 /**
099 * Returns a reverse order view of the mappings contained in this map.
100 * The descending map is backed by this map, so changes to the map are
101 * reflected in the descending map, and vice-versa.
102 *
103 * <p>The returned map has an ordering equivalent to
104 * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
105 * The expression {@code m.descendingMap().descendingMap()} returns a
106 * view of {@code m} essentially equivalent to {@code m}.
107 *
108 * @return a reverse order view of this map
109 */
110 ConcurrentNavigableMap<K, V> descendingMap();
111
112 /**
113 * Returns a {@link NavigableSet} view of the keys contained in this map.
114 * The set's iterator returns the keys in ascending order.
115 * The set is backed by the map, so changes to the map are
116 * reflected in the set, and vice-versa. The set supports element
117 * removal, which removes the corresponding mapping from the map,
118 * via the {@code Iterator.remove}, {@code Set.remove},
119 * {@code removeAll}, {@code retainAll}, and {@code clear}
120 * operations. It does not support the {@code add} or {@code addAll}
121 * operations.
122 *
123 * <p>The view's {@code iterator} is a "weakly consistent" iterator
124 * that will never throw {@link ConcurrentModificationException},
125 * and guarantees to traverse elements as they existed upon
126 * construction of the iterator, and may (but is not guaranteed to)
127 * reflect any modifications subsequent to construction.
128 *
129 * @return a navigable set view of the keys in this map
130 */
131 public NavigableSet<K> navigableKeySet();
132
133 /**
134 * Returns a {@link NavigableSet} view of the keys contained in this map.
135 * The set's iterator returns the keys in ascending order.
136 * The set is backed by the map, so changes to the map are
137 * reflected in the set, and vice-versa. The set supports element
138 * removal, which removes the corresponding mapping from the map,
139 * via the {@code Iterator.remove}, {@code Set.remove},
140 * {@code removeAll}, {@code retainAll}, and {@code clear}
141 * operations. It does not support the {@code add} or {@code addAll}
142 * operations.
143 *
144 * <p>The view's {@code iterator} is a "weakly consistent" iterator
145 * that will never throw {@link ConcurrentModificationException},
146 * and guarantees to traverse elements as they existed upon
147 * construction of the iterator, and may (but is not guaranteed to)
148 * reflect any modifications subsequent to construction.
149 *
150 * <p>This method is equivalent to method {@code navigableKeySet}.
151 *
152 * @return a navigable set view of the keys in this map
153 */
154 NavigableSet<K> keySet();
155
156 /**
157 * Returns a reverse order {@link NavigableSet} view of the keys contained in this map.
158 * The set's iterator returns the keys in descending order.
159 * The set is backed by the map, so changes to the map are
160 * reflected in the set, and vice-versa. The set supports element
161 * removal, which removes the corresponding mapping from the map,
162 * via the {@code Iterator.remove}, {@code Set.remove},
163 * {@code removeAll}, {@code retainAll}, and {@code clear}
164 * operations. It does not support the {@code add} or {@code addAll}
165 * operations.
166 *
167 * <p>The view's {@code iterator} is a "weakly consistent" iterator
168 * that will never throw {@link ConcurrentModificationException},
169 * and guarantees to traverse elements as they existed upon
170 * construction of the iterator, and may (but is not guaranteed to)
171 * reflect any modifications subsequent to construction.
172 *
173 * @return a reverse order navigable set view of the keys in this map
174 */
175 public NavigableSet<K> descendingKeySet();
176 }
|