Index: ChangeLog =================================================================== RCS file: /cvsroot/classpath/classpath/ChangeLog,v retrieving revision 1.2448 diff -u -3 -p -u -r1.2448 ChangeLog --- ChangeLog 31 Aug 2004 22:17:29 -0000 1.2448 +++ ChangeLog 1 Sep 2004 16:13:10 -0000 @@ -1,3 +1,9 @@ +2004-09-01 Andrew John Hughes + + * java/util/Collections.java, java/util/SortedMap.java, + java/util/SortedSet.java + Added and corrected documentation. + 2004-08-31 Mark Wielaard * NEWS: Add new news. Index: java/util/Collections.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/Collections.java,v retrieving revision 1.28 diff -u -3 -p -u -r1.28 Collections.java --- java/util/Collections.java 17 Apr 2004 19:23:19 -0000 1.28 +++ java/util/Collections.java 1 Sep 2004 16:13:12 -0000 @@ -74,7 +74,7 @@ public class Collections /** * Constant used to decide cutoff for when a non-RandomAccess list should * be treated as sequential-access. Basically, quadratic behavior is - * acceptible for small lists when the overhead is so small in the first + * acceptable for small lists when the overhead is so small in the first * place. I arbitrarily set it to 16, so it may need some tuning. */ private static final int LARGE_LIST_SIZE = 16; @@ -130,6 +130,7 @@ public class Collections /** * The size: always 0! + * @return 0. */ public int size() { @@ -138,6 +139,7 @@ public class Collections /** * Returns an iterator that does not iterate. + * @return A non-iterating iterator. */ // This is really cheating! I think it's perfectly valid, though. public Iterator iterator() @@ -149,6 +151,8 @@ public class Collections // advantage by not allocating unnecessary iterators in AbstractSet. /** * The empty set never contains anything. + * @param o The object to search for. + * @return false. */ public boolean contains(Object o) { @@ -157,6 +161,9 @@ public class Collections /** * This is true only if the given collection is also empty. + * @param c The collection of objects which are to be compared + * against the members of this set. + * @return True if c is empty. */ public boolean containsAll(Collection c) { @@ -165,6 +172,8 @@ public class Collections /** * Equal only if the other set is empty. + * @param o The object to compare with this set. + * @return True if o is an empty instance of Set. */ public boolean equals(Object o) { @@ -173,6 +182,7 @@ public class Collections /** * The hashcode is always 0. + * @return 0. */ public int hashCode() { @@ -181,6 +191,8 @@ public class Collections /** * Always succeeds with false result. + * @param o The object to remove. + * @return false. */ public boolean remove(Object o) { @@ -189,6 +201,9 @@ public class Collections /** * Always succeeds with false result. + * @param c The collection of objects which should + * all be removed from this set. + * @return false. */ public boolean removeAll(Collection c) { @@ -197,6 +212,9 @@ public class Collections /** * Always succeeds with false result. + * @param c The collection of objects which should + * all be retained within this set. + * @return false. */ public boolean retainAll(Collection c) { @@ -205,6 +223,7 @@ public class Collections /** * The array is always empty. + * @return A new array with a size of 0. */ public Object[] toArray() { @@ -213,6 +232,9 @@ public class Collections /** * We don't even need to use reflection! + * @param a An existing array, which can be empty. + * @return The original array with any existing + * initial element set to null. */ public Object[] toArray(Object[] a) { @@ -223,6 +245,7 @@ public class Collections /** * The string never changes. + * @return "[]". */ public String toString() { @@ -260,6 +283,7 @@ public class Collections /** * The size is always 0. + * @return 0. */ public int size() { @@ -267,7 +291,13 @@ public class Collections } /** - * No matter the index, it is out of bounds. + * No matter the index, it is out of bounds. This + * method never returns, throwing an exception instead. + * + * @param index The index of the element to retrieve. + * @return the object at the specified index. + * @throws IndexOutofBoundsException as any given index + * is outside the bounds of an empty array. */ public Object get(int index) { @@ -278,6 +308,8 @@ public class Collections // advantage by not allocating unnecessary iterators in AbstractList. /** * Never contains anything. + * @param o The object to search for. + * @return false. */ public boolean contains(Object o) { @@ -286,6 +318,9 @@ public class Collections /** * This is true only if the given collection is also empty. + * @param c The collection of objects, which should be compared + * against the members of this list. + * @return True if c is also empty. */ public boolean containsAll(Collection c) { @@ -293,7 +328,9 @@ public class Collections } /** - * Equal only if the other set is empty. + * Equal only if the other list is empty. + * @param o The object to compare against this list. + * @return True if o is also an empty instance of List. */ public boolean equals(Object o) { @@ -302,6 +339,7 @@ public class Collections /** * The hashcode is always 1. + * @return 1. */ public int hashCode() { @@ -310,6 +348,8 @@ public class Collections /** * Returns -1. + * @param o The object to search for. + * @return -1. */ public int indexOf(Object o) { @@ -318,6 +358,8 @@ public class Collections /** * Returns -1. + * @param o The object to search for. + * @return -1. */ public int lastIndexOf(Object o) { @@ -326,6 +368,8 @@ public class Collections /** * Always succeeds with false result. + * @param o The object to remove. + * @return -1. */ public boolean remove(Object o) { @@ -334,6 +378,9 @@ public class Collections /** * Always succeeds with false result. + * @param c The collection of objects which should + * all be removed from this list. + * @return false. */ public boolean removeAll(Collection c) { @@ -342,6 +389,9 @@ public class Collections /** * Always succeeds with false result. + * @param c The collection of objects which should + * all be retained within this list. + * @return false. */ public boolean retainAll(Collection c) { @@ -350,6 +400,7 @@ public class Collections /** * The array is always empty. + * @return A new array with a size of 0. */ public Object[] toArray() { @@ -358,6 +409,9 @@ public class Collections /** * We don't even need to use reflection! + * @param a An existing array, which can be empty. + * @return The original array with any existing + * initial element set to null. */ public Object[] toArray(Object[] a) { @@ -368,6 +422,7 @@ public class Collections /** * The string never changes. + * @return "[]". */ public String toString() { @@ -404,6 +459,7 @@ public class Collections /** * There are no entries. + * @return The empty set. */ public Set entrySet() { @@ -414,6 +470,8 @@ public class Collections // advantage by not allocating unnecessary iterators in AbstractMap. /** * No entries! + * @param key The key to search for. + * @return false. */ public boolean containsKey(Object key) { @@ -422,6 +480,8 @@ public class Collections /** * No entries! + * @param value The value to search for. + * @return false. */ public boolean containsValue(Object value) { @@ -430,6 +490,8 @@ public class Collections /** * Equal to all empty maps. + * @param o The object o to compare against this map. + * @return True if o is also an empty instance of Map. */ public boolean equals(Object o) { @@ -438,6 +500,8 @@ public class Collections /** * No mappings, so this returns null. + * @param o The key of the object to retrieve. + * @return null. */ public Object get(Object o) { @@ -446,6 +510,7 @@ public class Collections /** * The hashcode is always 0. + * @return 0. */ public int hashCode() { @@ -454,6 +519,7 @@ public class Collections /** * No entries. + * @return The empty set. */ public Set keySet() { @@ -462,6 +528,8 @@ public class Collections /** * Remove always succeeds, with null result. + * @param o The key of the mapping to remove. + * @return null, as there is never a mapping for o. */ public Object remove(Object o) { @@ -470,6 +538,7 @@ public class Collections /** * Size is always 0. + * @return 0. */ public int size() { @@ -479,6 +548,7 @@ public class Collections /** * No entries. Technically, EMPTY_SET, while more specific than a general * Collection, will work. Besides, that's what the JDK uses! + * @return The empty set. */ public Collection values() { @@ -487,6 +557,7 @@ public class Collections /** * The string never changes. + * @return "[]". */ public String toString() { @@ -651,10 +722,24 @@ public class Collections final Iterator i = c.iterator(); return new Enumeration() { + /** + * Returns true if there are more elements to + * be enumerated. + * + * @return The result of hasNext() + * called on the underlying iterator. + */ public final boolean hasMoreElements() { return i.hasNext(); } + + /** + * Returns the next element to be enumerated. + * + * @return The result of next() + * called on the underlying iterator. + */ public final Object nextElement() { return i.next(); @@ -894,6 +979,7 @@ public class Collections /** * The size is fixed. + * @return The size of the list. */ public int size() { @@ -902,6 +988,9 @@ public class Collections /** * The same element is returned. + * @param index The index of the element to be returned (irrelevant + * as the list contains only copies of element). + * @return The element used by this list. */ public Object get(int index) { @@ -914,6 +1003,8 @@ public class Collections // advantage by not allocating unnecessary iterators in AbstractList. /** * This list only contains one element. + * @param o The object to search for. + * @return True if o is the element used by this list. */ public boolean contains(Object o) { @@ -922,6 +1013,8 @@ public class Collections /** * The index is either 0 or -1. + * @param o The object to find the index of. + * @return 0 if o == element, -1 if not. */ public int indexOf(Object o) { @@ -930,6 +1023,9 @@ public class Collections /** * The index is either n-1 or -1. + * @param o The object to find the last index of. + * @return The last index in the list if o == element, + * -1 if not. */ public int lastIndexOf(Object o) { @@ -938,6 +1034,11 @@ public class Collections /** * A subList is just another CopiesList. + * @param from The starting bound of the sublist. + * @param to The ending bound of the sublist. + * @return A list of copies containing from - to + * elements, all of which are equal to the element + * used by this list. */ public List subList(int from, int to) { @@ -948,6 +1049,8 @@ public class Collections /** * The array is easy. + * @return An array of size n filled with copies of + * the element used by this list. */ public Object[] toArray() { @@ -958,6 +1061,7 @@ public class Collections /** * The string is easy to generate. + * @return A string representation of the list. */ public String toString() { @@ -980,9 +1084,9 @@ public class Collections * @return true if a replacement occurred * @throws UnsupportedOperationException if the list iterator does not allow * for the set operation - * @throws ClassCastException newval is of a type which cannot be added + * @throws ClassCastException if newval is of a type which cannot be added * to the list - * @throws IllegalArgumentException some other aspect of newval stops + * @throws IllegalArgumentException if some other aspect of newval stops * it being added to the list * @since 1.4 */ @@ -1288,6 +1392,7 @@ public class Collections /** * The size: always 1! + * @return 1. */ public int size() { @@ -1301,13 +1406,30 @@ public class Collections { return new Iterator() { + /** + * Flag to indicate whether or not the element has + * been retrieved. + */ private boolean hasNext = true; + /** + * Returns true if elements still remain to be + * iterated through. + * + * @return True if the element has not yet been returned. + */ public boolean hasNext() { return hasNext; } + /** + * Returns the element. + * + * @return The element used by this singleton. + * @throws NoSuchElementException if the object + * has already been retrieved. + */ public Object next() { if (hasNext) @@ -1319,6 +1441,15 @@ public class Collections throw new NoSuchElementException(); } + /** + * Removes the element from the singleton. + * As this set is immutable, this will always + * throw an exception. + * + * @throws UnsupportedOperationException as the + * singleton set doesn't support + * remove(). + */ public void remove() { throw new UnsupportedOperationException(); @@ -1330,6 +1461,9 @@ public class Collections // advantage by not allocating unnecessary iterators in AbstractSet. /** * The set only contains one element. + * + * @param o The object to search for. + * @return True if o == the element of the singleton. */ public boolean contains(Object o) { @@ -1338,6 +1472,10 @@ public class Collections /** * This is true if the other collection only contains the element. + * + * @param c A collection to compare against this singleton. + * @return True if c only contains either no elements or elements + * equal to the element in this singleton. */ public boolean containsAll(Collection c) { @@ -1351,6 +1489,8 @@ public class Collections /** * The hash is just that of the element. + * + * @return The hashcode of the element. */ public int hashCode() { @@ -1359,6 +1499,8 @@ public class Collections /** * Returning an array is simple. + * + * @return An array containing the element. */ public Object[] toArray() { @@ -1367,6 +1509,9 @@ public class Collections /** * Obvious string. + * + * @return The string surrounded by enclosing + * square brackets. */ public String toString() { @@ -1420,6 +1565,7 @@ public class Collections /** * The size: always 1! + * @return 1. */ public int size() { @@ -1428,6 +1574,12 @@ public class Collections /** * Only index 0 is valid. + * @param index The index of the element + * to retrieve. + * @return The singleton's element if the + * index is 0. + * @throws IndexOutOfBoundsException if + * index is not 0. */ public Object get(int index) { @@ -1440,6 +1592,9 @@ public class Collections // advantage by not allocating unnecessary iterators in AbstractList. /** * The set only contains one element. + * + * @param o The object to search for. + * @return True if o == the singleton element. */ public boolean contains(Object o) { @@ -1448,6 +1603,10 @@ public class Collections /** * This is true if the other collection only contains the element. + * + * @param c A collection to compare against this singleton. + * @return True if c only contains either no elements or elements + * equal to the element in this singleton. */ public boolean containsAll(Collection c) { @@ -1461,6 +1620,9 @@ public class Collections /** * Speed up the hashcode computation. + * + * @return The hashcode of the list, based + * on the hashcode of the singleton element. */ public int hashCode() { @@ -1469,6 +1631,9 @@ public class Collections /** * Either the list has it or not. + * + * @param o The object to find the first index of. + * @return 0 if o is the singleton element, -1 if not. */ public int indexOf(Object o) { @@ -1477,6 +1642,9 @@ public class Collections /** * Either the list has it or not. + * + * @param o The object to find the last index of. + * @return 0 if o is the singleton element, -1 if not. */ public int lastIndexOf(Object o) { @@ -1485,6 +1653,14 @@ public class Collections /** * Sublists are limited in scope. + * + * @param from The starting bound for the sublist. + * @param to The ending bound for the sublist. + * @return Either an empty list if both bounds are + * 0 or 1, or this list if the bounds are 0 and 1. + * @throws IllegalArgumentException if from > to + * @throws IndexOutOfBoundsException if either bound is greater + * than 1. */ public List subList(int from, int to) { @@ -1499,6 +1675,8 @@ public class Collections /** * Returning an array is simple. + * + * @return An array containing the element. */ public Object[] toArray() { @@ -1507,6 +1685,9 @@ public class Collections /** * Obvious string. + * + * @return The string surrounded by enclosing + * square brackets. */ public String toString() { @@ -1573,12 +1754,23 @@ public class Collections /** * There is a single immutable entry. + * + * @return A singleton containing the map entry. */ public Set entrySet() { if (entries == null) entries = singleton(new AbstractMap.BasicMapEntry(k, v) { + /** + * Sets the value of the map entry to the supplied value. + * An exception is always thrown, as the map is immutable. + * + * @param o The new value. + * @return The old value. + * @throws UnsupportedOperationException as setting the value + * is not supported. + */ public Object setValue(Object o) { throw new UnsupportedOperationException(); @@ -1591,6 +1783,9 @@ public class Collections // advantage by not allocating unnecessary iterators in AbstractMap. /** * Single entry. + * + * @param key The key to look for. + * @return True if the key is the same as the one used by this map. */ public boolean containsKey(Object key) { @@ -1599,6 +1794,9 @@ public class Collections /** * Single entry. + * + * @param value The value to look for. + * @return True if the value is the same as the one used by this map. */ public boolean containsValue(Object value) { @@ -1607,6 +1805,10 @@ public class Collections /** * Single entry. + * + * @param key The key of the value to be retrieved. + * @return The singleton value if the key is the same as the + * singleton key, null otherwise. */ public Object get(Object key) { @@ -1615,6 +1817,9 @@ public class Collections /** * Calculate the hashcode directly. + * + * @return The hashcode computed from the singleton key + * and the singleton value. */ public int hashCode() { @@ -1623,6 +1828,8 @@ public class Collections /** * Return the keyset. + * + * @return A singleton containing the key. */ public Set keySet() { @@ -1633,6 +1840,8 @@ public class Collections /** * The size: always 1! + * + * @return 1. */ public int size() { @@ -1642,6 +1851,8 @@ public class Collections /** * Return the values. Technically, a singleton, while more specific than * a general Collection, will work. Besides, that's what the JDK uses! + * + * @return A singleton containing the value. */ public Collection values() { @@ -1652,6 +1863,9 @@ public class Collections /** * Obvious string. + * + * @return A string containing the string representations of the key + * and its associated value. */ public String toString() { @@ -1812,6 +2026,21 @@ public class Collections mutex = sync; } + /** + * Adds the object to the underlying collection, first + * obtaining a lock on the mutex. + * + * @param o The object to add. + * @return true if the collection was modified as a result of this action. + * @throws UnsupportedOperationException if this collection does not + * support the add operation. + * @throws ClassCastException if o cannot be added to this collection due + * to its type. + * @throws NullPointerException if o is null and this collection doesn't + * support the addition of null values. + * @throws IllegalArgumentException if o cannot be added to this + * collection for some other reason. + */ public boolean add(Object o) { synchronized (mutex) @@ -1820,6 +2049,22 @@ public class Collections } } + /** + * Adds the objects in col to the underlying collection, first + * obtaining a lock on the mutex. + * + * @param col The collection to take the new objects from. + * @return true if the collection was modified as a result of this action. + * @throws UnsupportedOperationException if this collection does not + * support the addAll operation. + * @throws ClassCastException if some element of col cannot be added to this + * collection due to its type. + * @throws NullPointerException if some element of col is null and this + * collection does not support the addition of null values. + * @throws NullPointerException if col itself is null. + * @throws IllegalArgumentException if some element of col cannot be added + * to this collection for some other reason. + */ public boolean addAll(Collection col) { synchronized (mutex) @@ -1828,6 +2073,13 @@ public class Collections } } + /** + * Removes all objects from the underlying collection, + * first obtaining a lock on the mutex. + * + * @throws UnsupportedOperationException if this collection does not + * support the clear operation. + */ public void clear() { synchronized (mutex) @@ -1836,6 +2088,18 @@ public class Collections } } + /** + * Checks for the existence of o within the underlying + * collection, first obtaining a lock on the mutex. + * + * @param o the element to look for. + * @return true if this collection contains at least one + * element e such that o == null ? e == null : o.equals(e). + * @throws ClassCastException if the type of o is not a valid type for this + * collection. + * @throws NullPointerException if o is null and this collection doesn't + * support null values. + */ public boolean contains(Object o) { synchronized (mutex) @@ -1844,6 +2108,20 @@ public class Collections } } + /** + * Checks for the existence of each object in cl + * within the underlying collection, first obtaining + * a lock on the mutex. + * + * @param cl the collection to test for. + * @return true if for every element o in c, contains(o) + * would return true. + * @throws ClassCastException if the type of any element in cl is not a valid + * type for this collection. + * @throws NullPointerException if some element of cl is null and this + * collection does not support null values. + * @throws NullPointerException if cl itself is null. + */ public boolean containsAll(Collection c1) { synchronized (mutex) @@ -1852,6 +2130,13 @@ public class Collections } } + /** + * Returns true if there are no objects in the underlying + * collection. A lock on the mutex is obtained before the + * check is performed. + * + * @return true if this collection contains no elements. + */ public boolean isEmpty() { synchronized (mutex) @@ -1860,6 +2145,14 @@ public class Collections } } + /** + * Returns a synchronized iterator wrapper around the underlying + * collection's iterator. A lock on the mutex is obtained before + * retrieving the collection's iterator. + * + * @return An iterator over the elements in the underlying collection, + * which returns each element in any order. + */ public Iterator iterator() { synchronized (mutex) @@ -1868,6 +2161,20 @@ public class Collections } } + /** + * Removes the specified object from the underlying collection, + * first obtaining a lock on the mutex. + * + * @param o The object to remove. + * @return true if the collection changed as a result of this call, that is, + * if the collection contained at least one occurrence of o. + * @throws UnsupportedOperationException if this collection does not + * support the remove operation. + * @throws ClassCastException if the type of o is not a valid type + * for this collection. + * @throws NullPointerException if o is null and the collection doesn't + * support null values. + */ public boolean remove(Object o) { synchronized (mutex) @@ -1876,6 +2183,22 @@ public class Collections } } + /** + * Removes all elements, e, of the underlying + * collection for which col.contains(e) + * returns true. A lock on the mutex is obtained + * before the operation proceeds. + * + * @param col The collection of objects to be removed. + * @return true if this collection was modified as a result of this call. + * @throws UnsupportedOperationException if this collection does not + * support the removeAll operation. + * @throws ClassCastException if the type of any element in c is not a valid + * type for this collection. + * @throws NullPointerException if some element of c is null and this + * collection does not support removing null values. + * @throws NullPointerException if c itself is null. + */ public boolean removeAll(Collection col) { synchronized (mutex) @@ -1884,6 +2207,23 @@ public class Collections } } + /** + * Retains all elements, e, of the underlying + * collection for which col.contains(e) + * returns true. That is, every element that doesn't + * exist in col is removed. A lock on the mutex is obtained + * before the operation proceeds. + * + * @param col The collection of objects to be removed. + * @return true if this collection was modified as a result of this call. + * @throws UnsupportedOperationException if this collection does not + * support the removeAll operation. + * @throws ClassCastException if the type of any element in c is not a valid + * type for this collection. + * @throws NullPointerException if some element of c is null and this + * collection does not support removing null values. + * @throws NullPointerException if c itself is null. + */ public boolean retainAll(Collection col) { synchronized (mutex) @@ -1892,6 +2232,13 @@ public class Collections } } + /** + * Retrieves the size of the underlying collection. + * A lock on the mutex is obtained before the collection + * is accessed. + * + * @return The size of the collection. + */ public int size() { synchronized (mutex) @@ -1900,6 +2247,14 @@ public class Collections } } + /** + * Returns an array containing each object within the underlying + * collection. A lock is obtained on the mutex before the collection + * is accessed. + * + * @return An array of objects, matching the collection in size. The + * elements occur in any order. + */ public Object[] toArray() { synchronized (mutex) @@ -1908,6 +2263,23 @@ public class Collections } } + /** + * Copies the elements in the underlying collection to the supplied + * array. If a.length < size(), a new array of the + * same run-time type is created, with a size equal to that of + * the collection. If a.length > size(), then the + * elements from 0 to size() - 1 contain the elements + * from this collection. The following element is set to null + * to indicate the end of the collection objects. However, this + * only makes a difference if null is not a permitted value within + * the collection. + * Before the copying takes place, a lock is obtained on the mutex. + * + * @param a An array to copy elements to. + * @return An array containing the elements of the underlying collection. + * @throws ArrayStoreException if the type of any element of the + * collection is not a subtype of the element type of a. + */ public Object[] toArray(Object[] a) { synchronized (mutex) @@ -1916,6 +2288,12 @@ public class Collections } } + /** + * Returns a string representation of the underlying collection. + * A lock is obtained on the mutex before the string is created. + * + * @return A string representation of the collection. + */ public String toString() { synchronized (mutex) @@ -1955,6 +2333,13 @@ public class Collections mutex = sync; } + /** + * Retrieves the next object in the underlying collection. + * A lock is obtained on the mutex before the collection is accessed. + * + * @return The next object in the collection. + * @throws NoSuchElementException if there are no more elements + */ public Object next() { synchronized (mutex) @@ -1963,6 +2348,14 @@ public class Collections } } + /** + * Returns true if objects can still be retrieved from the iterator + * using next(). A lock is obtained on the mutex before + * the collection is accessed. + * + * @return True if at least one element is still to be returned by + * next(). + */ public boolean hasNext() { synchronized (mutex) @@ -1971,6 +2364,21 @@ public class Collections } } + /** + * Removes the object that was last returned by next() + * from the underlying collection. Only one call to this method is + * allowed per call to the next() method, and it does + * not affect the value that will be returned by next(). + * Thus, if element n was retrieved from the collection by + * next(), it is this element that gets removed. + * Regardless of whether this takes place or not, element n+1 is + * still returned on the subsequent next() call. + * + * @throws IllegalStateException if next has not yet been called or remove + * has already been called since the last call to next. + * @throws UnsupportedOperationException if this Iterator does not support + * the remove operation. + */ public void remove() { synchronized (mutex) @@ -2058,6 +2466,25 @@ public class Collections list = l; } + /** + * Insert an element into the underlying list at a given position (optional + * operation). This shifts all existing elements from that position to the + * end one index to the right. This version of add has no return, since it is + * assumed to always succeed if there is no exception. Before the + * addition takes place, a lock is obtained on the mutex. + * + * @param index the location to insert the item + * @param o the object to insert + * @throws UnsupportedOperationException if this list does not support the + * add operation + * @throws IndexOutOfBoundsException if index < 0 || index > size() + * @throws ClassCastException if o cannot be added to this list due to its + * type + * @throws IllegalArgumentException if o cannot be added to this list for + * some other reason + * @throws NullPointerException if o is null and this list doesn't support + * the addition of null values. + */ public void add(int index, Object o) { synchronized (mutex) @@ -2066,6 +2493,23 @@ public class Collections } } + /** + * Add an element to the end of the underlying list (optional operation). + * If the list imposes restraints on what can be inserted, such as no null + * elements, this should be documented. A lock is obtained on the mutex before + * any of the elements are added. + * + * @param o the object to add + * @return true, as defined by Collection for a modified list + * @throws UnsupportedOperationException if this list does not support the + * add operation + * @throws ClassCastException if o cannot be added to this list due to its + * type + * @throws IllegalArgumentException if o cannot be added to this list for + * some other reason + * @throws NullPointerException if o is null and this list doesn't support + * the addition of null values. + */ public boolean addAll(int index, Collection c) { synchronized (mutex) @@ -2074,6 +2518,18 @@ public class Collections } } + /** + * Tests whether the underlying list is equal to the supplied object. + * The object is deemed to be equal if it is also a List + * of equal size and with the same elements (i.e. each element, e1, + * in list, l1, and each element, e2, in l2, must return true for + * e1 == null ? e2 == null : e1.equals(e2). Before the + * comparison is made, a lock is obtained on the mutex. + * + * @param o The object to test for equality with the underlying list. + * @return True if o is equal to the underlying list under the above + * definition. + */ public boolean equals(Object o) { synchronized (mutex) @@ -2082,6 +2538,14 @@ public class Collections } } + /** + * Retrieves the object at the specified index. A lock + * is obtained on the mutex before the list is accessed. + * + * @param index the index of the element to be returned + * @return the element at index index in this list + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + */ public Object get(int index) { synchronized (mutex) @@ -2090,6 +2554,15 @@ public class Collections } } + /** + * Obtains a hashcode for the underlying list, first obtaining + * a lock on the mutex. The calculation of the hashcode is + * detailed in the documentation for the List + * interface. + * + * @return The hashcode of the underlying list. + * @see List#hashCode() + */ public int hashCode() { synchronized (mutex) @@ -2098,6 +2571,20 @@ public class Collections } } + /** + * Obtain the first index at which a given object is to be found in the + * underlying list. A lock is obtained on the mutex before the list is + * accessed. + * + * @param o the object to search for + * @return the least integer n such that o == null ? get(n) == null : + * o.equals(get(n)), or -1 if there is no such index. + * @throws ClassCastException if the type of o is not a valid + * type for this list. + * @throws NullPointerException if o is null and this + * list does not support null values. + */ + public int indexOf(Object o) { synchronized (mutex) @@ -2106,6 +2593,18 @@ public class Collections } } + /** + * Obtain the last index at which a given object is to be found in this + * underlying list. A lock is obtained on the mutex before the list + * is accessed. + * + * @return the greatest integer n such that o == null ? get(n) == null + * : o.equals(get(n)), or -1 if there is no such index. + * @throws ClassCastException if the type of o is not a valid + * type for this list. + * @throws NullPointerException if o is null and this + * list does not support null values. + */ public int lastIndexOf(Object o) { synchronized (mutex) @@ -2114,6 +2613,16 @@ public class Collections } } + /** + * Retrieves a synchronized wrapper around the underlying list's + * list iterator. A lock is obtained on the mutex before the + * list iterator is retrieved. + * + * @return A list iterator over the elements in the underlying list. + * The list iterator allows additional list-specific operations + * to be performed, in addition to those supplied by the + * standard iterator. + */ public ListIterator listIterator() { synchronized (mutex) @@ -2122,6 +2631,23 @@ public class Collections } } + /** + * Retrieves a synchronized wrapper around the underlying list's + * list iterator. A lock is obtained on the mutex before the + * list iterator is retrieved. The iterator starts at the + * index supplied, leading to the element at that index being + * the first one returned by next(). Calling + * previous() from this initial position returns + * index - 1. + * + * @param index the position, between 0 and size() inclusive, to begin the + * iteration from + * @return A list iterator over the elements in the underlying list. + * The list iterator allows additional list-specific operations + * to be performed, in addition to those supplied by the + * standard iterator. + * @throws IndexOutOfBoundsException if index < 0 || index > size() + */ public ListIterator listIterator(int index) { synchronized (mutex) @@ -2130,6 +2656,17 @@ public class Collections } } + /** + * Remove the element at a given position in the underlying list (optional + * operation). All remaining elements are shifted to the left to fill the gap. + * A lock on the mutex is obtained before the element is removed. + * + * @param index the position within the list of the object to remove + * @return the object that was removed + * @throws UnsupportedOperationException if this list does not support the + * remove operation + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + */ public Object remove(int index) { synchronized (mutex) @@ -2138,6 +2675,24 @@ public class Collections } } + /** + * Replace an element of the underlying list with another object (optional + * operation). A lock is obtained on the mutex before the element is + * replaced. + * + * @param index the position within this list of the element to be replaced + * @param o the object to replace it with + * @return the object that was replaced + * @throws UnsupportedOperationException if this list does not support the + * set operation. + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + * @throws ClassCastException if o cannot be added to this list due to its + * type + * @throws IllegalArgumentException if o cannot be added to this list for + * some other reason + * @throws NullPointerException if o is null and this + * list does not support null values. + */ public Object set(int index, Object o) { synchronized (mutex) @@ -2146,6 +2701,24 @@ public class Collections } } + /** + * Obtain a List view of a subsection of the underlying list, from fromIndex + * (inclusive) to toIndex (exclusive). If the two indices are equal, the + * sublist is empty. The returned list should be modifiable if and only + * if this list is modifiable. Changes to the returned list should be + * reflected in this list. If this list is structurally modified in + * any way other than through the returned list, the result of any subsequent + * operations on the returned list is undefined. A lock is obtained + * on the mutex before the creation of the sublist. The returned list + * is also synchronized, using the same mutex. + * + * @param fromIndex the index that the returned list should start from + * (inclusive) + * @param toIndex the index that the returned list should go to (exclusive) + * @return a List backed by a subsection of this list + * @throws IndexOutOfBoundsException if fromIndex < 0 + * || toIndex > size() || fromIndex > toIndex + */ public List subList(int fromIndex, int toIndex) { synchronized (mutex) @@ -2191,6 +2764,25 @@ public class Collections super(sync, l); } + /** + * Obtain a List view of a subsection of the underlying list, from fromIndex + * (inclusive) to toIndex (exclusive). If the two indices are equal, the + * sublist is empty. The returned list should be modifiable if and only + * if this list is modifiable. Changes to the returned list should be + * reflected in this list. If this list is structurally modified in + * any way other than through the returned list, the result of any subsequent + * operations on the returned list is undefined. A lock is obtained + * on the mutex before the creation of the sublist. The returned list + * is also synchronized, using the same mutex. Random accessibility + * is also extended to the new list. + * + * @param fromIndex the index that the returned list should start from + * (inclusive) + * @param toIndex the index that the returned list should go to (exclusive) + * @return a List backed by a subsection of this list + * @throws IndexOutOfBoundsException if fromIndex < 0 + * || toIndex > size() || fromIndex > toIndex + */ public List subList(int fromIndex, int toIndex) { synchronized (mutex) @@ -2228,6 +2820,24 @@ public class Collections this.li = li; } + /** + * Insert an element into the underlying list at the current position of + * the iterator (optional operation). The element is inserted in between + * the element that would be returned by previous() and the + * element that would be returned by next(). After the + * insertion, a subsequent call to next is unaffected, but + * a call to previous returns the item that was added. The values returned + * by nextIndex() and previousIndex() are incremented. A lock is obtained + * on the mutex before the addition takes place. + * + * @param o the object to insert into the list + * @throws ClassCastException if the object is of a type which cannot be added + * to this list. + * @throws IllegalArgumentException if some other aspect of the object stops + * it being added to this list. + * @throws UnsupportedOperationException if this ListIterator does not + * support the add operation. + */ public void add(Object o) { synchronized (mutex) @@ -2235,6 +2845,15 @@ public class Collections li.add(o); } } + + /** + * Tests whether there are elements remaining in the underlying list + * in the reverse direction. In other words, previous() + * will not fail with a NoSuchElementException. A lock is obtained + * on the mutex before the check takes place. + * + * @return true if the list continues in the reverse direction + */ public boolean hasPrevious() { synchronized (mutex) @@ -2243,6 +2862,14 @@ public class Collections } } + /** + * Find the index of the element that would be returned by a call to + * next(). If hasNext() returns false, this returns the + * list size. A lock is obtained on the mutex before the query takes + * place. + * + * @return the index of the element that would be returned by next() + */ public int nextIndex() { synchronized (mutex) @@ -2251,6 +2878,16 @@ public class Collections } } + /** + * Obtain the previous element from the underlying list. Repeated + * calls to previous may be used to iterate backwards over the entire list, + * or calls to next and previous may be used together to go forwards and + * backwards. Alternating calls to next and previous will return the same + * element. A lock is obtained on the mutex before the object is retrieved. + * + * @return the next element in the list in the reverse direction + * @throws NoSuchElementException if there are no more elements + */ public Object previous() { synchronized (mutex) @@ -2259,6 +2896,13 @@ public class Collections } } + /** + * Find the index of the element that would be returned by a call to + * previous. If hasPrevious() returns false, this returns -1. A lock + * is obtained on the mutex before the query takes place. + * + * @return the index of the element that would be returned by previous() + */ public int previousIndex() { synchronized (mutex) @@ -2267,6 +2911,25 @@ public class Collections } } + /** + * Replace the element last returned by a call to next() or + * previous() with a given object (optional operation). This + * method may only be called if neither add() nor + * remove() have been called since the last call to + * next() or previous. A lock is obtained + * on the mutex before the list is modified. + * + * @param o the object to replace the element with + * @throws ClassCastException the object is of a type which cannot be added + * to this list + * @throws IllegalArgumentException some other aspect of the object stops + * it being added to this list + * @throws IllegalStateException if neither next or previous have been + * called, or if add or remove has been called since the last call + * to next or previous + * @throws UnsupportedOperationException if this ListIterator does not + * support the set operation + */ public void set(Object o) { synchronized (mutex) @@ -2373,6 +3036,12 @@ public class Collections mutex = sync; } + /** + * Clears all the entries from the underlying map. A lock is obtained + * on the mutex before the map is cleared. + * + * @throws UnsupportedOperationException if clear is not supported + */ public void clear() { synchronized (mutex) @@ -2381,6 +3050,16 @@ public class Collections } } + /** + * Returns true if the underlying map contains a entry for the given key. + * A lock is obtained on the mutex before the map is queried. + * + * @param key the key to search for. + * @return true if the underlying map contains the key. + * @throws ClassCastException if the key is of an inappropriate type. + * @throws NullPointerException if key is null but the map + * does not permit null keys. + */ public boolean containsKey(Object key) { synchronized (mutex) @@ -2389,6 +3068,20 @@ public class Collections } } + /** + * Returns true if the underlying map contains at least one entry with the + * given value. In other words, returns true if a value v exists where + * (value == null ? v == null : value.equals(v)). This usually + * requires linear time. A lock is obtained on the mutex before the map + * is queried. + * + * @param value the value to search for + * @return true if the map contains the value + * @throws ClassCastException if the type of the value is not a valid type + * for this map. + * @throws NullPointerException if the value is null and the map doesn't + * support null values. + */ public boolean containsValue(Object value) { synchronized (mutex) @@ -2411,6 +3104,15 @@ public class Collections { e = (Map.Entry) o; } + + /** + * Returns true if the object, o, implements Map.Entry + * with the same key and value as the underlying entry. A lock is + * obtained on the mutex before the comparison takes place. + * + * @param o The object to compare with this entry. + * @return True if o is equivalent to the underlying map entry. + */ public boolean equals(Object o) { synchronized (mutex) @@ -2418,6 +3120,13 @@ public class Collections return e.equals(o); } } + + /** + * Returns the key used in the underlying map entry. A lock is obtained + * on the mutex before the key is retrieved. + * + * @return The key of the underlying map entry. + */ public Object getKey() { synchronized (mutex) @@ -2425,6 +3134,13 @@ public class Collections return e.getKey(); } } + + /** + * Returns the value used in the underlying map entry. A lock is obtained + * on the mutex before the value is retrieved. + * + * @return The value of the underlying map entry. + */ public Object getValue() { synchronized (mutex) @@ -2432,6 +3148,16 @@ public class Collections return e.getValue(); } } + + /** + * Computes the hash code for the underlying map entry. + * This computation is described in the documentation for the + * Map interface. A lock is obtained on the mutex + * before the underlying map is accessed. + * + * @return The hash code of the underlying map entry. + * @see Map#hashCode() + */ public int hashCode() { synchronized (mutex) @@ -2439,6 +3165,23 @@ public class Collections return e.hashCode(); } } + + /** + * Replaces the value in the underlying map entry with the specified + * object (optional operation). A lock is obtained on the mutex + * before the map is altered. The map entry, in turn, will alter + * the underlying map object. The operation is undefined if the + * remove() method of the iterator has been called + * beforehand. + * + * @param value the new value to store + * @return the old value + * @throws UnsupportedOperationException if the operation is not supported. + * @throws ClassCastException if the value is of the wrong type. + * @throws IllegalArgumentException if something about the value + * prevents it from existing in this map. + * @throws NullPointerException if the map forbids null values. + */ public Object setValue(Object value) { synchronized (mutex) @@ -2446,6 +3189,13 @@ public class Collections return e.setValue(value); } } + + /** + * Returns a textual representation of the underlying map entry. + * A lock is obtained on the mutex before the entry is accessed. + * + * @return The contents of the map entry in String form. + */ public String toString() { synchronized (mutex) @@ -2461,12 +3211,28 @@ public class Collections { entries = new SynchronizedSet(mutex, m.entrySet()) { - public Iterator iterator() + /** + * Returns an iterator over the set. The iterator has no specific order, + * unless further specified. A lock is obtained on the set's mutex + * before the iterator is created. The created iterator is also + * thread-safe. + * + * @return A synchronized set iterator. + */ + public Iterator iterator() { synchronized (super.mutex) { return new SynchronizedIterator(super.mutex, c.iterator()) { + /** + * Retrieves the next map entry from the iterator. + * A lock is obtained on the iterator's mutex before + * the entry is created. The new map entry is enclosed in + * a thread-safe wrapper. + * + * @return A synchronized map entry. + */ public Object next() { synchronized (super.mutex) @@ -2482,6 +3248,16 @@ public class Collections return entries; } + /** + * Returns true if the object, o, is also an instance + * of Map and contains an equivalent + * entry set to that of the underlying map. A lock + * is obtained on the mutex before the objects are + * compared. + * + * @param o The object to compare. + * @return True if o and the underlying map are equivalent. + */ public boolean equals(Object o) { synchronized (mutex) @@ -2490,6 +3266,21 @@ public class Collections } } + /** + * Returns the value associated with the given key, or null + * if no such mapping exists. An ambiguity exists with maps + * that accept null values as a return value of null could + * be due to a non-existent mapping or simply a null value + * for that key. To resolve this, containsKey + * should be used. A lock is obtained on the mutex before + * the value is retrieved from the underlying map. + * + * @param key The key of the required mapping. + * @return The value associated with the given key, or + * null if no such mapping exists. + * @throws ClassCastException if the key is an inappropriate type. + * @throws NullPointerException if this map does not accept null keys. + */ public Object get(Object key) { synchronized (mutex) @@ -2498,6 +3289,13 @@ public class Collections } } + /** + * Calculates the hash code of the underlying map as the + * sum of the hash codes of all entries. A lock is obtained + * on the mutex before the hash code is computed. + * + * @return The hash code of the underlying map. + */ public int hashCode() { synchronized (mutex) @@ -2506,6 +3304,12 @@ public class Collections } } + /** + * Returns true if the underlying map contains no entries. + * A lock is obtained on the mutex before the map is examined. + * + * @return True if the map is empty. + */ public boolean isEmpty() { synchronized (mutex) @@ -2514,6 +3318,19 @@ public class Collections } } + /** + * Returns a thread-safe set view of the keys in the underlying map. The + * set is backed by the map, so that changes in one show up in the other. + * Modifications made while an iterator is in progress cause undefined + * behavior. If the set supports removal, these methods remove the + * underlying mapping from the map: Iterator.remove, + * Set.remove, removeAll, retainAll, + * and clear. Element addition, via add or + * addAll, is not supported via this set. A lock is obtained + * on the mutex before the set is created. + * + * @return A synchronized set containing the keys of the underlying map. + */ public Set keySet() { if (keys == null) @@ -2524,6 +3341,24 @@ public class Collections return keys; } + /** + * Associates the given key to the given value (optional operation). If the + * underlying map already contains the key, its value is replaced. Be aware + * that in a map that permits null values, a null return does not + * always imply that the mapping was created. A lock is obtained on the mutex + * before the modification is made. + * + * @param key the key to map. + * @param value the value to be mapped. + * @return the previous value of the key, or null if there was no mapping + * @throws UnsupportedOperationException if the operation is not supported + * @throws ClassCastException if the key or value is of the wrong type + * @throws IllegalArgumentException if something about this key or value + * prevents it from existing in this map + * @throws NullPointerException if either the key or the value is null, + * and the map forbids null keys or values + * @see #containsKey(Object) + */ public Object put(Object key, Object value) { synchronized (mutex) @@ -2532,6 +3367,20 @@ public class Collections } } + /** + * Copies all entries of the given map to the underlying one (optional + * operation). If the map already contains a key, its value is replaced. + * A lock is obtained on the mutex before the operation proceeds. + * + * @param m the mapping to load into this map + * @throws UnsupportedOperationException if the operation is not supported + * @throws ClassCastException if a key or value is of the wrong type + * @throws IllegalArgumentException if something about a key or value + * prevents it from existing in this map + * @throws NullPointerException if the map forbids null keys or values, or + * if m is null. + * @see #put(Object, Object) + */ public void putAll(Map map) { synchronized (mutex) @@ -2540,6 +3389,21 @@ public class Collections } } + /** + * Removes the mapping for the key, o, if present (optional operation). If + * the key is not present, this returns null. Note that maps which permit + * null values may also return null if the key was removed. A prior + * containsKey() check is required to avoid this ambiguity. + * Before the mapping is removed, a lock is obtained on the mutex. + * + * @param key the key to remove + * @return the value the key mapped to, or null if not present + * @throws UnsupportedOperationException if deletion is unsupported + * @throws NullPointerException if the key is null and this map doesn't + * support null keys. + * @throws ClassCastException if the type of the key is not a valid type + * for this map. + */ public Object remove(Object o) { synchronized (mutex) @@ -2548,6 +3412,14 @@ public class Collections } } + /** + * Retrieves the size of the underlying map. A lock + * is obtained on the mutex before access takes place. + * Maps with a size greater than Integer.MAX_VALUE + * return Integer.MAX_VALUE instead. + * + * @return The size of the underlying map. + */ public int size() { synchronized (mutex) @@ -2556,6 +3428,13 @@ public class Collections } } + /** + * Returns a textual representation of the underlying + * map. A lock is obtained on the mutex before the map + * is accessed. + * + * @return The map in String form. + */ public String toString() { synchronized (mutex) @@ -2564,6 +3443,20 @@ public class Collections } } + /** + * Returns a synchronized collection view of the values in the underlying + * map. The collection is backed by the map, so that changes in one show up in + * the other. Modifications made while an iterator is in progress cause + * undefined behavior. If the collection supports removal, these methods + * remove the underlying mapping from the map: Iterator.remove, + * Collection.remove, removeAll, + * retainAll, and clear. Element addition, via + * add or addAll, is not supported via this + * collection. A lock is obtained on the mutex before the collection + * is created. + * + * @return the collection of all values in the underlying map. + */ public Collection values() { if (values == null) @@ -2640,6 +3533,16 @@ public class Collections super(sync, s); } + /** + * Returns true if the object, o, is a Set + * of the same size as the underlying set, and contains + * each element, e, which occurs in the underlying set. + * A lock is obtained on the mutex before the comparison + * takes place. + * + * @param o The object to compare against. + * @return True if o is an equivalent set. + */ public boolean equals(Object o) { synchronized (mutex) @@ -2648,6 +3551,14 @@ public class Collections } } + /** + * Computes the hash code for the underlying set as the + * sum of the hash code of all elements within the set. + * A lock is obtained on the mutex before the computation + * occurs. + * + * @return The hash code for the underlying set. + */ public int hashCode() { synchronized (mutex) @@ -2735,6 +3646,13 @@ public class Collections this.sm = sm; } + /** + * Returns the comparator used in sorting the underlying map, or null if + * it is the keys' natural ordering. A lock is obtained on the mutex + * before the comparator is retrieved. + * + * @return the sorting comparator. + */ public Comparator comparator() { synchronized (mutex) @@ -2743,6 +3661,13 @@ public class Collections } } + /** + * Returns the first, lowest sorted, key from the underlying map. + * A lock is obtained on the mutex before the map is accessed. + * + * @return the first key. + * @throws NoSuchElementException if this map is empty. + */ public Object firstKey() { synchronized (mutex) @@ -2751,6 +3676,25 @@ public class Collections } } + /** + * Returns a submap containing the keys from the first + * key (as returned by firstKey()) to + * the key before that specified. The submap supports all + * operations supported by the underlying map and all actions + * taking place on the submap are also reflected in the underlying + * map. A lock is obtained on the mutex prior to submap creation. + * This operation is equivalent to subMap(firstKey(), toKey). + * The submap retains the thread-safe status of this map. + * + * @param toKey the exclusive upper range of the submap. + * @return a submap from firstKey() to the + * the key preceding toKey. + * @throws ClassCastException if toKey is not comparable to the underlying + * map's contents. + * @throws IllegalArgumentException if toKey is outside the map's range. + * @throws NullPointerException if toKey is null. but the map does not allow + * null keys. + */ public SortedMap headMap(Object toKey) { synchronized (mutex) @@ -2759,6 +3703,13 @@ public class Collections } } + /** + * Returns the last, highest sorted, key from the underlying map. + * A lock is obtained on the mutex before the map is accessed. + * + * @return the last key. + * @throws NoSuchElementException if this map is empty. + */ public Object lastKey() { synchronized (mutex) @@ -2767,6 +3718,24 @@ public class Collections } } + /** + * Returns a submap containing the keys from fromKey to + * the key before toKey. The submap supports all + * operations supported by the underlying map and all actions + * taking place on the submap are also reflected in the underlying + * map. A lock is obtained on the mutex prior to submap creation. + * The submap retains the thread-safe status of this map. + * + * @param fromKey the inclusive lower range of the submap. + * @param toKey the exclusive upper range of the submap. + * @return a submap from fromKey to the key preceding toKey. + * @throws ClassCastException if fromKey or toKey is not comparable + * to the underlying map's contents. + * @throws IllegalArgumentException if fromKey or toKey is outside the map's + * range. + * @throws NullPointerException if fromKey or toKey is null. but the map does + * not allow null keys. + */ public SortedMap subMap(Object fromKey, Object toKey) { synchronized (mutex) @@ -2775,6 +3744,22 @@ public class Collections } } + /** + * Returns a submap containing all the keys from fromKey onwards. + * The submap supports all operations supported by the underlying + * map and all actions taking place on the submap are also reflected + * in the underlying map. A lock is obtained on the mutex prior to + * submap creation. The submap retains the thread-safe status of + * this map. + * + * @param fromKey the inclusive lower range of the submap. + * @return a submap from fromKey to lastKey(). + * @throws ClassCastException if fromKey is not comparable to the underlying + * map's contents. + * @throws IllegalArgumentException if fromKey is outside the map's range. + * @throws NullPointerException if fromKey is null. but the map does not allow + * null keys. + */ public SortedMap tailMap(Object fromKey) { synchronized (mutex) @@ -2857,6 +3842,13 @@ public class Collections this.ss = ss; } + /** + * Returns the comparator used in sorting the underlying set, or null if + * it is the elements' natural ordering. A lock is obtained on the mutex + * before the comparator is retrieved. + * + * @return the sorting comparator. + */ public Comparator comparator() { synchronized (mutex) @@ -2865,6 +3857,13 @@ public class Collections } } + /** + * Returns the first, lowest sorted, element from the underlying set. + * A lock is obtained on the mutex before the set is accessed. + * + * @return the first element. + * @throws NoSuchElementException if this set is empty. + */ public Object first() { synchronized (mutex) @@ -2873,6 +3872,25 @@ public class Collections } } + /** + * Returns a subset containing the element from the first + * element (as returned by first()) to + * the element before that specified. The subset supports all + * operations supported by the underlying set and all actions + * taking place on the subset are also reflected in the underlying + * set. A lock is obtained on the mutex prior to subset creation. + * This operation is equivalent to subSet(first(), toElement). + * The subset retains the thread-safe status of this set. + * + * @param toElement the exclusive upper range of the subset. + * @return a subset from first() to the + * the element preceding toElement. + * @throws ClassCastException if toElement is not comparable to the underlying + * set's contents. + * @throws IllegalArgumentException if toElement is outside the set's range. + * @throws NullPointerException if toElement is null. but the set does not allow + * null elements. + */ public SortedSet headSet(Object toElement) { synchronized (mutex) @@ -2881,6 +3899,13 @@ public class Collections } } + /** + * Returns the last, highest sorted, element from the underlying set. + * A lock is obtained on the mutex before the set is accessed. + * + * @return the last element. + * @throws NoSuchElementException if this set is empty. + */ public Object last() { synchronized (mutex) @@ -2889,6 +3914,24 @@ public class Collections } } + /** + * Returns a subset containing the elements from fromElement to + * the element before toElement. The subset supports all + * operations supported by the underlying set and all actions + * taking place on the subset are also reflected in the underlying + * set. A lock is obtained on the mutex prior to subset creation. + * The subset retains the thread-safe status of this set. + * + * @param fromElement the inclusive lower range of the subset. + * @param toElement the exclusive upper range of the subset. + * @return a subset from fromElement to the element preceding toElement. + * @throws ClassCastException if fromElement or toElement is not comparable + * to the underlying set's contents. + * @throws IllegalArgumentException if fromElement or toElement is outside the set's + * range. + * @throws NullPointerException if fromElement or toElement is null. but the set does + * not allow null elements. + */ public SortedSet subSet(Object fromElement, Object toElement) { synchronized (mutex) @@ -2898,6 +3941,22 @@ public class Collections } } + /** + * Returns a subset containing all the elements from fromElement onwards. + * The subset supports all operations supported by the underlying + * set and all actions taking place on the subset are also reflected + * in the underlying set. A lock is obtained on the mutex prior to + * subset creation. The subset retains the thread-safe status of + * this set. + * + * @param fromElement the inclusive lower range of the subset. + * @return a subset from fromElement to last(). + * @throws ClassCastException if fromElement is not comparable to the underlying + * set's contents. + * @throws IllegalArgumentException if fromElement is outside the set's range. + * @throws NullPointerException if fromElement is null. but the set does not allow + * null elements. + */ public SortedSet tailSet(Object fromElement) { synchronized (mutex) @@ -2912,7 +3971,9 @@ public class Collections * Returns an unmodifiable view of the given collection. This allows * "read-only" access, although changes in the backing collection show up * in this view. Attempts to modify the collection directly or via iterators - * will fail with address@hidden UnsupportedOperationException}. + * will fail with address@hidden UnsupportedOperationException}. Although this view + * prevents changes to the structure of the collection and its elements, the values + * referenced by the objects in the collection can still be modified. *

* * Since the collection might be a List or a Set, and those have incompatible @@ -2962,71 +4023,197 @@ public class Collections throw new NullPointerException(); } + /** + * Blocks the addition of elements to the underlying collection. + * This method never returns, throwing an exception instead. + * + * @param o the object to add. + * @return true if the collection was modified as a result of this action. + * @throws UnsupportedOperationException as an unmodifiable collection does not + * support the add operation. + */ public boolean add(Object o) { throw new UnsupportedOperationException(); } + /** + * Blocks the addition of a collection of elements to the underlying + * collection. This method never returns, throwing an exception instead. + * + * @param c the collection to add. + * @return true if the collection was modified as a result of this action. + * @throws UnsupportedOperationException as an unmodifiable collection does not + * support the addAll operation. + */ public boolean addAll(Collection c) { throw new UnsupportedOperationException(); } + /** + * Blocks the clearing of the underlying collection. This method never + * returns, throwing an exception instead. + * + * @throws UnsupportedOperationException as an unmodifiable collection does + * not support the clear() operation. + */ public void clear() { throw new UnsupportedOperationException(); } + /** + * Test whether the underlying collection contains a given object as one of its + * elements. + * + * @param o the element to look for. + * @return true if the underlying collection contains at least one element e such + * that o == null ? e == null : o.equals(e). + * @throws ClassCastException if the type of o is not a valid type for the + * underlying collection. + * @throws NullPointerException if o is null and the underlying collection + * doesn't support null values. + */ public boolean contains(Object o) { return c.contains(o); } + /** + * Test whether the underlying collection contains every element in a given + * collection. + * + * @param c the collection to test for. + * @return true if for every element o in c, contains(o) would return true. + * @throws ClassCastException if the type of any element in c is not a valid + * type for the underlying collection. + * @throws NullPointerException if some element of c is null and the underlying + * collection does not support null values. + * @throws NullPointerException if c itself is null. + */ public boolean containsAll(Collection c1) { return c.containsAll(c1); } + /** + * Tests whether the underlying collection is empty, that is, + * if size() == 0. + * + * @return true if this collection contains no elements. + */ public boolean isEmpty() { return c.isEmpty(); } + /** + * Obtain an Iterator over the underlying collection, which maintains + * its unmodifiable nature. + * + * @return an UnmodifiableIterator over the elements of the underlying + * collection, in any order. + */ public Iterator iterator() { return new UnmodifiableIterator(c.iterator()); } + /** + * Blocks the removal of an object from the underlying collection. + * This method never returns, throwing an exception instead. + * + * @param o The object to remove. + * @return true if the object was removed (i.e. the underlying + * collection returned 1 or more instances of o). + * @throws UnsupportedOperationException as an unmodifiable collection + * does not support the remove() operation. + */ public boolean remove(Object o) { throw new UnsupportedOperationException(); } + /** + * Blocks the removal of a collection of objects from the underlying + * collection. This method never returns, throwing an exception + * instead. + * + * @param c The collection of objects to remove. + * @return true if the collection was modified. + * @throws UnsupportedOperationException as an unmodifiable collection + * does not support the removeAll() operation. + */ public boolean removeAll(Collection c) { throw new UnsupportedOperationException(); } + /** + * Blocks the removal of all elements from the underlying collection, + * except those in the supplied collection. This method never returns, + * throwing an exception instead. + * + * @param c The collection of objects to retain. + * @return true if the collection was modified. + * @throws UnsupportedOperationException as an unmodifiable collection + * does not support the retainAll() operation. + */ public boolean retainAll(Collection c) { throw new UnsupportedOperationException(); } + /** + * Retrieves the number of elements in the underlying collection. + * + * @return the number of elements in the collection. + */ public int size() { return c.size(); } + /** + * Copy the current contents of the underlying collection into an array. + * + * @return an array of type Object[] with a length equal to the size of the + * underlying collection and containing the elements currently in + * the underlying collection, in any order. + */ public Object[] toArray() { return c.toArray(); } + /** + * Copy the current contents of the underlying collection into an array. If + * the array passed as an argument has length less than the size of the + * underlying collection, an array of the same run-time type as a, with a length + * equal to the size of the underlying collection, is allocated using reflection. + * Otherwise, a itself is used. The elements of the underlying collection are + * copied into it, and if there is space in the array, the following element is + * set to null. The resultant array is returned. + * Note: The fact that the following element is set to null is only useful + * if it is known that this collection does not contain any null elements. + * + * @param a the array to copy this collection into. + * @return an array containing the elements currently in the underlying + * collection, in any order. + * @throws ArrayStoreException if the type of any element of the + * collection is not a subtype of the element type of a. + */ public Object[] toArray(Object[] a) { return c.toArray(a); } + /** + * A textual representation of the unmodifiable collection. + * + * @return The unmodifiable collection in the form of a String. + */ public String toString() { return c.toString(); @@ -3055,16 +4242,37 @@ public class Collections this.i = i; } + /** + * Obtains the next element in the underlying collection. + * + * @return the next element in the collection. + * @throws NoSuchElementException if there are no more elements. + */ public Object next() { return i.next(); } - + /** + * Tests whether there are still elements to be retrieved from the + * underlying collection by next(). When this method + * returns true, an exception will not be thrown on calling + * next(). + * + * @return true if there is at least one more element in the underlying + * collection. + */ public boolean hasNext() { return i.hasNext(); } + /** + * Blocks the removal of elements from the underlying collection by the + * iterator. + * + * @throws UnsupportedOperationException as an unmodifiable collection + * does not support the removal of elements by its iterator. + */ public void remove() { throw new UnsupportedOperationException(); @@ -3076,6 +4284,9 @@ public class Collections * "read-only" access, although changes in the backing list show up * in this view. Attempts to modify the list directly, via iterators, or * via sublists, will fail with address@hidden UnsupportedOperationException}. + * Although this view prevents changes to the structure of the list and + * its elements, the values referenced by the objects in the list can + * still be modified. *

* * The returned List implements Serializable, but can only be serialized if @@ -3128,61 +4339,184 @@ public class Collections list = l; } + /** + * Blocks the addition of an element to the underlying + * list at a specific index. This method never returns, + * throwing an exception instead. + * + * @param index The index at which to place the new element. + * @param o the object to add. + * @throws UnsupportedOperationException as an unmodifiable + * list doesn't support the add() operation. + */ public void add(int index, Object o) { throw new UnsupportedOperationException(); } + /** + * Blocks the addition of a collection of elements to the + * underlying list at a specific index. This method never + * returns, throwing an exception instead. + * + * @param index The index at which to place the new element. + * @param c the collections of objects to add. + * @throws UnsupportedOperationException as an unmodifiable + * list doesn't support the addAll() operation. + */ public boolean addAll(int index, Collection c) { throw new UnsupportedOperationException(); } + /** + * Returns true if the object, o, is an instance of + * List with the same size and elements + * as the underlying list. + * + * @param o The object to compare. + * @return True if o is equivalent to the underlying list. + */ public boolean equals(Object o) { return list.equals(o); } + /** + * Retrieves the element at a given index in the underlying list. + * + * @param index the index of the element to be returned + * @return the element at index index in this list + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + */ public Object get(int index) { return list.get(index); } + /** + * Computes the hash code for the underlying list. + * The exact computation is described in the documentation + * of the List interface. + * + * @return The hash code of the underlying list. + * @see List#hashCode() + */ public int hashCode() { return list.hashCode(); } + /** + * Obtain the first index at which a given object is to be found in the + * underlying list. + * + * @param o the object to search for + * @return the least integer n such that o == null ? get(n) == null : + * o.equals(get(n)), or -1 if there is no such index. + * @throws ClassCastException if the type of o is not a valid + * type for the underlying list. + * @throws NullPointerException if o is null and the underlying + * list does not support null values. + */ public int indexOf(Object o) { return list.indexOf(o); } + /** + * Obtain the last index at which a given object is to be found in the + * underlying list. + * + * @return the greatest integer n such that o == null ? get(n) == null + * : o.equals(get(n)), or -1 if there is no such index. + * @throws ClassCastException if the type of o is not a valid + * type for the underlying list. + * @throws NullPointerException if o is null and the underlying + * list does not support null values. + */ public int lastIndexOf(Object o) { return list.lastIndexOf(o); } + /** + * Obtains a list iterator over the underlying list, starting at the beginning + * and maintaining the unmodifiable nature of this list. + * + * @return a UnmodifiableListIterator over the elements of the + * underlying list, in order, starting at the beginning. + */ public ListIterator listIterator() { return new UnmodifiableListIterator(list.listIterator()); } + /** + * Obtains a list iterator over the underlying list, starting at the specified + * index and maintaining the unmodifiable nature of this list. An initial call + * to next() will retrieve the element at the specified index, + * and an initial call to previous() will retrieve the element + * at index - 1. + * + * + * @param index the position, between 0 and size() inclusive, to begin the + * iteration from. + * @return a UnmodifiableListIterator over the elements of the + * underlying list, in order, starting at the specified index. + * @throws IndexOutOfBoundsException if index < 0 || index > size() + */ public ListIterator listIterator(int index) { return new UnmodifiableListIterator(list.listIterator(index)); } + /** + * Blocks the removal of the element at the specified index. + * This method never returns, throwing an exception instead. + * + * @param index The index of the element to remove. + * @return the removed element. + * @throws UnsupportedOperationException as an unmodifiable + * list does not support the remove() + * operation. + */ public Object remove(int index) { throw new UnsupportedOperationException(); } + /** + * Blocks the replacement of the element at the specified index. + * This method never returns, throwing an exception instead. + * + * @param index The index of the element to replace. + * @param o The new object to place at the specified index. + * @return the replaced element. + * @throws UnsupportedOperationException as an unmodifiable + * list does not support the set() + * operation. + */ public Object set(int index, Object o) { throw new UnsupportedOperationException(); } + /** + * Obtain a List view of a subsection of the underlying list, from + * fromIndex (inclusive) to toIndex (exclusive). If the two indices + * are equal, the sublist is empty. The returned list will be + * unmodifiable, like this list. Changes to the elements of the + * returned list will be reflected in the underlying list. No structural + * modifications can take place in either list. + * + * @param fromIndex the index that the returned list should start from + * (inclusive). + * @param toIndex the index that the returned list should go to (exclusive). + * @return a List backed by a subsection of the underlying list. + * @throws IndexOutOfBoundsException if fromIndex < 0 + * || toIndex > size() || fromIndex > toIndex. + */ public List subList(int fromIndex, int toIndex) { return unmodifiableList(list.subList(fromIndex, toIndex)); @@ -3239,31 +4573,76 @@ public class Collections this.li = li; } + /** + * Blocks the addition of an object to the list underlying this iterator. + * This method never returns, throwing an exception instead. + * + * @param o The object to add. + * @throws UnsupportedOperationException as the iterator of an unmodifiable + * list does not support the add() operation. + */ public void add(Object o) { throw new UnsupportedOperationException(); } + /** + * Tests whether there are still elements to be retrieved from the + * underlying collection by previous(). When this method + * returns true, an exception will not be thrown on calling + * previous(). + * + * @return true if there is at least one more element prior to the + * current position in the underlying list. + */ public boolean hasPrevious() { return li.hasPrevious(); } + /** + * Find the index of the element that would be returned by a call to next. + * If hasNext() returns false, this returns the list size. + * + * @return the index of the element that would be returned by + * next(). + */ public int nextIndex() { return li.nextIndex(); } + /** + * Obtains the previous element in the underlying list. + * + * @return the previous element in the list. + * @throws NoSuchElementException if there are no more prior elements. + */ public Object previous() { return li.previous(); } + /** + * Find the index of the element that would be returned by a call to + * previous. If hasPrevious() returns false, this returns -1. + * + * @return the index of the element that would be returned by + * previous(). + */ public int previousIndex() { return li.previousIndex(); } + /** + * Blocks the replacement of an element in the list underlying this + * iterator. This method never returns, throwing an exception instead. + * + * @param o The new object to replace the existing one. + * @throws UnsupportedOperationException as the iterator of an unmodifiable + * list does not support the set() operation. + */ public void set(Object o) { throw new UnsupportedOperationException(); @@ -3275,6 +4654,9 @@ public class Collections * access, although changes in the backing map show up in this view. * Attempts to modify the map directly, or via collection views or their * iterators will fail with address@hidden UnsupportedOperationException}. + * Although this view prevents changes to the structure of the map and its + * entries, the values referenced by the objects in the map can still be + * modified. *

* * The returned Map implements Serializable, but can only be serialized if @@ -3335,21 +4717,62 @@ public class Collections throw new NullPointerException(); } + /** + * Blocks the clearing of entries from the underlying map. + * This method never returns, throwing an exception instead. + * + * @throws UnsupportedOperationException as an unmodifiable + * map does not support the clear() operation. + */ public void clear() { throw new UnsupportedOperationException(); } + /** + * Returns true if the underlying map contains a mapping for + * the given key. + * + * @param key the key to search for + * @return true if the map contains the key + * @throws ClassCastException if the key is of an inappropriate type + * @throws NullPointerException if key is null but the map + * does not permit null keys + */ public boolean containsKey(Object key) { return m.containsKey(key); } + /** + * Returns true if the underlying map contains at least one mapping with + * the given value. In other words, it returns true if a value v exists where + * (value == null ? v == null : value.equals(v)). This usually + * requires linear time. + * + * @param value the value to search for + * @return true if the map contains the value + * @throws ClassCastException if the type of the value is not a valid type + * for this map. + * @throws NullPointerException if the value is null and the map doesn't + * support null values. + */ public boolean containsValue(Object value) { return m.containsValue(value); } + /** + * Returns a unmodifiable set view of the entries in the underlying map. + * Each element in the set is a unmodifiable variant of Map.Entry. + * The set is backed by the map, so that changes in one show up in the other. + * Modifications made while an iterator is in progress cause undefined + * behavior. These modifications are again limited to the values of + * the objects. + * + * @return the unmodifiable set view of all mapping entries. + * @see Map.Entry + */ public Set entrySet() { if (entries == null) @@ -3385,31 +4808,82 @@ public class Collections { return new UnmodifiableIterator(c.iterator()) { + /** + * Obtains the next element from the underlying set of + * map entries. + * + * @return the next element in the collection. + * @throws NoSuchElementException if there are no more elements. + */ public Object next() { final Map.Entry e = (Map.Entry) super.next(); return new Map.Entry() { + /** + * Returns true if the object, o, is also a map entry with an + * identical key and value. + * + * @param o the object to compare. + * @return true if o is an equivalent map entry. + */ public boolean equals(Object o) { return e.equals(o); } + + /** + * Returns the key of this map entry. + * + * @return the key. + */ public Object getKey() { return e.getKey(); } + + /** + * Returns the value of this map entry. + * + * @return the value. + */ public Object getValue() { return e.getValue(); } + + /** + * Computes the hash code of this map entry. + * The computation is described in the Map + * interface documentation. + * + * @return the hash code of this entry. + * @see Map#hashCode() + */ public int hashCode() { return e.hashCode(); } + + /** + * Blocks the alteration of the value of this map entry. + * This method never returns, throwing an exception instead. + * + * @param value The new value. + * @throws UnsupportedOperationException as an unmodifiable + * map entry does not support the setValue() + * operation. + */ public Object setValue(Object value) { throw new UnsupportedOperationException(); } + + /** + * Returns a textual representation of the map entry. + * + * @return The map entry as a String. + */ public String toString() { return e.toString(); @@ -3420,31 +4894,82 @@ public class Collections } } // class UnmodifiableEntrySet + /** + * Returns true if the object, o, is also an instance + * of Map with an equal set of map entries. + * + * @param o The object to compare. + * @return true if o is an equivalent map. + */ public boolean equals(Object o) { return m.equals(o); } + /** + * Returns the value associated with the supplied key or + * null if no such mapping exists. An ambiguity can occur + * if null values are accepted by the underlying map. + * In this case, containsKey() can be used + * to separate the two possible cases of a null result. + * + * @param key The key to look up. + * @return the value associated with the key, or null if key not in map. + * @throws ClassCastException if the key is an inappropriate type. + * @throws NullPointerException if this map does not accept null keys. + * @see #containsKey(Object) + */ public Object get(Object key) { return m.get(key); } + /** + * Blocks the addition of a new entry to the underlying map. + * This method never returns, throwing an exception instead. + * + * @param key The new key. + * @param value The new value. + * @return the previous value of the key, or null if there was no mapping. + * @throws UnsupportedOperationException as an unmodifiable + * map does not support the put() operation. + */ public Object put(Object key, Object value) { throw new UnsupportedOperationException(); } + /** + * Computes the hash code for the underlying map, as the sum + * of the hash codes of all entries. + * + * @return The hash code of the underlying map. + * @see Map.Entry#hashCode() + */ public int hashCode() { return m.hashCode(); } + /** + * Returns true if the underlying map contains no entries. + * + * @return true if the map is empty. + */ public boolean isEmpty() { return m.isEmpty(); } + /** + * Returns a unmodifiable set view of the keys in the underlying map. + * The set is backed by the map, so that changes in one show up in the other. + * Modifications made while an iterator is in progress cause undefined + * behavior. These modifications are again limited to the values of + * the keys. + * + * @return the set view of all keys. + */ public Set keySet() { if (keys == null) @@ -3452,26 +4977,68 @@ public class Collections return keys; } + /** + * Blocks the addition of the entries in the supplied map. + * This method never returns, throwing an exception instead. + * + * @param m The map, the entries of which should be added + * to the underlying map. + * @throws UnsupportedOperationException as an unmodifiable + * map does not support the putAll operation. + */ public void putAll(Map m) { throw new UnsupportedOperationException(); } + /** + * Blocks the removal of an entry from the map. + * This method never returns, throwing an exception instead. + * + * @param o The key of the entry to remove. + * @return The value the key was associated with, or null + * if no such mapping existed. Null is also returned + * if the removed entry had a null key. + * @throws UnsupportedOperationException as an unmodifiable + * map does not support the remove operation. + */ public Object remove(Object o) { throw new UnsupportedOperationException(); } + + /** + * Returns the number of key-value mappings in the underlying map. + * If there are more than Integer.MAX_VALUE mappings, Integer.MAX_VALUE + * is returned. + * + * @return the number of mappings. + */ public int size() { return m.size(); } + /** + * Returns a textual representation of the map. + * + * @return The map in the form of a String. + */ public String toString() { return m.toString(); } + /** + * Returns a unmodifiable collection view of the values in the underlying map. + * The collection is backed by the map, so that changes in one show up in the other. + * Modifications made while an iterator is in progress cause undefined + * behavior. These modifications are again limited to the values of + * the keys. + * + * @return the collection view of all values. + */ public Collection values() { if (values == null) @@ -3485,6 +5052,9 @@ public class Collections * "read-only" access, although changes in the backing set show up * in this view. Attempts to modify the set directly or via iterators * will fail with address@hidden UnsupportedOperationException}. + * Although this view prevents changes to the structure of the set and its + * entries, the values referenced by the objects in the set can still be + * modified. *

* * The returned Set implements Serializable, but can only be serialized if @@ -3523,11 +5093,23 @@ public class Collections super(s); } + /** + * Returns true if the object, o, is also an instance of + * Set of the same size and with the same entries. + * + * @return true if o is an equivalent set. + */ public boolean equals(Object o) { return c.equals(o); } + /** + * Computes the hash code of this set, as the sum of the + * hash codes of all elements within the set. + * + * @return the hash code of the set. + */ public int hashCode() { return c.hashCode(); @@ -3539,6 +5121,9 @@ public class Collections * "read-only" access, although changes in the backing map show up in this * view. Attempts to modify the map directly, via subviews, via collection * views, or iterators, will fail with address@hidden UnsupportedOperationException}. + * Although this view prevents changes to the structure of the map and its + * entries, the values referenced by the objects in the map can still be + * modified. *

* * The returned SortedMap implements Serializable, but can only be @@ -3585,31 +5170,119 @@ public class Collections this.sm = sm; } + /** + * Returns the comparator used in sorting the underlying map, + * or null if it is the keys' natural ordering. + * + * @return the sorting comparator. + */ public Comparator comparator() { return sm.comparator(); } + /** + * Returns the first (lowest sorted) key in the map. + * + * @return the first key. + * @throws NoSuchElementException if this map is empty. + */ public Object firstKey() { return sm.firstKey(); } + /** + * Returns a unmodifiable view of the portion of the map strictly less + * than toKey. The view is backed by the underlying map, so changes in + * one show up in the other. The submap supports all optional operations + * of the original. This operation is equivalent to + * subMap(firstKey(), toKey). + *

+ * + * The returned map throws an IllegalArgumentException any time a key is + * used which is out of the range of toKey. Note that the endpoint, toKey, + * is not included; if you want this value to be included, pass its successor + * object in to toKey. For example, for Integers, you could request + * headMap(new Integer(limit.intValue() + 1)). + * + * @param toKey the exclusive upper range of the submap. + * @return the submap. + * @throws ClassCastException if toKey is not comparable to the map contents. + * @throws IllegalArgumentException if this is a subMap, and toKey is out + * of range. + * @throws NullPointerException if toKey is null but the map does not allow + * null keys. + */ public SortedMap headMap(Object toKey) { return new UnmodifiableSortedMap(sm.headMap(toKey)); } + /** + * Returns the last (highest sorted) key in the map. + * + * @return the last key. + * @throws NoSuchElementException if this map is empty. + */ public Object lastKey() { return sm.lastKey(); } + /** + * Returns a unmodifiable view of the portion of the map greater than or + * equal to fromKey, and strictly less than toKey. The view is backed by + * the underlying map, so changes in one show up in the other. The submap + * supports all optional operations of the original. + *

+ * + * The returned map throws an IllegalArgumentException any time a key is + * used which is out of the range of fromKey and toKey. Note that the + * lower endpoint is included, but the upper is not; if you want to + * change the inclusion or exclusion of an endpoint, pass its successor + * object in instead. For example, for Integers, you could request + * subMap(new Integer(lowlimit.intValue() + 1), + * new Integer(highlimit.intValue() + 1)) to reverse + * the inclusiveness of both endpoints. + * + * @param fromKey the inclusive lower range of the submap. + * @param toKey the exclusive upper range of the submap. + * @return the submap. + * @throws ClassCastException if fromKey or toKey is not comparable to + * the map contents. + * @throws IllegalArgumentException if this is a subMap, and fromKey or + * toKey is out of range. + * @throws NullPointerException if fromKey or toKey is null but the map + * does not allow null keys. + */ public SortedMap subMap(Object fromKey, Object toKey) { return new UnmodifiableSortedMap(sm.subMap(fromKey, toKey)); } + /** + * Returns a unmodifiable view of the portion of the map greater than or + * equal to fromKey. The view is backed by the underlying map, so changes + * in one show up in the other. The submap supports all optional operations + * of the original. + *

+ * + * The returned map throws an IllegalArgumentException any time a key is + * used which is out of the range of fromKey. Note that the endpoint, fromKey, is + * included; if you do not want this value to be included, pass its successor object in + * to fromKey. For example, for Integers, you could request + * tailMap(new Integer(limit.intValue() + 1)). + * + * @param fromKey the inclusive lower range of the submap + * @return the submap + * @throws ClassCastException if fromKey is not comparable to the map + * contents + * @throws IllegalArgumentException if this is a subMap, and fromKey is out + * of range + * @throws NullPointerException if fromKey is null but the map does not allow + * null keys + */ public SortedMap tailMap(Object fromKey) { return new UnmodifiableSortedMap(sm.tailMap(fromKey)); @@ -3621,6 +5294,9 @@ public class Collections * "read-only" access, although changes in the backing set show up * in this view. Attempts to modify the set directly, via subsets, or via * iterators, will fail with address@hidden UnsupportedOperationException}. + * Although this view prevents changes to the structure of the set and its + * entries, the values referenced by the objects in the set can still be + * modified. *

* * The returns SortedSet implements Serializable, but can only be @@ -3667,31 +5343,121 @@ public class Collections this.ss = ss; } + /** + * Returns the comparator used in sorting the underlying set, + * or null if it is the elements' natural ordering. + * + * @return the sorting comparator + */ public Comparator comparator() { return ss.comparator(); } + /** + * Returns the first (lowest sorted) element in the underlying + * set. + * + * @return the first element. + * @throws NoSuchElementException if the set is empty. + */ public Object first() { return ss.first(); } + /** + * Returns a unmodifiable view of the portion of the set strictly + * less than toElement. The view is backed by the underlying set, + * so changes in one show up in the other. The subset supports + * all optional operations of the original. This operation + * is equivalent to subSet(first(), toElement). + *

+ * + * The returned set throws an IllegalArgumentException any time an element is + * used which is out of the range of toElement. Note that the endpoint, toElement, + * is not included; if you want this value included, pass its successor object in to + * toElement. For example, for Integers, you could request + * headSet(new Integer(limit.intValue() + 1)). + * + * @param toElement the exclusive upper range of the subset + * @return the subset. + * @throws ClassCastException if toElement is not comparable to the set + * contents. + * @throws IllegalArgumentException if this is a subSet, and toElement is out + * of range. + * @throws NullPointerException if toElement is null but the set does not + * allow null elements. + */ public SortedSet headSet(Object toElement) { return new UnmodifiableSortedSet(ss.headSet(toElement)); } + /** + * Returns the last (highest sorted) element in the underlying + * set. + * + * @return the last element. + * @throws NoSuchElementException if the set is empty. + */ public Object last() { return ss.last(); } + /** + * Returns a unmodifiable view of the portion of the set greater than or + * equal to fromElement, and strictly less than toElement. The view is backed by + * the underlying set, so changes in one show up in the other. The subset + * supports all optional operations of the original. + *

+ * + * The returned set throws an IllegalArgumentException any time an element is + * used which is out of the range of fromElement and toElement. Note that the + * lower endpoint is included, but the upper is not; if you want to + * change the inclusion or exclusion of an endpoint, pass its successor + * object in instead. For example, for Integers, you can request + * subSet(new Integer(lowlimit.intValue() + 1), + * new Integer(highlimit.intValue() + 1)) to reverse + * the inclusiveness of both endpoints. + * + * @param fromElement the inclusive lower range of the subset. + * @param toElement the exclusive upper range of the subset. + * @return the subset. + * @throws ClassCastException if fromElement or toElement is not comparable + * to the set contents. + * @throws IllegalArgumentException if this is a subSet, and fromElement or + * toElement is out of range. + * @throws NullPointerException if fromElement or toElement is null but the + * set does not allow null elements. + */ public SortedSet subSet(Object fromElement, Object toElement) { return new UnmodifiableSortedSet(ss.subSet(fromElement, toElement)); } + /** + * Returns a unmodifiable view of the portion of the set greater than or equal to + * fromElement. The view is backed by the underlying set, so changes in one show up + * in the other. The subset supports all optional operations of the original. + *

+ * + * The returned set throws an IllegalArgumentException any time an element is + * used which is out of the range of fromElement. Note that the endpoint, + * fromElement, is included; if you do not want this value to be included, pass its + * successor object in to fromElement. For example, for Integers, you could request + * tailSet(new Integer(limit.intValue() + 1)). + * + * @param fromElement the inclusive lower range of the subset + * @return the subset. + * @throws ClassCastException if fromElement is not comparable to the set + * contents. + * @throws IllegalArgumentException if this is a subSet, and fromElement is + * out of range. + * @throws NullPointerException if fromElement is null but the set does not + * allow null elements. + */ public SortedSet tailSet(Object fromElement) { return new UnmodifiableSortedSet(ss.tailSet(fromElement)); Index: java/util/SortedMap.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/SortedMap.java,v retrieving revision 1.7 diff -u -3 -p -u -r1.7 SortedMap.java --- java/util/SortedMap.java 29 Jul 2004 20:23:18 -0000 1.7 +++ java/util/SortedMap.java 1 Sep 2004 16:13:12 -0000 @@ -97,10 +97,10 @@ public interface SortedMap extends Map *

* * The returned map throws an IllegalArgumentException any time a key is - * used which is out of the range of toKey. Note that the endpoint is not - * included; if you want the endpoint, pass the successor object in to - * toKey. For example, for Strings, you can request - * headMap(limit + "\0"). + * used which is out of the range of toKey. Note that the endpoint, toKey, + * is not included; if you want this value to be included, pass its successor + * object in to toKey. For example, for Integers, you could request + * headMap(new Integer(limit.intValue() + 1)). * * @param toKey the exclusive upper range of the submap * @return the submap @@ -130,9 +130,10 @@ public interface SortedMap extends Map * The returned map throws an IllegalArgumentException any time a key is * used which is out of the range of fromKey and toKey. Note that the * lower endpoint is included, but the upper is not; if you want to - * change the inclusion or exclusion of an endpoint, pass the successor - * object in instead. For example, for Strings, you can request - * subMap(lowlimit + "\0", highlimit + "\0") to reverse + * change the inclusion or exclusion of an endpoint, pass its successor + * object in instead. For example, for Integers, you could request + * subMap(new Integer(lowlimit.intValue() + 1), + * new Integer(highlimit.intValue() + 1)) to reverse * the inclusiveness of both endpoints. * * @param fromKey the inclusive lower range of the submap @@ -154,10 +155,10 @@ public interface SortedMap extends Map *

* * The returned map throws an IllegalArgumentException any time a key is - * used which is out of the range of fromKey. Note that the endpoint is - * included; if you do not want the endpoint, pass the successor object in - * to fromKey. For example, for Strings, you can request - * tailMap(limit + "\0"). + * used which is out of the range of fromKey. Note that the endpoint, fromKey, is + * included; if you do not want this value to be included, pass its successor object in + * to fromKey. For example, for Integers, you could request + * tailMap(new Integer(limit.intValue() + 1)). * * @param fromKey the inclusive lower range of the submap * @return the submap Index: java/util/SortedSet.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/SortedSet.java,v retrieving revision 1.8 diff -u -3 -p -u -r1.8 SortedSet.java --- java/util/SortedSet.java 17 Aug 2004 22:19:57 -0000 1.8 +++ java/util/SortedSet.java 1 Sep 2004 16:13:12 -0000 @@ -99,10 +99,10 @@ public interface SortedSet extends Set *

* * The returned set throws an IllegalArgumentException any time an element is - * used which is out of the range of toElement. Note that the endpoint is not - * included; if you want the endpoint, pass the successor object in to - * toElement. For example, for Strings, you can request - * headSet(limit + "\0"). + * used which is out of the range of toElement. Note that the endpoint, toElement, + * is not included; if you want this value included, pass its successor object in to + * toElement. For example, for Integers, you could request + * headSet(new Integer(limit.intValue() + 1)). * * @param toElement the exclusive upper range of the subset * @return the subset @@ -133,9 +133,10 @@ public interface SortedSet extends Set * The returned set throws an IllegalArgumentException any time an element is * used which is out of the range of fromElement and toElement. Note that the * lower endpoint is included, but the upper is not; if you want to - * change the inclusion or exclusion of an endpoint, pass the successor - * object in instead. For example, for Strings, you can request - * subSet(lowlimit + "\0", highlimit + "\0") to reverse + * change the inclusion or exclusion of an endpoint, pass its successor + * object in instead. For example, for Integers, you can request + * subSet(new Integer(lowlimit.intValue() + 1), + * new Integer(highlimit.intValue() + 1)) to reverse * the inclusiveness of both endpoints. * * @param fromElement the inclusive lower range of the subset @@ -157,10 +158,10 @@ public interface SortedSet extends Set *

* * The returned set throws an IllegalArgumentException any time an element is - * used which is out of the range of fromElement. Note that the endpoint is - * included; if you do not want the endpoint, pass the successor object in - * to fromElement. For example, for Strings, you can request - * tailSet(limit + "\0"). + * used which is out of the range of fromElement. Note that the endpoint, + * fromElement, is included; if you do not want this value to be included, pass its + * successor object in to fromElement. For example, for Integers, you could request + * tailSet(new Integer(limit.intValue() + 1)). * * @param fromElement the inclusive lower range of the subset * @return the subset