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 
36 package java.util.concurrent;
37 
38 import java.util.NavigableMap;
39 import java.util.NavigableSet;
40 
41 // BEGIN android-note
42 // removed link to collections framework docs
43 // END android-note
44 
45 /**
46  * A {@link ConcurrentMap} supporting {@link NavigableMap} operations,
47  * and recursively so for its navigable sub-maps.
48  *
49  * @author Doug Lea
50  * @param <K> the type of keys maintained by this map
51  * @param <V> the type of mapped values
52  * @since 1.6
53  */
54 public interface ConcurrentNavigableMap<K,V>
55     extends ConcurrentMap<K,V>, NavigableMap<K,V>
56 {
57     /**
58      * @throws ClassCastException       {@inheritDoc}
59      * @throws NullPointerException     {@inheritDoc}
60      * @throws IllegalArgumentException {@inheritDoc}
61      */
subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)62     ConcurrentNavigableMap<K,V> subMap(K fromKey, boolean fromInclusive,
63                                        K toKey,   boolean toInclusive);
64 
65     /**
66      * @throws ClassCastException       {@inheritDoc}
67      * @throws NullPointerException     {@inheritDoc}
68      * @throws IllegalArgumentException {@inheritDoc}
69      */
headMap(K toKey, boolean inclusive)70     ConcurrentNavigableMap<K,V> headMap(K toKey, boolean inclusive);
71 
72     /**
73      * @throws ClassCastException       {@inheritDoc}
74      * @throws NullPointerException     {@inheritDoc}
75      * @throws IllegalArgumentException {@inheritDoc}
76      */
tailMap(K fromKey, boolean inclusive)77     ConcurrentNavigableMap<K,V> tailMap(K fromKey, boolean inclusive);
78 
79     /**
80      * @throws ClassCastException       {@inheritDoc}
81      * @throws NullPointerException     {@inheritDoc}
82      * @throws IllegalArgumentException {@inheritDoc}
83      */
subMap(K fromKey, K toKey)84     ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey);
85 
86     /**
87      * @throws ClassCastException       {@inheritDoc}
88      * @throws NullPointerException     {@inheritDoc}
89      * @throws IllegalArgumentException {@inheritDoc}
90      */
headMap(K toKey)91     ConcurrentNavigableMap<K,V> headMap(K toKey);
92 
93     /**
94      * @throws ClassCastException       {@inheritDoc}
95      * @throws NullPointerException     {@inheritDoc}
96      * @throws IllegalArgumentException {@inheritDoc}
97      */
tailMap(K fromKey)98     ConcurrentNavigableMap<K,V> tailMap(K fromKey);
99 
100     /**
101      * Returns a reverse order view of the mappings contained in this map.
102      * The descending map is backed by this map, so changes to the map are
103      * reflected in the descending map, and vice-versa.
104      *
105      * <p>The returned map has an ordering equivalent to
106      * {@link java.util.Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
107      * The expression {@code m.descendingMap().descendingMap()} returns a
108      * view of {@code m} essentially equivalent to {@code m}.
109      *
110      * @return a reverse order view of this map
111      */
descendingMap()112     ConcurrentNavigableMap<K,V> descendingMap();
113 
114     /**
115      * Returns a {@link NavigableSet} view of the keys contained in this map.
116      * The set's iterator returns the keys in ascending order.
117      * The set is backed by the map, so changes to the map are
118      * reflected in the set, and vice-versa.  The set supports element
119      * removal, which removes the corresponding mapping from the map,
120      * via the {@code Iterator.remove}, {@code Set.remove},
121      * {@code removeAll}, {@code retainAll}, and {@code clear}
122      * operations.  It does not support the {@code add} or {@code addAll}
123      * operations.
124      *
125      * <p>The view's iterators and spliterators are
126      * <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
127      *
128      * @return a navigable set view of the keys in this map
129      */
navigableKeySet()130     NavigableSet<K> navigableKeySet();
131 
132     /**
133      * Returns a {@link NavigableSet} view of the keys contained in this map.
134      * The set's iterator returns the keys in ascending order.
135      * The set is backed by the map, so changes to the map are
136      * reflected in the set, and vice-versa.  The set supports element
137      * removal, which removes the corresponding mapping from the map,
138      * via the {@code Iterator.remove}, {@code Set.remove},
139      * {@code removeAll}, {@code retainAll}, and {@code clear}
140      * operations.  It does not support the {@code add} or {@code addAll}
141      * operations.
142      *
143      * <p>The view's iterators and spliterators are
144      * <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
145      *
146      * <p>This method is equivalent to method {@code navigableKeySet}.
147      *
148      * @return a navigable set view of the keys in this map
149      */
keySet()150     NavigableSet<K> keySet();
151 
152     /**
153      * Returns a reverse order {@link NavigableSet} view of the keys contained in this map.
154      * The set's iterator returns the keys in descending order.
155      * The set is backed by the map, so changes to the map are
156      * reflected in the set, and vice-versa.  The set supports element
157      * removal, which removes the corresponding mapping from the map,
158      * via the {@code Iterator.remove}, {@code Set.remove},
159      * {@code removeAll}, {@code retainAll}, and {@code clear}
160      * operations.  It does not support the {@code add} or {@code addAll}
161      * operations.
162      *
163      * <p>The view's iterators and spliterators are
164      * <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
165      *
166      * @return a reverse order navigable set view of the keys in this map
167      */
descendingKeySet()168     NavigableSet<K> descendingKeySet();
169 }
170