util/concurrent/ConcurrentNavigableMap.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util.concurrent;

import java.util.NavigableMap;
import java.util.NavigableSet;

/**
 * A {@link ConcurrentMap} supporting {@link NavigableMap} operations,
 * and recursively so for its navigable sub-maps.
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
 * Java Collections Framework</a>.
 *
 * @author Doug Lea
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 * @since 1.6
 */
public interface ConcurrentNavigableMap<K,V>
    extends ConcurrentMap<K,V>, NavigableMap<K,V>
{
    /**
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ConcurrentNavigableMap<K,V> subMap(K fromKey, boolean fromInclusive,
                                       K toKey,   boolean toInclusive);

    /**
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ConcurrentNavigableMap<K,V> headMap(K toKey, boolean inclusive);

    /**
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ConcurrentNavigableMap<K,V> tailMap(K fromKey, boolean inclusive);

    /**
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey);

    /**
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ConcurrentNavigableMap<K,V> headMap(K toKey);

    /**
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ConcurrentNavigableMap<K,V> tailMap(K fromKey);

    /**
     * Returns a reverse order view of the mappings contained in this map.
     * The descending map is backed by this map, so changes to the map are
     * reflected in the descending map, and vice-versa.
     *
     * <p>The returned map has an ordering equivalent to
     * {@link java.util.Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
     * The expression {@code m.descendingMap().descendingMap()} returns a
     * view of {@code m} essentially equivalent to {@code m}.
     *
     * @return a reverse order view of this map
     */
    ConcurrentNavigableMap<K,V> descendingMap();

    /**
     * Returns a {@link NavigableSet} view of the keys contained in this map.
     * The set's iterator returns the keys in ascending order.
     * The set is backed by the map, so changes to the map are
     * reflected in the set, and vice-versa.  The set supports element
     * removal, which removes the corresponding mapping from the map,
     * via the {@code Iterator.remove}, {@code Set.remove},
     * {@code removeAll}, {@code retainAll}, and {@code clear}
     * operations.  It does not support the {@code add} or {@code addAll}
     * operations.
     *
     * <p>The view's iterators and spliterators are
     * <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
     *
     * @return a navigable set view of the keys in this map
     */
    NavigableSet<K> navigableKeySet();

    /**
     * Returns a {@link NavigableSet} view of the keys contained in this map.
     * The set's iterator returns the keys in ascending order.
     * The set is backed by the map, so changes to the map are
     * reflected in the set, and vice-versa.  The set supports element
     * removal, which removes the corresponding mapping from the map,
     * via the {@code Iterator.remove}, {@code Set.remove},
     * {@code removeAll}, {@code retainAll}, and {@code clear}
     * operations.  It does not support the {@code add} or {@code addAll}
     * operations.
     *
     * <p>The view's iterators and spliterators are
     * <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
     *
     * <p>This method is equivalent to method {@code navigableKeySet}.
     *
     * @return a navigable set view of the keys in this map
     */
    NavigableSet<K> keySet();

    /**
     * Returns a reverse order {@link NavigableSet} view of the keys contained in this map.
     * The set's iterator returns the keys in descending order.
     * The set is backed by the map, so changes to the map are
     * reflected in the set, and vice-versa.  The set supports element
     * removal, which removes the corresponding mapping from the map,
     * via the {@code Iterator.remove}, {@code Set.remove},
     * {@code removeAll}, {@code retainAll}, and {@code clear}
     * operations.  It does not support the {@code add} or {@code addAll}
     * operations.
     *
     * <p>The view's iterators and spliterators are
     * <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
     *
     * @return a reverse order navigable set view of the keys in this map
     */
    NavigableSet<K> descendingKeySet();
}
Revision:	1.20
Committed:	Mon Oct 1 00:10:53 2018 UTC (5 years, 8 months ago) by jsr166
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.19:	+1 -1 lines
Log Message:	update to using jdk11 by default, except link to jdk10 javadocs; sync @docRoot references in javadoc with upstream
#	User	Rev	Content
1	dl	1.1	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain, as explained at
4	jsr166	1.12	* http://creativecommons.org/publicdomain/zero/1.0/
5	dl	1.1	*/
6
7			package java.util.concurrent;
8	jsr166	1.17
9			import java.util.NavigableMap;
10			import java.util.NavigableSet;
11	dl	1.1
12			/**
13	dl	1.5	* A {@link ConcurrentMap} supporting {@link NavigableMap} operations,
14			* and recursively so for its navigable sub-maps.
15	dl	1.1	*
16	jsr166	1.3	* <p>This interface is a member of the
17	jsr166	1.20	* <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
18	jsr166	1.3	* Java Collections Framework</a>.
19			*
20	dl	1.1	* @author Doug Lea
21			* @param <K> the type of keys maintained by this map
22	jsr166	1.3	* @param <V> the type of mapped values
23			* @since 1.6
24	dl	1.1	*/
25	jsr166	1.3	public interface ConcurrentNavigableMap<K,V>
26			extends ConcurrentMap<K,V>, NavigableMap<K,V>
27			{
28	dl	1.1	/**
29	jsr166	1.3	* @throws ClassCastException {@inheritDoc}
30	jsr166	1.4	* @throws NullPointerException {@inheritDoc}
31	jsr166	1.3	* @throws IllegalArgumentException {@inheritDoc}
32	dl	1.1	*/
33	dl	1.9	ConcurrentNavigableMap<K,V> subMap(K fromKey, boolean fromInclusive,
34			K toKey, boolean toInclusive);
35	dl	1.1
36			/**
37	jsr166	1.3	* @throws ClassCastException {@inheritDoc}
38	jsr166	1.4	* @throws NullPointerException {@inheritDoc}
39	jsr166	1.3	* @throws IllegalArgumentException {@inheritDoc}
40	dl	1.1	*/
41	dl	1.9	ConcurrentNavigableMap<K,V> headMap(K toKey, boolean inclusive);
42	dl	1.8
43	dl	1.1	/**
44	jsr166	1.3	* @throws ClassCastException {@inheritDoc}
45	jsr166	1.4	* @throws NullPointerException {@inheritDoc}
46	jsr166	1.3	* @throws IllegalArgumentException {@inheritDoc}
47	dl	1.1	*/
48	dl	1.9	ConcurrentNavigableMap<K,V> tailMap(K fromKey, boolean inclusive);
49	dl	1.5
50			/**
51			* @throws ClassCastException {@inheritDoc}
52			* @throws NullPointerException {@inheritDoc}
53			* @throws IllegalArgumentException {@inheritDoc}
54			*/
55			ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey);
56
57			/**
58			* @throws ClassCastException {@inheritDoc}
59			* @throws NullPointerException {@inheritDoc}
60			* @throws IllegalArgumentException {@inheritDoc}
61			*/
62			ConcurrentNavigableMap<K,V> headMap(K toKey);
63
64			/**
65			* @throws ClassCastException {@inheritDoc}
66			* @throws NullPointerException {@inheritDoc}
67			* @throws IllegalArgumentException {@inheritDoc}
68			*/
69			ConcurrentNavigableMap<K,V> tailMap(K fromKey);
70
71	jsr166	1.11	/**
72			* Returns a reverse order view of the mappings contained in this map.
73			* The descending map is backed by this map, so changes to the map are
74			* reflected in the descending map, and vice-versa.
75			*
76			* <p>The returned map has an ordering equivalent to
77	jsr166	1.17	* {@link java.util.Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
78	jsr166	1.11	* The expression {@code m.descendingMap().descendingMap()} returns a
79			* view of {@code m} essentially equivalent to {@code m}.
80			*
81			* @return a reverse order view of this map
82			*/
83	dl	1.8	ConcurrentNavigableMap<K,V> descendingMap();
84	jsr166	1.11
85			/**
86			* Returns a {@link NavigableSet} view of the keys contained in this map.
87			* The set's iterator returns the keys in ascending order.
88			* The set is backed by the map, so changes to the map are
89			* reflected in the set, and vice-versa. The set supports element
90			* removal, which removes the corresponding mapping from the map,
91			* via the {@code Iterator.remove}, {@code Set.remove},
92			* {@code removeAll}, {@code retainAll}, and {@code clear}
93			* operations. It does not support the {@code add} or {@code addAll}
94			* operations.
95			*
96	jsr166	1.16	* <p>The view's iterators and spliterators are
97			* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
98	jsr166	1.11	*
99			* @return a navigable set view of the keys in this map
100			*/
101	jsr166	1.18	NavigableSet<K> navigableKeySet();
102	jsr166	1.11
103			/**
104			* Returns a {@link NavigableSet} view of the keys contained in this map.
105			* The set's iterator returns the keys in ascending order.
106			* The set is backed by the map, so changes to the map are
107			* reflected in the set, and vice-versa. The set supports element
108			* removal, which removes the corresponding mapping from the map,
109			* via the {@code Iterator.remove}, {@code Set.remove},
110			* {@code removeAll}, {@code retainAll}, and {@code clear}
111			* operations. It does not support the {@code add} or {@code addAll}
112			* operations.
113			*
114	jsr166	1.16	* <p>The view's iterators and spliterators are
115			* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
116	jsr166	1.11	*
117			* <p>This method is equivalent to method {@code navigableKeySet}.
118			*
119			* @return a navigable set view of the keys in this map
120			*/
121			NavigableSet<K> keySet();
122
123			/**
124			* Returns a reverse order {@link NavigableSet} view of the keys contained in this map.
125			* The set's iterator returns the keys in descending order.
126			* The set is backed by the map, so changes to the map are
127			* reflected in the set, and vice-versa. The set supports element
128			* removal, which removes the corresponding mapping from the map,
129			* via the {@code Iterator.remove}, {@code Set.remove},
130			* {@code removeAll}, {@code retainAll}, and {@code clear}
131			* operations. It does not support the {@code add} or {@code addAll}
132			* operations.
133			*
134	jsr166	1.16	* <p>The view's iterators and spliterators are
135			* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
136	jsr166	1.11	*
137			* @return a reverse order navigable set view of the keys in this map
138			*/
139	jsr166	1.18	NavigableSet<K> descendingKeySet();
140	dl	1.1	}