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.*;

/**
 * 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
     * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
     * 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 {@code iterator} is a "weakly consistent" iterator
     * that will never throw {@link ConcurrentModificationException},
     * and guarantees to traverse elements as they existed upon
     * construction of the iterator, and may (but is not guaranteed to)
     * reflect any modifications subsequent to construction.
     *
     * @return a navigable set view of the keys in this map
     */
    public 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 {@code iterator} is a "weakly consistent" iterator
     * that will never throw {@link ConcurrentModificationException},
     * and guarantees to traverse elements as they existed upon
     * construction of the iterator, and may (but is not guaranteed to)
     * reflect any modifications subsequent to construction.
     *
     * <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 {@code iterator} is a "weakly consistent" iterator
     * that will never throw {@link ConcurrentModificationException},
     * and guarantees to traverse elements as they existed upon
     * construction of the iterator, and may (but is not guaranteed to)
     * reflect any modifications subsequent to construction.
     *
     * @return a reverse order navigable set view of the keys in this map
     */
    public NavigableSet<K> descendingKeySet();
}
Revision:	1.1
Committed:	Sun Dec 16 20:55:15 2012 UTC (11 years, 5 months ago) by dl
Branch:	MAIN
Log Message:	Create src/jdk7 package
#	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			* http://creativecommons.org/publicdomain/zero/1.0/
5			*/
6
7			package java.util.concurrent;
8			import java.util.*;
9
10			/**
11			* A {@link ConcurrentMap} supporting {@link NavigableMap} operations,
12			* and recursively so for its navigable sub-maps.
13			*
14			* <p>This interface is a member of the
15			* <a href="{@docRoot}/../technotes/guides/collections/index.html">
16			* Java Collections Framework</a>.
17			*
18			* @author Doug Lea
19			* @param <K> the type of keys maintained by this map
20			* @param <V> the type of mapped values
21			* @since 1.6
22			*/
23			public interface ConcurrentNavigableMap<K,V>
24			extends ConcurrentMap<K,V>, NavigableMap<K,V>
25			{
26			/**
27			* @throws ClassCastException {@inheritDoc}
28			* @throws NullPointerException {@inheritDoc}
29			* @throws IllegalArgumentException {@inheritDoc}
30			*/
31			ConcurrentNavigableMap<K,V> subMap(K fromKey, boolean fromInclusive,
32			K toKey, boolean toInclusive);
33
34			/**
35			* @throws ClassCastException {@inheritDoc}
36			* @throws NullPointerException {@inheritDoc}
37			* @throws IllegalArgumentException {@inheritDoc}
38			*/
39			ConcurrentNavigableMap<K,V> headMap(K toKey, boolean inclusive);
40
41			/**
42			* @throws ClassCastException {@inheritDoc}
43			* @throws NullPointerException {@inheritDoc}
44			* @throws IllegalArgumentException {@inheritDoc}
45			*/
46			ConcurrentNavigableMap<K,V> tailMap(K fromKey, boolean inclusive);
47
48			/**
49			* @throws ClassCastException {@inheritDoc}
50			* @throws NullPointerException {@inheritDoc}
51			* @throws IllegalArgumentException {@inheritDoc}
52			*/
53			ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey);
54
55			/**
56			* @throws ClassCastException {@inheritDoc}
57			* @throws NullPointerException {@inheritDoc}
58			* @throws IllegalArgumentException {@inheritDoc}
59			*/
60			ConcurrentNavigableMap<K,V> headMap(K toKey);
61
62			/**
63			* @throws ClassCastException {@inheritDoc}
64			* @throws NullPointerException {@inheritDoc}
65			* @throws IllegalArgumentException {@inheritDoc}
66			*/
67			ConcurrentNavigableMap<K,V> tailMap(K fromKey);
68
69			/**
70			* Returns a reverse order view of the mappings contained in this map.
71			* The descending map is backed by this map, so changes to the map are
72			* reflected in the descending map, and vice-versa.
73			*
74			* <p>The returned map has an ordering equivalent to
75			* <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
76			* The expression {@code m.descendingMap().descendingMap()} returns a
77			* view of {@code m} essentially equivalent to {@code m}.
78			*
79			* @return a reverse order view of this map
80			*/
81			ConcurrentNavigableMap<K,V> descendingMap();
82
83			/**
84			* Returns a {@link NavigableSet} view of the keys contained in this map.
85			* The set's iterator returns the keys in ascending order.
86			* The set is backed by the map, so changes to the map are
87			* reflected in the set, and vice-versa. The set supports element
88			* removal, which removes the corresponding mapping from the map,
89			* via the {@code Iterator.remove}, {@code Set.remove},
90			* {@code removeAll}, {@code retainAll}, and {@code clear}
91			* operations. It does not support the {@code add} or {@code addAll}
92			* operations.
93			*
94			* <p>The view's {@code iterator} is a "weakly consistent" iterator
95			* that will never throw {@link ConcurrentModificationException},
96			* and guarantees to traverse elements as they existed upon
97			* construction of the iterator, and may (but is not guaranteed to)
98			* reflect any modifications subsequent to construction.
99			*
100			* @return a navigable set view of the keys in this map
101			*/
102			public NavigableSet<K> navigableKeySet();
103
104			/**
105			* Returns a {@link NavigableSet} view of the keys contained in this map.
106			* The set's iterator returns the keys in ascending order.
107			* The set is backed by the map, so changes to the map are
108			* reflected in the set, and vice-versa. The set supports element
109			* removal, which removes the corresponding mapping from the map,
110			* via the {@code Iterator.remove}, {@code Set.remove},
111			* {@code removeAll}, {@code retainAll}, and {@code clear}
112			* operations. It does not support the {@code add} or {@code addAll}
113			* operations.
114			*
115			* <p>The view's {@code iterator} is a "weakly consistent" iterator
116			* that will never throw {@link ConcurrentModificationException},
117			* and guarantees to traverse elements as they existed upon
118			* construction of the iterator, and may (but is not guaranteed to)
119			* reflect any modifications subsequent to construction.
120			*
121			* <p>This method is equivalent to method {@code navigableKeySet}.
122			*
123			* @return a navigable set view of the keys in this map
124			*/
125			NavigableSet<K> keySet();
126
127			/**
128			* Returns a reverse order {@link NavigableSet} view of the keys contained in this map.
129			* The set's iterator returns the keys in descending order.
130			* The set is backed by the map, so changes to the map are
131			* reflected in the set, and vice-versa. The set supports element
132			* removal, which removes the corresponding mapping from the map,
133			* via the {@code Iterator.remove}, {@code Set.remove},
134			* {@code removeAll}, {@code retainAll}, and {@code clear}
135			* operations. It does not support the {@code add} or {@code addAll}
136			* operations.
137			*
138			* <p>The view's {@code iterator} is a "weakly consistent" iterator
139			* that will never throw {@link ConcurrentModificationException},
140			* and guarantees to traverse elements as they existed upon
141			* construction of the iterator, and may (but is not guaranteed to)
142			* reflect any modifications subsequent to construction.
143			*
144			* @return a reverse order navigable set view of the keys in this map
145			*/
146			public NavigableSet<K> descendingKeySet();
147			}