From 95808ab06657ff4f73314ae406076fe96f73baee Mon Sep 17 00:00:00 2001 From: mark Date: Sun, 7 Nov 2004 11:42:22 +0000 Subject: [PATCH] 2004-11-07 Andrew John Hughes * java/util/Collections.java Added documentation. * java/util/SortedMap.java Clarified some method examples. * java/util/SortedSet.java Clarified some method examples. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@90227 138bc75d-0d04-0410-961f-82ee72b054a4 --- libjava/ChangeLog | 9 + libjava/java/util/Collections.java | 1810 +++++++++++++++++++++++++++++++++++- libjava/java/util/SortedMap.java | 23 +- libjava/java/util/SortedSet.java | 23 +- 4 files changed, 1827 insertions(+), 38 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index 8a5a54cf3f8..2521bf0b4de 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,5 +1,14 @@ 2004-11-07 Andrew John Hughes + * java/util/Collections.java + Added documentation. + * java/util/SortedMap.java + Clarified some method examples. + * java/util/SortedSet.java + Clarified some method examples. + +2004-11-07 Andrew John Hughes + * java/util/Currency.java Documented variables and methods more fully. Caches the currency instances, so that a request diff --git a/libjava/java/util/Collections.java b/libjava/java/util/Collections.java index 5ae4b40389a..6da84296e7e 100644 --- a/libjava/java/util/Collections.java +++ b/libjava/java/util/Collections.java @@ -75,7 +75,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; @@ -88,7 +88,7 @@ public class Collections * and exceeds a large (unspecified) size should be sequential. * * @param l the list to check - * @return true if it should be treated as sequential-access + * @return true if it should be treated as sequential-access */ private static boolean isSequential(List l) { @@ -131,6 +131,7 @@ public class Collections /** * The size: always 0! + * @return 0. */ public int size() { @@ -139,6 +140,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() @@ -150,6 +152,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) { @@ -158,6 +162,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) { @@ -166,6 +173,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) { @@ -174,6 +183,7 @@ public class Collections /** * The hashcode is always 0. + * @return 0. */ public int hashCode() { @@ -181,7 +191,9 @@ public class Collections } /** - * Always succeeds with false result. + * Always succeeds with a false result. + * @param o The object to remove. + * @return false. */ public boolean remove(Object o) { @@ -189,7 +201,10 @@ public class Collections } /** - * Always succeeds with false result. + * Always succeeds with a false result. + * @param c The collection of objects which should + * all be removed from this set. + * @return false. */ public boolean removeAll(Collection c) { @@ -197,7 +212,10 @@ public class Collections } /** - * Always succeeds with false result. + * Always succeeds with a false result. + * @param c The collection of objects which should + * all be retained within this set. + * @return false. */ public boolean retainAll(Collection c) { @@ -206,6 +224,7 @@ public class Collections /** * The array is always empty. + * @return A new array with a size of 0. */ public Object[] toArray() { @@ -214,6 +233,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) { @@ -224,6 +246,8 @@ public class Collections /** * The string never changes. + * + * @return the string "[]". */ public String toString() { @@ -261,6 +285,7 @@ public class Collections /** * The size is always 0. + * @return 0. */ public int size() { @@ -268,7 +293,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) { @@ -279,6 +310,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) { @@ -287,6 +320,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) { @@ -294,7 +330,10 @@ 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) { @@ -303,6 +342,7 @@ public class Collections /** * The hashcode is always 1. + * @return 1. */ public int hashCode() { @@ -311,6 +351,8 @@ public class Collections /** * Returns -1. + * @param o The object to search for. + * @return -1. */ public int indexOf(Object o) { @@ -319,6 +361,8 @@ public class Collections /** * Returns -1. + * @param o The object to search for. + * @return -1. */ public int lastIndexOf(Object o) { @@ -326,7 +370,9 @@ public class Collections } /** - * Always succeeds with false result. + * Always succeeds with false result. + * @param o The object to remove. + * @return -1. */ public boolean remove(Object o) { @@ -334,7 +380,10 @@ public class Collections } /** - * Always succeeds with false result. + * 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,7 +391,10 @@ public class Collections } /** - * Always succeeds with false result. + * 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) { @@ -351,6 +403,7 @@ public class Collections /** * The array is always empty. + * @return A new array with a size of 0. */ public Object[] toArray() { @@ -359,6 +412,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) { @@ -369,6 +425,8 @@ public class Collections /** * The string never changes. + * + * @return the string "[]". */ public String toString() { @@ -405,6 +463,7 @@ public class Collections /** * There are no entries. + * @return The empty set. */ public Set entrySet() { @@ -415,6 +474,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) { @@ -423,6 +484,8 @@ public class Collections /** * No entries! + * @param value The value to search for. + * @return false. */ public boolean containsValue(Object value) { @@ -431,6 +494,9 @@ 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) { @@ -439,6 +505,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) { @@ -447,6 +515,7 @@ public class Collections /** * The hashcode is always 0. + * @return 0. */ public int hashCode() { @@ -455,6 +524,7 @@ public class Collections /** * No entries. + * @return The empty set. */ public Set keySet() { @@ -463,6 +533,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) { @@ -471,6 +543,7 @@ public class Collections /** * Size is always 0. + * @return 0. */ public int size() { @@ -480,6 +553,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() { @@ -488,6 +562,8 @@ public class Collections /** * The string never changes. + * + * @return the string "[]". */ public String toString() { @@ -664,10 +740,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(); @@ -907,6 +997,7 @@ public class Collections /** * The size is fixed. + * @return The size of the list. */ public int size() { @@ -915,6 +1006,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) { @@ -927,6 +1021,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) { @@ -935,6 +1031,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) { @@ -943,6 +1041,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) { @@ -951,6 +1052,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) { @@ -961,6 +1067,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() { @@ -971,6 +1079,7 @@ public class Collections /** * The string is easy to generate. + * @return A string representation of the list. */ public String toString() { @@ -990,12 +1099,12 @@ public class Collections * @param list the list to iterate over * @param oldval the element to replace * @param newval the new value for the element - * @return true if a replacement occurred + * @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 */ @@ -1303,6 +1412,7 @@ public class Collections /** * The size: always 1! + * @return 1. */ public int size() { @@ -1316,13 +1426,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) @@ -1334,6 +1461,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(); @@ -1345,6 +1481,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) { @@ -1353,6 +1492,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) { @@ -1366,6 +1509,8 @@ public class Collections /** * The hash is just that of the element. + * + * @return The hashcode of the element. */ public int hashCode() { @@ -1374,6 +1519,8 @@ public class Collections /** * Returning an array is simple. + * + * @return An array containing the element. */ public Object[] toArray() { @@ -1382,6 +1529,9 @@ public class Collections /** * Obvious string. + * + * @return The string surrounded by enclosing + * square brackets. */ public String toString() { @@ -1435,6 +1585,7 @@ public class Collections /** * The size: always 1! + * @return 1. */ public int size() { @@ -1443,6 +1594,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) { @@ -1455,6 +1612,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) { @@ -1463,6 +1623,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) { @@ -1476,6 +1640,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() { @@ -1484,6 +1651,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) { @@ -1492,6 +1662,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) { @@ -1500,6 +1673,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) { @@ -1514,6 +1695,8 @@ public class Collections /** * Returning an array is simple. + * + * @return An array containing the element. */ public Object[] toArray() { @@ -1522,6 +1705,9 @@ public class Collections /** * Obvious string. + * + * @return The string surrounded by enclosing + * square brackets. */ public String toString() { @@ -1588,12 +1774,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(); @@ -1606,6 +1803,10 @@ 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) { @@ -1614,6 +1815,10 @@ 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) { @@ -1622,6 +1827,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) { @@ -1630,6 +1839,9 @@ public class Collections /** * Calculate the hashcode directly. + * + * @return The hashcode computed from the singleton key + * and the singleton value. */ public int hashCode() { @@ -1638,6 +1850,8 @@ public class Collections /** * Return the keyset. + * + * @return A singleton containing the key. */ public Set keySet() { @@ -1648,6 +1862,8 @@ public class Collections /** * The size: always 1! + * + * @return 1. */ public int size() { @@ -1657,6 +1873,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() { @@ -1667,6 +1885,9 @@ public class Collections /** * Obvious string. + * + * @return A string containing the string representations of the key + * and its associated value. */ public String toString() { @@ -1827,6 +2048,22 @@ 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) @@ -1835,6 +2072,23 @@ 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) @@ -1843,6 +2097,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) @@ -1851,6 +2112,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) @@ -1859,6 +2132,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) @@ -1867,6 +2154,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) @@ -1875,6 +2169,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) @@ -1883,6 +2185,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) @@ -1891,6 +2207,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) @@ -1899,6 +2231,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) @@ -1907,6 +2256,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) @@ -1915,6 +2271,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) @@ -1923,6 +2287,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) @@ -1931,6 +2312,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) @@ -1970,6 +2357,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) @@ -1978,6 +2372,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) @@ -1986,6 +2388,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) @@ -2073,6 +2490,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) @@ -2081,6 +2517,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) @@ -2089,6 +2542,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) @@ -2097,6 +2562,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) @@ -2105,6 +2578,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) @@ -2113,6 +2595,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) @@ -2121,6 +2617,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) @@ -2129,6 +2637,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) @@ -2137,6 +2655,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) @@ -2145,6 +2680,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) @@ -2153,6 +2699,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) @@ -2161,6 +2725,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) @@ -2206,6 +2788,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) @@ -2243,6 +2844,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) @@ -2250,6 +2869,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) @@ -2258,6 +2886,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) @@ -2266,6 +2902,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) @@ -2274,6 +2920,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) @@ -2282,6 +2935,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) @@ -2388,6 +3060,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) @@ -2396,6 +3074,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) @@ -2404,6 +3092,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) @@ -2426,6 +3128,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) @@ -2433,6 +3144,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) @@ -2440,6 +3158,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) @@ -2447,6 +3172,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) @@ -2454,6 +3189,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) @@ -2461,6 +3213,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) @@ -2476,12 +3235,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) @@ -2497,6 +3272,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) @@ -2505,6 +3290,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) @@ -2513,6 +3313,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) @@ -2521,6 +3328,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) @@ -2529,6 +3342,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) @@ -2539,6 +3365,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) @@ -2547,6 +3391,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) @@ -2555,6 +3413,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) @@ -2563,6 +3436,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) @@ -2571,6 +3452,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) @@ -2579,6 +3467,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) @@ -2655,6 +3557,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) @@ -2663,6 +3575,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) @@ -2750,6 +3670,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) @@ -2758,6 +3685,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) @@ -2766,6 +3700,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) @@ -2774,6 +3727,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) @@ -2782,6 +3742,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) @@ -2790,6 +3768,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) @@ -2872,6 +3866,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) @@ -2880,6 +3881,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) @@ -2888,6 +3896,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) @@ -2896,6 +3923,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) @@ -2904,6 +3938,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) @@ -2913,6 +3965,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) @@ -2927,7 +3995,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 {@link UnsupportedOperationException}. + * will fail with {@link 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 @@ -2977,71 +4047,199 @@ 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(); @@ -3070,16 +4268,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(); @@ -3091,6 +4310,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 {@link 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 @@ -3143,61 +4365,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)); @@ -3254,31 +4599,77 @@ 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(); @@ -3290,6 +4681,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 {@link 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 @@ -3350,21 +4744,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) @@ -3400,31 +4835,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(); @@ -3435,31 +4921,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) @@ -3467,26 +5004,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) @@ -3500,6 +5079,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 {@link 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 @@ -3538,11 +5120,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(); @@ -3554,6 +5148,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 {@link 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 @@ -3600,31 +5197,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)); @@ -3636,6 +5321,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 {@link 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 @@ -3682,31 +5370,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)); diff --git a/libjava/java/util/SortedMap.java b/libjava/java/util/SortedMap.java index 742524e7a68..1d2d5a3cc46 100644 --- a/libjava/java/util/SortedMap.java +++ b/libjava/java/util/SortedMap.java @@ -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 diff --git a/libjava/java/util/SortedSet.java b/libjava/java/util/SortedSet.java index 415e95f8f18..8cdbe878f63 100644 --- a/libjava/java/util/SortedSet.java +++ b/libjava/java/util/SortedSet.java @@ -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 -- 2.11.4.GIT