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.6
Committed:	Sat Dec 29 23:55:19 2012 UTC (11 years, 4 months ago) by jsr166
Branch:	MAIN
Changes since 1.5:	+14 -14 lines
Log Message:	punctuation
#	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	jsr166	1.4	*
27	jsr166	1.6	* @param fromKey low endpoint (inclusive) of the subMap
28			* @param toKey high endpoint (exclusive) of the subMap
29	dl	1.1	*
30			* @return a view of the portion of this map whose keys range from
31	jsr166	1.6	* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive
32	dl	1.1	*
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	jsr166	1.6	* natural ordering)
37	dl	1.1	* @throws IllegalArgumentException if <tt>fromKey</tt> is greater
38	jsr166	1.6	* than <tt>toKey</tt>
39	dl	1.1	* @throws NullPointerException if <tt>fromKey</tt> or
40			* <tt>toKey</tt> is <tt>null</tt> and this map does not support
41	jsr166	1.6	* <tt>null</tt> keys
42	dl	1.1	*/
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	jsr166	1.6	* @param toKey high endpoint (exclusive) of the headMap
51	dl	1.1	* @return a view of the portion of this map whose keys are strictly
52	jsr166	1.6	* less than <tt>toKey</tt>
53	dl	1.1	*
54			* @throws ClassCastException if <tt>toKey</tt> is not compatible
55			* with this map's comparator (or, if the map has no comparator,
56	jsr166	1.6	* if <tt>toKey</tt> does not implement <tt>Comparable</tt>)
57	dl	1.1	* @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>
58	jsr166	1.6	* and this map does not support <tt>null</tt> keys
59	dl	1.1	*/
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	jsr166	1.6	* @param fromKey low endpoint (inclusive) of the tailMap
68	dl	1.1	* @return a view of the portion of this map whose keys are greater
69	jsr166	1.6	* than or equal to <tt>fromKey</tt>
70	dl	1.1	* @throws ClassCastException if <tt>fromKey</tt> is not compatible
71			* with this map's comparator (or, if the map has no comparator,
72	jsr166	1.6	* if <tt>fromKey</tt> does not implement <tt>Comparable</tt>)
73	dl	1.1	* @throws NullPointerException if <tt>fromKey</tt> is <tt>null</tt>
74	jsr166	1.6	* and this map does not support <tt>null</tt> keys
75	dl	1.1	*/
76	jsr166	1.5	public ConcurrentNavigableMap<K,V> tailMap(K fromKey);
77	dl	1.1	}