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}/../technotes/guides/collections/index.html">
 * 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.1
Committed:	Sat Mar 26 06:22:49 2016 UTC (8 years, 1 month ago) by jsr166
Branch:	MAIN
CVS Tags:	HEAD
Log Message:	fork jdk8 maintenance branch for source and jtreg tests
#	User	Rev	Content
1	jsr166	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			* http://creativecommons.org/publicdomain/zero/1.0/
5			*/
6
7			package java.util.concurrent;
8
9			import java.util.NavigableMap;
10			import java.util.NavigableSet;
11
12			/**
13			* A {@link ConcurrentMap} supporting {@link NavigableMap} operations,
14			* and recursively so for its navigable sub-maps.
15			*
16			* <p>This interface is a member of the
17			* <a href="{@docRoot}/../technotes/guides/collections/index.html">
18			* Java Collections Framework</a>.
19			*
20			* @author Doug Lea
21			* @param <K> the type of keys maintained by this map
22			* @param <V> the type of mapped values
23			* @since 1.6
24			*/
25			public interface ConcurrentNavigableMap<K,V>
26			extends ConcurrentMap<K,V>, NavigableMap<K,V>
27			{
28			/**
29			* @throws ClassCastException {@inheritDoc}
30			* @throws NullPointerException {@inheritDoc}
31			* @throws IllegalArgumentException {@inheritDoc}
32			*/
33			ConcurrentNavigableMap<K,V> subMap(K fromKey, boolean fromInclusive,
34			K toKey, boolean toInclusive);
35
36			/**
37			* @throws ClassCastException {@inheritDoc}
38			* @throws NullPointerException {@inheritDoc}
39			* @throws IllegalArgumentException {@inheritDoc}
40			*/
41			ConcurrentNavigableMap<K,V> headMap(K toKey, boolean inclusive);
42
43			/**
44			* @throws ClassCastException {@inheritDoc}
45			* @throws NullPointerException {@inheritDoc}
46			* @throws IllegalArgumentException {@inheritDoc}
47			*/
48			ConcurrentNavigableMap<K,V> tailMap(K fromKey, boolean inclusive);
49
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			/**
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			* {@link java.util.Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
78			* 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			ConcurrentNavigableMap<K,V> descendingMap();
84
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			* <p>The view's iterators and spliterators are
97			* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
98			*
99			* @return a navigable set view of the keys in this map
100			*/
101			NavigableSet<K> navigableKeySet();
102
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			* <p>The view's iterators and spliterators are
115			* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
116			*
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			* <p>The view's iterators and spliterators are
135			* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
136			*
137			* @return a reverse order navigable set view of the keys in this map
138			*/
139			NavigableSet<K> descendingKeySet();
140			}