src/jsr166x/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 jsr166x;

import java.util.*;
import java.util.concurrent.*;

/**
 * A {@link ConcurrentMap} supporting {@link NavigableMap} operations.
 *
 * @author Doug Lea
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
public interface ConcurrentNavigableMap<K,V> extends ConcurrentMap<K,V>, NavigableMap<K,V> {
    /**
     * Returns a view of the portion of this map whose keys range from
     * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.  (If
     * <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned sorted map
     * is empty.)  The returned sorted map is backed by this map, so changes
     * in the returned sorted map are reflected in this map, and vice-versa.

     * @param fromKey low endpoint (inclusive) of the subMap.
     * @param toKey high endpoint (exclusive) of the subMap.
     *
     * @return a view of the portion of this map whose keys range from
     * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.
     *
     * @throws ClassCastException if <tt>fromKey</tt> and
     * <tt>toKey</tt> cannot be compared to one another using this
     * map's comparator (or, if the map has no comparator, using
     * natural ordering).
     * @throws IllegalArgumentException if <tt>fromKey</tt> is greater
     * than <tt>toKey</tt>.
     * @throws NullPointerException if <tt>fromKey</tt> or
     * <tt>toKey</tt> is <tt>null</tt> and this map does not support
     * <tt>null</tt> keys.
     */
    public ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey);

    /**
     * Returns a view of the portion of this map whose keys are strictly less
     * than <tt>toKey</tt>.  The returned sorted map is backed by this map, so
     * changes in the returned sorted map are reflected in this map, and
     * vice-versa.
     * @param toKey high endpoint (exclusive) of the headMap.
     * @return a view of the portion of this map whose keys are strictly
     *                less than <tt>toKey</tt>.
     *
     * @throws ClassCastException if <tt>toKey</tt> is not compatible
     *         with this map's comparator (or, if the map has no comparator,
     *         if <tt>toKey</tt> does not implement <tt>Comparable</tt>).
     * @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>
     * and this map does not support <tt>null</tt> keys.
     */
    public ConcurrentNavigableMap<K,V> headMap(K toKey);

    /**
     * Returns a view of the portion of this map whose keys are
     * greater than or equal to <tt>fromKey</tt>.  The returned sorted
     * map is backed by this map, so changes in the returned sorted
     * map are reflected in this map, and vice-versa.
     * @param fromKey low endpoint (inclusive) of the tailMap.
     * @return a view of the portion of this map whose keys are greater
     *                than or equal to <tt>fromKey</tt>.
     * @throws ClassCastException if <tt>fromKey</tt> is not compatible
     *         with this map's comparator (or, if the map has no comparator,
     *         if <tt>fromKey</tt> does not implement <tt>Comparable</tt>).
     * @throws NullPointerException if <tt>fromKey</tt> is <tt>null</tt>
     * and this map does not support <tt>null</tt> keys.
     */
    public ConcurrentNavigableMap<K,V>  tailMap(K fromKey);
}
Revision:	1.3
Committed:	Tue Mar 15 19:47:02 2011 UTC (13 years, 1 month ago) by jsr166
Branch:	MAIN
Changes since 1.2:	+1 -1 lines
Log Message:	Update Creative Commons license URL in legal notices
#	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.3	* http://creativecommons.org/publicdomain/zero/1.0/
5	dl	1.1	*/
6
7			package jsr166x;
8
9			import java.util.*;
10			import java.util.concurrent.*;
11
12			/**
13			* A {@link ConcurrentMap} supporting {@link NavigableMap} operations.
14			*
15			* @author Doug Lea
16			* @param <K> the type of keys maintained by this map
17	jsr166	1.2	* @param <V> the type of mapped values
18	dl	1.1	*/
19			public interface ConcurrentNavigableMap<K,V> extends ConcurrentMap<K,V>, NavigableMap<K,V> {
20			/**
21			* Returns a view of the portion of this map whose keys range from
22			* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive. (If
23			* <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned sorted map
24			* is empty.) The returned sorted map is backed by this map, so changes
25			* in the returned sorted map are reflected in this map, and vice-versa.
26
27			* @param fromKey low endpoint (inclusive) of the subMap.
28			* @param toKey high endpoint (exclusive) of the subMap.
29			*
30			* @return a view of the portion of this map whose keys range from
31			* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.
32			*
33			* @throws ClassCastException if <tt>fromKey</tt> and
34			* <tt>toKey</tt> cannot be compared to one another using this
35			* map's comparator (or, if the map has no comparator, using
36			* natural ordering).
37			* @throws IllegalArgumentException if <tt>fromKey</tt> is greater
38			* than <tt>toKey</tt>.
39			* @throws NullPointerException if <tt>fromKey</tt> or
40			* <tt>toKey</tt> is <tt>null</tt> and this map does not support
41			* <tt>null</tt> keys.
42			*/
43			public ConcurrentNavigableMap<K,V> subMap(K fromKey, K toKey);
44
45			/**
46			* Returns a view of the portion of this map whose keys are strictly less
47			* than <tt>toKey</tt>. The returned sorted map is backed by this map, so
48			* changes in the returned sorted map are reflected in this map, and
49	jsr166	1.2	* vice-versa.
50	dl	1.1	* @param toKey high endpoint (exclusive) of the headMap.
51			* @return a view of the portion of this map whose keys are strictly
52			* less than <tt>toKey</tt>.
53			*
54			* @throws ClassCastException if <tt>toKey</tt> is not compatible
55			* with this map's comparator (or, if the map has no comparator,
56			* if <tt>toKey</tt> does not implement <tt>Comparable</tt>).
57			* @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>
58			* and this map does not support <tt>null</tt> keys.
59			*/
60			public ConcurrentNavigableMap<K,V> headMap(K toKey);
61
62			/**
63			* Returns a view of the portion of this map whose keys are
64			* greater than or equal to <tt>fromKey</tt>. The returned sorted
65			* map is backed by this map, so changes in the returned sorted
66			* map are reflected in this map, and vice-versa.
67			* @param fromKey low endpoint (inclusive) of the tailMap.
68			* @return a view of the portion of this map whose keys are greater
69			* than or equal to <tt>fromKey</tt>.
70			* @throws ClassCastException if <tt>fromKey</tt> is not compatible
71			* with this map's comparator (or, if the map has no comparator,
72			* if <tt>fromKey</tt> does not implement <tt>Comparable</tt>).
73			* @throws NullPointerException if <tt>fromKey</tt> is <tt>null</tt>
74			* and this map does not support <tt>null</tt> keys.
75			*/
76			public ConcurrentNavigableMap<K,V> tailMap(K fromKey);
77			}