java/util/NavigableMap.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/licenses/publicdomain
 */

package java.util;

/**
 * A {@link SortedMap} extended with navigation methods returning the
 * closest matches for given search targets. Methods
 * <tt>lowerEntry</tt>, <tt>floorEntry</tt>, <tt>ceilingEntry</tt>,
 * and <tt>higherEntry</tt> return <tt>Map.Entry</tt> objects
 * associated with keys respectively less than, less than or equal,
 * greater than or equal, and greater than a given key, returning
 * <tt>null</tt> if there is no such key.  Similarly, methods
 * <tt>lowerKey</tt>, <tt>floorKey</tt>, <tt>ceilingKey</tt>, and
 * <tt>higherKey</tt> return only the associated keys. All of these
 * methods are designed for locating, not traversing entries.
 *
 * <p>A <tt>NavigableMap</tt> may be viewed and traversed in either
 * ascending or descending key order.  The <tt>Map</tt> methods
 * <tt>keySet</tt> and <tt>entrySet</tt> return ascending views, and
 * the additional methods <tt>descendingKeySet</tt> and
 * <tt>descendingEntrySet</tt> return descending views. The
 * performance of ascending traversals is likely to be faster than
 * descending traversals.  Notice that it is possible to perform
 * subrange traversals in either direction using <tt>navigableSubMap</tt>.
 * Methods <tt>navigableSubMap</tt>, <tt>navigableHeadMap</tt>, and
 * <tt>navigableTailMap</tt> differ from the similarly named
 * <tt>SortedMap</tt> methods only in their declared return types.
 * Submaps of any <tt>NavigableMap</tt> must obey
 * the <tt>NavigableMap</tt> interface.
 *
 * <p>This interface additionally defines methods <tt>firstEntry</tt>,
 * <tt>pollFirstEntry</tt>, <tt>lastEntry</tt>, and
 * <tt>pollLastEntry</tt> that return and/or remove the least and
 * greatest mappings, if any exist, else returning <tt>null</tt>.
 *
 * <p> Implementations of entry-returning methods are expected to
 * return <tt>Map.Entry</tt> pairs representing snapshots of mappings
 * at the time they were produced, and thus generally do <em>not</em>
 * support the optional <tt>Entry.setValue</tt> method. Note however
 * that it is possible to change mappings in the associated map using
 * method <tt>put</tt>.
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/../guide/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 NavigableMap<K,V> extends SortedMap<K,V> {
    /**
     * Returns a key-value mapping associated with the greatest key
     * strictly less than the given key, or <tt>null</tt> if there is
     * no such key.
     *
     * @param key the key
     * @return an entry with the greatest key less than <tt>key</tt>,
     *         or <tt>null</tt> if there is no such key
     * @throws ClassCastException if the specified key cannot be compared
     *         with the keys currently in the map
     * @throws NullPointerException if the specified key is null
     *         and this map does not permit null keys
     */
    Map.Entry<K,V> lowerEntry(K key);

    /**
     * Returns the greatest key strictly less than the given key, or
     * <tt>null</tt> if there is no such key.
     *
     * @param key the key
     * @return the greatest key less than <tt>key</tt>,
     *         or <tt>null</tt> if there is no such key
     * @throws ClassCastException if the specified key cannot be compared
     *         with the keys currently in the map
     * @throws NullPointerException if the specified key is null
     *         and this map does not permit null keys
     */
    K lowerKey(K key);

    /**
     * Returns a key-value mapping associated with the greatest key
     * less than or equal to the given key, or <tt>null</tt> if there
     * is no such key.
     *
     * @param key the key
     * @return an entry with the greatest key less than or equal to
     *         <tt>key</tt>, or <tt>null</tt> if there is no such key
     * @throws ClassCastException if the specified key cannot be compared
     *         with the keys currently in the map
     * @throws NullPointerException if the specified key is null
     *         and this map does not permit null keys
     */
    Map.Entry<K,V> floorEntry(K key);

    /**
     * Returns the greatest key less than or equal to the given key,
     * or <tt>null</tt> if there is no such key.
     *
     * @param key the key
     * @return the greatest key less than or equal to <tt>key</tt>,
     *         or <tt>null</tt> if there is no such key
     * @throws ClassCastException if the specified key cannot be compared
     *         with the keys currently in the map
     * @throws NullPointerException if the specified key is null
     *         and this map does not permit null keys
     */
    K floorKey(K key);

    /**
     * Returns a key-value mapping associated with the least key
     * greater than or equal to the given key, or <tt>null</tt> if
     * there is no such key.
     *
     * @param key the key
     * @return an entry with the least key greater than or equal to
     *         <tt>key</tt>, or <tt>null</tt> if there is no such key
     * @throws ClassCastException if the specified key cannot be compared
     *         with the keys currently in the map
     * @throws NullPointerException if the specified key is null
     *         and this map does not permit null keys
     */
    Map.Entry<K,V> ceilingEntry(K key);

    /**
     * Returns the least key greater than or equal to the given key,
     * or <tt>null</tt> if there is no such key.
     *
     * @param key the key
     * @return the least key greater than or equal to <tt>key</tt>,
     *         or <tt>null</tt> if there is no such key
     * @throws ClassCastException if the specified key cannot be compared
     *         with the keys currently in the map
     * @throws NullPointerException if the specified key is null
     *         and this map does not permit null keys
     */
    K ceilingKey(K key);

    /**
     * Returns a key-value mapping associated with the least key
     * strictly greater than the given key, or <tt>null</tt> if there
     * is no such key.
     *
     * @param key the key
     * @return an entry with the least key greater than <tt>key</tt>,
     *         or <tt>null</tt> if there is no such key
     * @throws ClassCastException if the specified key cannot be compared
     *         with the keys currently in the map
     * @throws NullPointerException if the specified key is null
     *         and this map does not permit null keys
     */
    Map.Entry<K,V> higherEntry(K key);

    /**
     * Returns the least key strictly greater than the given key, or
     * <tt>null</tt> if there is no such key.
     *
     * @param key the key
     * @return the least key greater than <tt>key</tt>,
     *         or <tt>null</tt> if there is no such key
     * @throws ClassCastException if the specified key cannot be compared
     *         with the keys currently in the map
     * @throws NullPointerException if the specified key is null
     *         and this map does not permit null keys
     */
    K higherKey(K key);

    /**
     * Returns a key-value mapping associated with the least
     * key in this map, or <tt>null</tt> if the map is empty.
     *
     * @return an entry with the least key,
     *         or <tt>null</tt> if this map is empty
     */
    Map.Entry<K,V> firstEntry();

    /**
     * Returns a key-value mapping associated with the greatest
     * key in this map, or <tt>null</tt> if the map is empty.
     *
     * @return an entry with the greatest key,
     *         or <tt>null</tt> if this map is empty
     */
    Map.Entry<K,V> lastEntry();

    /**
     * Removes and returns a key-value mapping associated with
     * the least key in this map, or <tt>null</tt> if the map is empty.
     *
     * @return the removed first entry of this map,
     *         or <tt>null</tt> if this map is empty
     */
    Map.Entry<K,V> pollFirstEntry();

    /**
     * Removes and returns a key-value mapping associated with
     * the greatest key in this map, or <tt>null</tt> if the map is empty.
     *
     * @return the removed last entry of this map,
     *         or <tt>null</tt> if this map is empty
     */
    Map.Entry<K,V> pollLastEntry();

    /**
     * Returns a {@link Set} 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.  If the map is modified
     * while an iteration over the set is in progress (except through
     * the iterator's own <tt>remove</tt> operation), the results of
     * the iteration are undefined.  The set supports element removal,
     * which removes the corresponding mapping from the map, via the
     * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
     * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
     * operations.  It does not support the <tt>add</tt> or <tt>addAll</tt>
     * operations.
     *
     * @return a set view of the keys contained in this map, sorted in
     *         descending order
     */
    Set<K> descendingKeySet();

    /**
     * Returns a {@link Set} view of the mappings contained in this map.
     * The set's iterator returns the entries in descending key order.
     * The set is backed by the map, so changes to the map are
     * reflected in the set, and vice-versa.  If the map is modified
     * while an iteration over the set is in progress (except through
     * the iterator's own <tt>remove</tt> operation, or through the
     * <tt>setValue</tt> operation on a map entry returned by the
     * iterator) the results of the iteration are undefined.  The set
     * supports element removal, which removes the corresponding
     * mapping from the map, via the <tt>Iterator.remove</tt>,
     * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
     * <tt>clear</tt> operations.  It does not support the
     * <tt>add</tt> or <tt>addAll</tt> operations.
     *
     * @return a set view of the mappings contained in this map,
     *         sorted in descending key order
     */
    Set<Map.Entry<K, V>> descendingEntrySet();

    /**
     * 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 map
     * is empty.)  The returned map is backed by this map, so changes
     * in the returned map are reflected in this map, and vice-versa.
     * The returned map supports all optional map operations that this
     * map supports.
     *
     * <p>The returned map will throw an <tt>IllegalArgumentException</tt>
     * on an attempt to insert a key outside its range.
     *
     * @param fromKey low endpoint (inclusive) of the keys in the returned map
     * @param toKey high endpoint (exclusive) of the keys in the returned map
     * @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).
     *         Implementations may, but are not required to, throw this
     *         exception if <tt>fromKey</tt> or <tt>toKey</tt>
     *         cannot be compared to keys currently in the map.
     * @throws NullPointerException if <tt>fromKey</tt> or <tt>toKey</tt>
     *         is null and this map does not permit null keys
     * @throws IllegalArgumentException if <tt>fromKey</tt> is greater than
     *         <tt>toKey</tt>; or if this map itself has a restricted
     *         range, and <tt>fromKey</tt> or <tt>toKey</tt> lies
     *         outside the bounds of the range
     */
    NavigableMap<K,V> navigableSubMap(K fromKey, K toKey);

    /**
     * Returns a view of the portion of this map whose keys are
     * strictly less than <tt>toKey</tt>.  The returned map is backed
     * by this map, so changes in the returned map are reflected in
     * this map, and vice-versa.  The returned map supports all
     * optional map operations that this map supports.
     *
     * <p>The returned map will throw an <tt>IllegalArgumentException</tt>
     * on an attempt to insert a key outside its range.
     *
     * @param toKey high endpoint (exclusive) of the keys in the returned map
     * @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 {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if <tt>toKey</tt> cannot be compared to keys
     *         currently in the map.
     * @throws NullPointerException if <tt>toKey</tt> is null
     *         and this map does not permit null keys
     * @throws IllegalArgumentException if this map itself has a
     *         restricted range, and <tt>toKey</tt> lies outside the
     *         bounds of the range
     */
    NavigableMap<K,V> navigableHeadMap(K toKey);

    /**
     * Returns a view of the portion of this map whose keys are
     * greater than or equal to <tt>fromKey</tt>.  The returned map is
     * backed by this map, so changes in the returned map are
     * reflected in this map, and vice-versa.  The returned map
     * supports all optional map operations that this map supports.
     *
     * <p>The returned map will throw an <tt>IllegalArgumentException</tt>
     * on an attempt to insert a key outside its range.
     *
     * @param fromKey low endpoint (inclusive) of the keys in the returned map
     * @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 {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if <tt>fromKey</tt> cannot be compared to keys
     *         currently in the map.
     * @throws NullPointerException if <tt>fromKey</tt> is null
     *         and this map does not permit null keys
     * @throws IllegalArgumentException if this map itself has a
     *         restricted range, and <tt>fromKey</tt> lies outside the
     *         bounds of the range
     */
    NavigableMap<K,V> navigableTailMap(K fromKey);
}
Revision:	1.10
Committed:	Mon Jul 18 19:32:38 2005 UTC (18 years, 9 months ago) by dl
Branch:	MAIN
Changes since 1.9:	+3 -2 lines
Log Message:	Clarify submap specs
#	Content
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/licenses/publicdomain
5	*/
6
7	package java.util;
8
9	/**
10	* A {@link SortedMap} extended with navigation methods returning the
11	* closest matches for given search targets. Methods
12	* <tt>lowerEntry</tt>, <tt>floorEntry</tt>, <tt>ceilingEntry</tt>,
13	* and <tt>higherEntry</tt> return <tt>Map.Entry</tt> objects
14	* associated with keys respectively less than, less than or equal,
15	* greater than or equal, and greater than a given key, returning
16	* <tt>null</tt> if there is no such key. Similarly, methods
17	* <tt>lowerKey</tt>, <tt>floorKey</tt>, <tt>ceilingKey</tt>, and
18	* <tt>higherKey</tt> return only the associated keys. All of these
19	* methods are designed for locating, not traversing entries.
20	*
21	* <p>A <tt>NavigableMap</tt> may be viewed and traversed in either
22	* ascending or descending key order. The <tt>Map</tt> methods
23	* <tt>keySet</tt> and <tt>entrySet</tt> return ascending views, and
24	* the additional methods <tt>descendingKeySet</tt> and
25	* <tt>descendingEntrySet</tt> return descending views. The
26	* performance of ascending traversals is likely to be faster than
27	* descending traversals. Notice that it is possible to perform
28	* subrange traversals in either direction using <tt>navigableSubMap</tt>.
29	* Methods <tt>navigableSubMap</tt>, <tt>navigableHeadMap</tt>, and
30	* <tt>navigableTailMap</tt> differ from the similarly named
31	* <tt>SortedMap</tt> methods only in their declared return types.
32	* Submaps of any <tt>NavigableMap</tt> must obey
33	* the <tt>NavigableMap</tt> interface.
34	*
35	* <p>This interface additionally defines methods <tt>firstEntry</tt>,
36	* <tt>pollFirstEntry</tt>, <tt>lastEntry</tt>, and
37	* <tt>pollLastEntry</tt> that return and/or remove the least and
38	* greatest mappings, if any exist, else returning <tt>null</tt>.
39	*
40	* <p> Implementations of entry-returning methods are expected to
41	* return <tt>Map.Entry</tt> pairs representing snapshots of mappings
42	* at the time they were produced, and thus generally do <em>not</em>
43	* support the optional <tt>Entry.setValue</tt> method. Note however
44	* that it is possible to change mappings in the associated map using
45	* method <tt>put</tt>.
46	*
47	* <p>This interface is a member of the
48	* <a href="{@docRoot}/../guide/collections/index.html">
49	* Java Collections Framework</a>.
50	*
51	* @author Doug Lea
52	* @param <K> the type of keys maintained by this map
53	* @param <V> the type of mapped values
54	* @since 1.6
55	*/
56	public interface NavigableMap<K,V> extends SortedMap<K,V> {
57	/**
58	* Returns a key-value mapping associated with the greatest key
59	* strictly less than the given key, or <tt>null</tt> if there is
60	* no such key.
61	*
62	* @param key the key
63	* @return an entry with the greatest key less than <tt>key</tt>,
64	* or <tt>null</tt> if there is no such key
65	* @throws ClassCastException if the specified key cannot be compared
66	* with the keys currently in the map
67	* @throws NullPointerException if the specified key is null
68	* and this map does not permit null keys
69	*/
70	Map.Entry<K,V> lowerEntry(K key);
71
72	/**
73	* Returns the greatest key strictly less than the given key, or
74	* <tt>null</tt> if there is no such key.
75	*
76	* @param key the key
77	* @return the greatest key less than <tt>key</tt>,
78	* or <tt>null</tt> if there is no such key
79	* @throws ClassCastException if the specified key cannot be compared
80	* with the keys currently in the map
81	* @throws NullPointerException if the specified key is null
82	* and this map does not permit null keys
83	*/
84	K lowerKey(K key);
85
86	/**
87	* Returns a key-value mapping associated with the greatest key
88	* less than or equal to the given key, or <tt>null</tt> if there
89	* is no such key.
90	*
91	* @param key the key
92	* @return an entry with the greatest key less than or equal to
93	* <tt>key</tt>, or <tt>null</tt> if there is no such key
94	* @throws ClassCastException if the specified key cannot be compared
95	* with the keys currently in the map
96	* @throws NullPointerException if the specified key is null
97	* and this map does not permit null keys
98	*/
99	Map.Entry<K,V> floorEntry(K key);
100
101	/**
102	* Returns the greatest key less than or equal to the given key,
103	* or <tt>null</tt> if there is no such key.
104	*
105	* @param key the key
106	* @return the greatest key less than or equal to <tt>key</tt>,
107	* or <tt>null</tt> if there is no such key
108	* @throws ClassCastException if the specified key cannot be compared
109	* with the keys currently in the map
110	* @throws NullPointerException if the specified key is null
111	* and this map does not permit null keys
112	*/
113	K floorKey(K key);
114
115	/**
116	* Returns a key-value mapping associated with the least key
117	* greater than or equal to the given key, or <tt>null</tt> if
118	* there is no such key.
119	*
120	* @param key the key
121	* @return an entry with the least key greater than or equal to
122	* <tt>key</tt>, or <tt>null</tt> if there is no such key
123	* @throws ClassCastException if the specified key cannot be compared
124	* with the keys currently in the map
125	* @throws NullPointerException if the specified key is null
126	* and this map does not permit null keys
127	*/
128	Map.Entry<K,V> ceilingEntry(K key);
129
130	/**
131	* Returns the least key greater than or equal to the given key,
132	* or <tt>null</tt> if there is no such key.
133	*
134	* @param key the key
135	* @return the least key greater than or equal to <tt>key</tt>,
136	* or <tt>null</tt> if there is no such key
137	* @throws ClassCastException if the specified key cannot be compared
138	* with the keys currently in the map
139	* @throws NullPointerException if the specified key is null
140	* and this map does not permit null keys
141	*/
142	K ceilingKey(K key);
143
144	/**
145	* Returns a key-value mapping associated with the least key
146	* strictly greater than the given key, or <tt>null</tt> if there
147	* is no such key.
148	*
149	* @param key the key
150	* @return an entry with the least key greater than <tt>key</tt>,
151	* or <tt>null</tt> if there is no such key
152	* @throws ClassCastException if the specified key cannot be compared
153	* with the keys currently in the map
154	* @throws NullPointerException if the specified key is null
155	* and this map does not permit null keys
156	*/
157	Map.Entry<K,V> higherEntry(K key);
158
159	/**
160	* Returns the least key strictly greater than the given key, or
161	* <tt>null</tt> if there is no such key.
162	*
163	* @param key the key
164	* @return the least key greater than <tt>key</tt>,
165	* or <tt>null</tt> if there is no such key
166	* @throws ClassCastException if the specified key cannot be compared
167	* with the keys currently in the map
168	* @throws NullPointerException if the specified key is null
169	* and this map does not permit null keys
170	*/
171	K higherKey(K key);
172
173	/**
174	* Returns a key-value mapping associated with the least
175	* key in this map, or <tt>null</tt> if the map is empty.
176	*
177	* @return an entry with the least key,
178	* or <tt>null</tt> if this map is empty
179	*/
180	Map.Entry<K,V> firstEntry();
181
182	/**
183	* Returns a key-value mapping associated with the greatest
184	* key in this map, or <tt>null</tt> if the map is empty.
185	*
186	* @return an entry with the greatest key,
187	* or <tt>null</tt> if this map is empty
188	*/
189	Map.Entry<K,V> lastEntry();
190
191	/**
192	* Removes and returns a key-value mapping associated with
193	* the least key in this map, or <tt>null</tt> if the map is empty.
194	*
195	* @return the removed first entry of this map,
196	* or <tt>null</tt> if this map is empty
197	*/
198	Map.Entry<K,V> pollFirstEntry();
199
200	/**
201	* Removes and returns a key-value mapping associated with
202	* the greatest key in this map, or <tt>null</tt> if the map is empty.
203	*
204	* @return the removed last entry of this map,
205	* or <tt>null</tt> if this map is empty
206	*/
207	Map.Entry<K,V> pollLastEntry();
208
209	/**
210	* Returns a {@link Set} view of the keys contained in this map.
211	* The set's iterator returns the keys in descending order.
212	* The set is backed by the map, so changes to the map are
213	* reflected in the set, and vice-versa. If the map is modified
214	* while an iteration over the set is in progress (except through
215	* the iterator's own <tt>remove</tt> operation), the results of
216	* the iteration are undefined. The set supports element removal,
217	* which removes the corresponding mapping from the map, via the
218	* <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
219	* <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
220	* operations. It does not support the <tt>add</tt> or <tt>addAll</tt>
221	* operations.
222	*
223	* @return a set view of the keys contained in this map, sorted in
224	* descending order
225	*/
226	Set<K> descendingKeySet();
227
228	/**
229	* Returns a {@link Set} view of the mappings contained in this map.
230	* The set's iterator returns the entries in descending key order.
231	* The set is backed by the map, so changes to the map are
232	* reflected in the set, and vice-versa. If the map is modified
233	* while an iteration over the set is in progress (except through
234	* the iterator's own <tt>remove</tt> operation, or through the
235	* <tt>setValue</tt> operation on a map entry returned by the
236	* iterator) the results of the iteration are undefined. The set
237	* supports element removal, which removes the corresponding
238	* mapping from the map, via the <tt>Iterator.remove</tt>,
239	* <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
240	* <tt>clear</tt> operations. It does not support the
241	* <tt>add</tt> or <tt>addAll</tt> operations.
242	*
243	* @return a set view of the mappings contained in this map,
244	* sorted in descending key order
245	*/
246	Set<Map.Entry<K, V>> descendingEntrySet();
247
248	/**
249	* Returns a view of the portion of this map whose keys range from
250	* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive. (If
251	* <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned map
252	* is empty.) The returned map is backed by this map, so changes
253	* in the returned map are reflected in this map, and vice-versa.
254	* The returned map supports all optional map operations that this
255	* map supports.
256	*
257	* <p>The returned map will throw an <tt>IllegalArgumentException</tt>
258	* on an attempt to insert a key outside its range.
259	*
260	* @param fromKey low endpoint (inclusive) of the keys in the returned map
261	* @param toKey high endpoint (exclusive) of the keys in the returned map
262	* @return a view of the portion of this map whose keys range from
263	* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive
264	* @throws ClassCastException if <tt>fromKey</tt> and <tt>toKey</tt>
265	* cannot be compared to one another using this map's comparator
266	* (or, if the map has no comparator, using natural ordering).
267	* Implementations may, but are not required to, throw this
268	* exception if <tt>fromKey</tt> or <tt>toKey</tt>
269	* cannot be compared to keys currently in the map.
270	* @throws NullPointerException if <tt>fromKey</tt> or <tt>toKey</tt>
271	* is null and this map does not permit null keys
272	* @throws IllegalArgumentException if <tt>fromKey</tt> is greater than
273	* <tt>toKey</tt>; or if this map itself has a restricted
274	* range, and <tt>fromKey</tt> or <tt>toKey</tt> lies
275	* outside the bounds of the range
276	*/
277	NavigableMap<K,V> navigableSubMap(K fromKey, K toKey);
278
279	/**
280	* Returns a view of the portion of this map whose keys are
281	* strictly less than <tt>toKey</tt>. The returned map is backed
282	* by this map, so changes in the returned map are reflected in
283	* this map, and vice-versa. The returned map supports all
284	* optional map operations that this map supports.
285	*
286	* <p>The returned map will throw an <tt>IllegalArgumentException</tt>
287	* on an attempt to insert a key outside its range.
288	*
289	* @param toKey high endpoint (exclusive) of the keys in the returned map
290	* @return a view of the portion of this map whose keys are strictly
291	* less than <tt>toKey</tt>
292	* @throws ClassCastException if <tt>toKey</tt> is not compatible
293	* with this map's comparator (or, if the map has no comparator,
294	* if <tt>toKey</tt> does not implement {@link Comparable}).
295	* Implementations may, but are not required to, throw this
296	* exception if <tt>toKey</tt> cannot be compared to keys
297	* currently in the map.
298	* @throws NullPointerException if <tt>toKey</tt> is null
299	* and this map does not permit null keys
300	* @throws IllegalArgumentException if this map itself has a
301	* restricted range, and <tt>toKey</tt> lies outside the
302	* bounds of the range
303	*/
304	NavigableMap<K,V> navigableHeadMap(K toKey);
305
306	/**
307	* Returns a view of the portion of this map whose keys are
308	* greater than or equal to <tt>fromKey</tt>. The returned map is
309	* backed by this map, so changes in the returned map are
310	* reflected in this map, and vice-versa. The returned map
311	* supports all optional map operations that this map supports.
312	*
313	* <p>The returned map will throw an <tt>IllegalArgumentException</tt>
314	* on an attempt to insert a key outside its range.
315	*
316	* @param fromKey low endpoint (inclusive) of the keys in the returned map
317	* @return a view of the portion of this map whose keys are greater
318	* than or equal to <tt>fromKey</tt>
319	* @throws ClassCastException if <tt>fromKey</tt> is not compatible
320	* with this map's comparator (or, if the map has no comparator,
321	* if <tt>fromKey</tt> does not implement {@link Comparable}).
322	* Implementations may, but are not required to, throw this
323	* exception if <tt>fromKey</tt> cannot be compared to keys
324	* currently in the map.
325	* @throws NullPointerException if <tt>fromKey</tt> is null
326	* and this map does not permit null keys
327	* @throws IllegalArgumentException if this map itself has a
328	* restricted range, and <tt>fromKey</tt> lies outside the
329	* bounds of the range
330	*/
331	NavigableMap<K,V> navigableTailMap(K fromKey);
332	}