--- jsr166/src/main/java/util/NavigableMap.java	2005/05/03 02:52:07	1.7
+++ jsr166/src/main/java/util/NavigableMap.java	2005/05/16 06:27:52	1.8
@@ -54,105 +54,104 @@ package java.util;
  */
 public interface NavigableMap<K,V> extends SortedMap<K,V> {
     /**
-     * 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 entry.
+     * 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 associated with ceiling of given key, or <tt>null</tt>
-     * if there is no such Entry.
-     * @throws ClassCastException if key cannot be compared with the keys
-     *            currently in the map.
-     * @throws NullPointerException if key is <tt>null</tt> and this map
-     * does not support <tt>null</tt> keys.
+     * @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> ceilingEntry(K key);
+    Map.Entry<K,V> lowerEntry(K key);
 
     /**
-     * Returns least key greater than or equal to the given key, or
+     * 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 ceiling key, or <tt>null</tt>
-     * if there is no such key.
-     * @throws ClassCastException if key cannot be compared with the keys
-     *            currently in the map.
-     * @throws NullPointerException if key is <tt>null</tt> and this map
-     * does not support <tt>null</tt> keys.
+     * @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 ceilingKey(K key);
+    K lowerKey(K key);
 
     /**
-     * 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 entry.
+     * 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 greatest key less than the given
-     * key, or <tt>null</tt> if there is no such Entry.
-     * @throws ClassCastException if key cannot be compared with the keys
-     *            currently in the map.
-     * @throws NullPointerException if key is <tt>null</tt> and this map
-     * does not support <tt>null</tt> keys.
+     * @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> lowerEntry(K key);
+    Map.Entry<K,V> floorEntry(K key);
 
     /**
-     * Returns the greatest key strictly less than the given key, or
-     * <tt>null</tt> if there is no such 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 the given
-     * key, or <tt>null</tt> if there is no such key.
-     * @throws ClassCastException if key cannot be compared with the keys
-     *            currently in the map.
-     * @throws NullPointerException if key is <tt>null</tt> and this map
-     * does not support <tt>null</tt> keys.
+     * @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 lowerKey(K key);
+    K floorKey(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 entry.
+     * 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 associated with floor of given key, or <tt>null</tt>
-     * if there is no such Entry.
-     * @throws ClassCastException if key cannot be compared with the keys
-     *            currently in the map.
-     * @throws NullPointerException if key is <tt>null</tt> and this map
-     * does not support <tt>null</tt> keys.
+     * @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> floorEntry(K key);
+    Map.Entry<K,V> ceilingEntry(K key);
 
     /**
-     * Returns the greatest key
-     * less than or equal to the given key, or <tt>null</tt> if there
-     * is no such 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 floor of given key, or <tt>null</tt> if there is no
-     * such key.
-     * @throws ClassCastException if key cannot be compared with the keys
-     *            currently in the map.
-     * @throws NullPointerException if key is <tt>null</tt> and this map
-     * does not support <tt>null</tt> keys.
+     * @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 floorKey(K key);
+    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 entry.
+     * is no such key.
      *
-     * @param key the key.
-     * @return an Entry with least key greater than the given key, or
-     * <tt>null</tt> if there is no such Entry.
-     * @throws ClassCastException if key cannot be compared with the keys
-     *            currently in the map.
-     * @throws NullPointerException if key is <tt>null</tt> and this map
-     * does not support <tt>null</tt> keys.
+     * @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);
 
@@ -160,13 +159,13 @@ public interface NavigableMap<K,V> exten
      * 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 the given key, or
-     * <tt>null</tt> if there is no such key.
-     * @throws ClassCastException if key cannot be compared with the keys
-     *            currently in the map.
-     * @throws NullPointerException if key is <tt>null</tt> and this map
-     * does not support <tt>null</tt> keys.
+     * @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);
 
@@ -174,8 +173,8 @@ public interface NavigableMap<K,V> exten
      * 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 least key, 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();
 
@@ -183,8 +182,8 @@ public interface NavigableMap<K,V> exten
      * 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 greatest key, 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();
 
@@ -192,8 +191,8 @@ public interface NavigableMap<K,V> exten
      * 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 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();
 
@@ -201,104 +200,132 @@ public interface NavigableMap<K,V> exten
      * 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 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 set view of the keys contained in this map, 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),
-     * 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>,
+     * 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 add or <tt>addAll</tt>
      * operations.
      *
-     * @return a set view of the keys contained in this map.
+     * @return a set view of the keys contained in this map, sorted in
+     *         descending order
      */
     Set<K> descendingKeySet();
 
     /**
-     * Returns a set view of the mappings contained in this map, in
-     * descending key order.  Each element in the returned set is a
-     * <tt>Map.Entry</tt>.  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.
+     * 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.
+     * @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
-     * navigable map is empty.)  The returned navigable map is backed
-     * by this map, so changes in the returned navigable map are
-     * reflected in this map, and vice-versa.
+     * <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.
      *
-     * @param fromKey low endpoint (inclusive) of the subMap.
-     * @param toKey high endpoint (exclusive) of the subMap.
+     * <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).
-     * @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.
+     *         <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 navigable map is backed by this map, so
-     * changes in the returned navigable 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>.
+     * 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 <tt>Comparable</tt>).
-     * @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>
-     * and this map does not support <tt>null</tt> keys.
+     *         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 navigable
-     * map is backed by this map, so changes in the returned navigable
-     * map are reflected in this map, and vice-versa.
-     * @param fromKey low endpoint (inclusive) of the tailMap.
+     * 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>.
+     *         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.
+     *         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);
+    NavigableMap<K,V> navigableTailMap(K fromKey);
 }