This is the mail archive of the java-patches@gcc.gnu.org mailing list for the Java project.
| Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
|---|---|---|
| Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
| Other format: | [Raw text] | |
Hi,
Here is a large documentation patch that Andrew wrote for the GNU
Classpath collection classes.
2004-11-07 Andrew John Hughes <gnu_andrew@member.fsf.org>
* java/util/Collections.java
Added documentation.
* java/util/SortedMap.java
Clarified some method examples.
* java/util/SortedSet.java
Clarified some method examples.
No code was changed.
Committed,
Mark
Index: java/util/Collections.java
===================================================================
RCS file: /cvs/gcc/gcc/libjava/java/util/Collections.java,v
retrieving revision 1.13
diff -u -r1.13 Collections.java
--- java/util/Collections.java 22 Oct 2004 17:14:26 -0000 1.13
+++ java/util/Collections.java 7 Nov 2004 11:41:06 -0000
@@ -75,7 +75,7 @@
/**
* 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 @@
* 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 <code>true</code> if it should be treated as sequential-access
*/
private static boolean isSequential(List l)
{
@@ -131,6 +131,7 @@
/**
* The size: always 0!
+ * @return 0.
*/
public int size()
{
@@ -139,6 +140,7 @@
/**
* 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 @@
// advantage by not allocating unnecessary iterators in AbstractSet.
/**
* The empty set never contains anything.
+ * @param o The object to search for.
+ * @return <code>false</code>.
*/
public boolean contains(Object o)
{
@@ -158,6 +162,9 @@
/**
* 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 <code>true</code> if c is empty.
*/
public boolean containsAll(Collection c)
{
@@ -166,6 +173,8 @@
/**
* Equal only if the other set is empty.
+ * @param o The object to compare with this set.
+ * @return <code>true</code> if o is an empty instance of <code>Set</code>.
*/
public boolean equals(Object o)
{
@@ -174,6 +183,7 @@
/**
* The hashcode is always 0.
+ * @return 0.
*/
public int hashCode()
{
@@ -181,7 +191,9 @@
}
/**
- * Always succeeds with false result.
+ * Always succeeds with a <code>false</code> result.
+ * @param o The object to remove.
+ * @return <code>false</code>.
*/
public boolean remove(Object o)
{
@@ -189,7 +201,10 @@
}
/**
- * Always succeeds with false result.
+ * Always succeeds with a <code>false</code> result.
+ * @param c The collection of objects which should
+ * all be removed from this set.
+ * @return <code>false</code>.
*/
public boolean removeAll(Collection c)
{
@@ -197,7 +212,10 @@
}
/**
- * Always succeeds with false result.
+ * Always succeeds with a <code>false</code> result.
+ * @param c The collection of objects which should
+ * all be retained within this set.
+ * @return <code>false</code>.
*/
public boolean retainAll(Collection c)
{
@@ -206,6 +224,7 @@
/**
* The array is always empty.
+ * @return A new array with a size of 0.
*/
public Object[] toArray()
{
@@ -214,6 +233,9 @@
/**
* 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 @@
/**
* The string never changes.
+ *
+ * @return the string "[]".
*/
public String toString()
{
@@ -261,6 +285,7 @@
/**
* The size is always 0.
+ * @return 0.
*/
public int size()
{
@@ -268,7 +293,13 @@
}
/**
- * 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 @@
// advantage by not allocating unnecessary iterators in AbstractList.
/**
* Never contains anything.
+ * @param o The object to search for.
+ * @return <code>false</code>.
*/
public boolean contains(Object o)
{
@@ -287,6 +320,9 @@
/**
* 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 <code>true</code> if c is also empty.
*/
public boolean containsAll(Collection c)
{
@@ -294,7 +330,10 @@
}
/**
- * 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 <code>true</code> if o is also an empty instance of
+ * <code>List</code>.
*/
public boolean equals(Object o)
{
@@ -303,6 +342,7 @@
/**
* The hashcode is always 1.
+ * @return 1.
*/
public int hashCode()
{
@@ -311,6 +351,8 @@
/**
* Returns -1.
+ * @param o The object to search for.
+ * @return -1.
*/
public int indexOf(Object o)
{
@@ -319,6 +361,8 @@
/**
* Returns -1.
+ * @param o The object to search for.
+ * @return -1.
*/
public int lastIndexOf(Object o)
{
@@ -326,7 +370,9 @@
}
/**
- * Always succeeds with false result.
+ * Always succeeds with <code>false</code> result.
+ * @param o The object to remove.
+ * @return -1.
*/
public boolean remove(Object o)
{
@@ -334,7 +380,10 @@
}
/**
- * Always succeeds with false result.
+ * Always succeeds with <code>false</code> result.
+ * @param c The collection of objects which should
+ * all be removed from this list.
+ * @return <code>false</code>.
*/
public boolean removeAll(Collection c)
{
@@ -342,7 +391,10 @@
}
/**
- * Always succeeds with false result.
+ * Always succeeds with <code>false</code> result.
+ * @param c The collection of objects which should
+ * all be retained within this list.
+ * @return <code>false</code>.
*/
public boolean retainAll(Collection c)
{
@@ -351,6 +403,7 @@
/**
* The array is always empty.
+ * @return A new array with a size of 0.
*/
public Object[] toArray()
{
@@ -359,6 +412,9 @@
/**
* 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 @@
/**
* The string never changes.
+ *
+ * @return the string "[]".
*/
public String toString()
{
@@ -405,6 +463,7 @@
/**
* There are no entries.
+ * @return The empty set.
*/
public Set entrySet()
{
@@ -415,6 +474,8 @@
// advantage by not allocating unnecessary iterators in AbstractMap.
/**
* No entries!
+ * @param key The key to search for.
+ * @return <code>false</code>.
*/
public boolean containsKey(Object key)
{
@@ -423,6 +484,8 @@
/**
* No entries!
+ * @param value The value to search for.
+ * @return <code>false</code>.
*/
public boolean containsValue(Object value)
{
@@ -431,6 +494,9 @@
/**
* Equal to all empty maps.
+ * @param o The object o to compare against this map.
+ * @return <code>true</code> if o is also an empty instance of
+ * <code>Map</code>.
*/
public boolean equals(Object o)
{
@@ -439,6 +505,8 @@
/**
* 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 @@
/**
* The hashcode is always 0.
+ * @return 0.
*/
public int hashCode()
{
@@ -455,6 +524,7 @@
/**
* No entries.
+ * @return The empty set.
*/
public Set keySet()
{
@@ -463,6 +533,8 @@
/**
* 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 @@
/**
* Size is always 0.
+ * @return 0.
*/
public int size()
{
@@ -480,6 +553,7 @@
/**
* 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 @@
/**
* The string never changes.
+ *
+ * @return the string "[]".
*/
public String toString()
{
@@ -664,10 +740,24 @@
final Iterator i = c.iterator();
return new Enumeration()
{
+ /**
+ * Returns <code>true</code> if there are more elements to
+ * be enumerated.
+ *
+ * @return The result of <code>hasNext()</code>
+ * called on the underlying iterator.
+ */
public final boolean hasMoreElements()
{
return i.hasNext();
}
+
+ /**
+ * Returns the next element to be enumerated.
+ *
+ * @return The result of <code>next()</code>
+ * called on the underlying iterator.
+ */
public final Object nextElement()
{
return i.next();
@@ -907,6 +997,7 @@
/**
* The size is fixed.
+ * @return The size of the list.
*/
public int size()
{
@@ -915,6 +1006,9 @@
/**
* The same element is returned.
+ * @param index The index of the element to be returned (irrelevant
+ * as the list contains only copies of <code>element</code>).
+ * @return The element used by this list.
*/
public Object get(int index)
{
@@ -927,6 +1021,8 @@
// advantage by not allocating unnecessary iterators in AbstractList.
/**
* This list only contains one element.
+ * @param o The object to search for.
+ * @return <code>true</code> if o is the element used by this list.
*/
public boolean contains(Object o)
{
@@ -935,6 +1031,8 @@
/**
* The index is either 0 or -1.
+ * @param o The object to find the index of.
+ * @return 0 if <code>o == element</code>, -1 if not.
*/
public int indexOf(Object o)
{
@@ -943,6 +1041,9 @@
/**
* 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 <code>o == element</code>,
+ * -1 if not.
*/
public int lastIndexOf(Object o)
{
@@ -951,6 +1052,11 @@
/**
* 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 <code>from - to</code>
+ * elements, all of which are equal to the element
+ * used by this list.
*/
public List subList(int from, int to)
{
@@ -961,6 +1067,8 @@
/**
* 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 @@
/**
* The string is easy to generate.
+ * @return A string representation of the list.
*/
public String toString()
{
@@ -990,12 +1099,12 @@
* @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 <code>true</code> 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 @@
/**
* The size: always 1!
+ * @return 1.
*/
public int size()
{
@@ -1316,13 +1426,30 @@
{
return new Iterator()
{
+ /**
+ * Flag to indicate whether or not the element has
+ * been retrieved.
+ */
private boolean hasNext = true;
+ /**
+ * Returns <code>true</code> if elements still remain to be
+ * iterated through.
+ *
+ * @return <code>true</code> 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 @@
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
+ * <code>remove()</code>.
+ */
public void remove()
{
throw new UnsupportedOperationException();
@@ -1345,6 +1481,9 @@
// advantage by not allocating unnecessary iterators in AbstractSet.
/**
* The set only contains one element.
+ *
+ * @param o The object to search for.
+ * @return <code>true</code> if o == the element of the singleton.
*/
public boolean contains(Object o)
{
@@ -1353,6 +1492,10 @@
/**
* This is true if the other collection only contains the element.
+ *
+ * @param c A collection to compare against this singleton.
+ * @return <code>true</code> 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 @@
/**
* The hash is just that of the element.
+ *
+ * @return The hashcode of the element.
*/
public int hashCode()
{
@@ -1374,6 +1519,8 @@
/**
* Returning an array is simple.
+ *
+ * @return An array containing the element.
*/
public Object[] toArray()
{
@@ -1382,6 +1529,9 @@
/**
* Obvious string.
+ *
+ * @return The string surrounded by enclosing
+ * square brackets.
*/
public String toString()
{
@@ -1435,6 +1585,7 @@
/**
* The size: always 1!
+ * @return 1.
*/
public int size()
{
@@ -1443,6 +1594,12 @@
/**
* 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 @@
// advantage by not allocating unnecessary iterators in AbstractList.
/**
* The set only contains one element.
+ *
+ * @param o The object to search for.
+ * @return <code>true</code> if o == the singleton element.
*/
public boolean contains(Object o)
{
@@ -1463,6 +1623,10 @@
/**
* This is true if the other collection only contains the element.
+ *
+ * @param c A collection to compare against this singleton.
+ * @return <code>true</code> 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 <code>from > to</code>
+ * @throws IndexOutOfBoundsException if either bound is greater
+ * than 1.
*/
public List subList(int from, int to)
{
@@ -1514,6 +1695,8 @@
/**
* Returning an array is simple.
+ *
+ * @return An array containing the element.
*/
public Object[] toArray()
{
@@ -1522,6 +1705,9 @@
/**
* Obvious string.
+ *
+ * @return The string surrounded by enclosing
+ * square brackets.
*/
public String toString()
{
@@ -1588,12 +1774,23 @@
/**
* 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 @@
// advantage by not allocating unnecessary iterators in AbstractMap.
/**
* Single entry.
+ *
+ * @param key The key to look for.
+ * @return <code>true</code> if the key is the same as the one used by
+ * this map.
*/
public boolean containsKey(Object key)
{
@@ -1614,6 +1815,10 @@
/**
* Single entry.
+ *
+ * @param value The value to look for.
+ * @return <code>true</code> if the value is the same as the one used by
+ * this map.
*/
public boolean containsValue(Object value)
{
@@ -1622,6 +1827,10 @@
/**
* 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 @@
/**
* Calculate the hashcode directly.
+ *
+ * @return The hashcode computed from the singleton key
+ * and the singleton value.
*/
public int hashCode()
{
@@ -1638,6 +1850,8 @@
/**
* Return the keyset.
+ *
+ * @return A singleton containing the key.
*/
public Set keySet()
{
@@ -1648,6 +1862,8 @@
/**
* The size: always 1!
+ *
+ * @return 1.
*/
public int size()
{
@@ -1657,6 +1873,8 @@
/**
* 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 @@
/**
* Obvious string.
+ *
+ * @return A string containing the string representations of the key
+ * and its associated value.
*/
public String toString()
{
@@ -1827,6 +2048,22 @@
mutex = sync;
}
+ /**
+ * Adds the object to the underlying collection, first
+ * obtaining a lock on the mutex.
+ *
+ * @param o The object to add.
+ * @return <code>true</code> 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 @@
}
}
+ /**
+ * 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 <code>true</code> 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 <code>true</code> if this collection contains at least one
+ * element e such that <code>o == null ? e == null : o.equals(e)</code>.
+ * @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 @@
}
}
+ /**
+ * 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 <code>true</code> if for every element o in c, contains(o)
+ * would return <code>true</code>.
+ * @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 @@
}
}
+ /**
+ * Returns <code>true</code> if there are no objects in the underlying
+ * collection. A lock on the mutex is obtained before the
+ * check is performed.
+ *
+ * @return <code>true</code> if this collection contains no elements.
+ */
public boolean isEmpty()
{
synchronized (mutex)
@@ -1875,6 +2169,14 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * Removes the specified object from the underlying collection,
+ * first obtaining a lock on the mutex.
+ *
+ * @param o The object to remove.
+ * @return <code>true</code> 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 @@
}
}
+ /**
+ * Removes all elements, e, of the underlying
+ * collection for which <code>col.contains(e)</code>
+ * returns <code>true</code>. A lock on the mutex is obtained
+ * before the operation proceeds.
+ *
+ * @param col The collection of objects to be removed.
+ * @return <code>true</code> 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 @@
}
}
+ /**
+ * Retains all elements, e, of the underlying
+ * collection for which <code>col.contains(e)</code>
+ * returns <code>true</code>. 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 <code>true</code> 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * Copies the elements in the underlying collection to the supplied
+ * array. If <code>a.length < size()</code>, a new array of the
+ * same run-time type is created, with a size equal to that of
+ * the collection. If <code>a.length > size()</code>, then the
+ * elements from 0 to <code>size() - 1</code> 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 @@
}
}
+ /**
+ * 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 @@
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 @@
}
}
+ /**
+ * Returns <code>true</code> if objects can still be retrieved from the iterator
+ * using <code>next()</code>. A lock is obtained on the mutex before
+ * the collection is accessed.
+ *
+ * @return <code>true</code> if at least one element is still to be returned by
+ * <code>next()</code>.
+ */
public boolean hasNext()
{
synchronized (mutex)
@@ -1986,6 +2388,21 @@
}
}
+ /**
+ * Removes the object that was last returned by <code>next()</code>
+ * from the underlying collection. Only one call to this method is
+ * allowed per call to the <code>next()</code> method, and it does
+ * not affect the value that will be returned by <code>next()</code>.
+ * Thus, if element n was retrieved from the collection by
+ * <code>next()</code>, it is this element that gets removed.
+ * Regardless of whether this takes place or not, element n+1 is
+ * still returned on the subsequent <code>next()</code> 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 @@
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 @@
}
}
+ /**
+ * 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 <code>true</code>, 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 @@
}
}
+ /**
+ * Tests whether the underlying list is equal to the supplied object.
+ * The object is deemed to be equal if it is also a <code>List</code>
+ * of equal size and with the same elements (i.e. each element, e1,
+ * in list, l1, and each element, e2, in l2, must return <code>true</code> for
+ * <code>e1 == null ? e2 == null : e1.equals(e2)</code>. 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 <code>true</code> if o is equal to the underlying list under the above
+ * definition.
+ */
public boolean equals(Object o)
{
synchronized (mutex)
@@ -2097,6 +2562,14 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 <code>List</code>
+ * interface.
+ *
+ * @return The hashcode of the underlying list.
+ * @see List#hashCode()
+ */
public int hashCode()
{
synchronized (mutex)
@@ -2113,6 +2595,20 @@
}
}
+ /**
+ * 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 <code>o == null ? get(n) == null :
+ * o.equals(get(n))</code>, 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 @@
}
}
+ /**
+ * 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 <code>o == null ? get(n) == null
+ * : o.equals(get(n))</code>, 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 <code>next()</code>. Calling
+ * <code>previous()</code> 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 @@
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 @@
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 <code>previous()</code> and the
+ * element that would be returned by <code>next()</code>. 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 @@
li.add(o);
}
}
+
+ /**
+ * Tests whether there are elements remaining in the underlying list
+ * in the reverse direction. In other words, <code>previous()</code>
+ * will not fail with a NoSuchElementException. A lock is obtained
+ * on the mutex before the check takes place.
+ *
+ * @return <code>true</code> if the list continues in the reverse direction
+ */
public boolean hasPrevious()
{
synchronized (mutex)
@@ -2258,6 +2886,14 @@
}
}
+ /**
+ * Find the index of the element that would be returned by a call to
+ * <code>next()</code>. If hasNext() returns <code>false</code>, 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * Find the index of the element that would be returned by a call to
+ * previous. If hasPrevious() returns <code>false</code>, 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 @@
}
}
+ /**
+ * Replace the element last returned by a call to <code>next()</code> or
+ * <code>previous()</code> with a given object (optional operation). This
+ * method may only be called if neither <code>add()</code> nor
+ * <code>remove()</code> have been called since the last call to
+ * <code>next()</code> or <code>previous</code>. 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 @@
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 @@
}
}
+ /**
+ * Returns <code>true</code> 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 <code>true</code> if the underlying map contains the key.
+ * @throws ClassCastException if the key is of an inappropriate type.
+ * @throws NullPointerException if key is <code>null</code> but the map
+ * does not permit null keys.
+ */
public boolean containsKey(Object key)
{
synchronized (mutex)
@@ -2404,6 +3092,20 @@
}
}
+ /**
+ * Returns <code>true</code> if the underlying map contains at least one entry with the
+ * given value. In other words, returns <code>true</code> if a value v exists where
+ * <code>(value == null ? v == null : value.equals(v))</code>. 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 <code>true</code> 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 @@
{
e = (Map.Entry) o;
}
+
+ /**
+ * Returns <code>true</code> if the object, o, implements <code>Map.Entry</code>
+ * 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 <code>true</code> if o is equivalent to the underlying map entry.
+ */
public boolean equals(Object o)
{
synchronized (mutex)
@@ -2433,6 +3144,13 @@
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 @@
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 @@
return e.getValue();
}
}
+
+ /**
+ * Computes the hash code for the underlying map entry.
+ * This computation is described in the documentation for the
+ * <code>Map</code> 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 @@
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
+ * <code>remove()</code> 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 @@
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 <code>String</code> form.
+ */
public String toString()
{
synchronized (mutex)
@@ -2476,12 +3235,28 @@
{
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 @@
return entries;
}
+ /**
+ * Returns <code>true</code> if the object, o, is also an instance
+ * of <code>Map</code> 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 <code>true</code> if o and the underlying map are equivalent.
+ */
public boolean equals(Object o)
{
synchronized (mutex)
@@ -2505,6 +3290,21 @@
}
}
+ /**
+ * 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, <code>containsKey</code>
+ * 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * Returns <code>true</code> if the underlying map contains no entries.
+ * A lock is obtained on the mutex before the map is examined.
+ *
+ * @return <code>true</code> if the map is empty.
+ */
public boolean isEmpty()
{
synchronized (mutex)
@@ -2529,6 +3342,19 @@
}
}
+ /**
+ * 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: <code>Iterator.remove</code>,
+ * <code>Set.remove</code>, <code>removeAll</code>, <code>retainAll</code>,
+ * and <code>clear</code>. Element addition, via <code>add</code> or
+ * <code>addAll</code>, 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 @@
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 <code>null</code> 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 @@
}
}
+ /**
+ * 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 <code>m</code> is null.
+ * @see #put(Object, Object)
+ */
public void putAll(Map map)
{
synchronized (mutex)
@@ -2555,6 +3413,21 @@
}
}
+ /**
+ * 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
+ * <code>containsKey()</code> 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 @@
}
}
+ /**
+ * Retrieves the size of the underlying map. A lock
+ * is obtained on the mutex before access takes place.
+ * Maps with a size greater than <code>Integer.MAX_VALUE</code>
+ * return <code>Integer.MAX_VALUE</code> instead.
+ *
+ * @return The size of the underlying map.
+ */
public int size()
{
synchronized (mutex)
@@ -2571,6 +3452,13 @@
}
}
+ /**
+ * Returns a textual representation of the underlying
+ * map. A lock is obtained on the mutex before the map
+ * is accessed.
+ *
+ * @return The map in <code>String</code> form.
+ */
public String toString()
{
synchronized (mutex)
@@ -2579,6 +3467,20 @@
}
}
+ /**
+ * 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: <code>Iterator.remove</code>,
+ * <code>Collection.remove</code>, <code>removeAll</code>,
+ * <code>retainAll</code>, and <code>clear</code>. Element addition, via
+ * <code>add</code> or <code>addAll</code>, 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 @@
super(sync, s);
}
+ /**
+ * Returns <code>true</code> if the object, o, is a <code>Set</code>
+ * 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 <code>true</code> if o is an equivalent set.
+ */
public boolean equals(Object o)
{
synchronized (mutex)
@@ -2663,6 +3575,14 @@
}
}
+ /**
+ * 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 @@
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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * Returns a submap containing the keys from the first
+ * key (as returned by <code>firstKey()</code>) 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 <code>subMap(firstKey(), toKey)</code>.
+ * The submap retains the thread-safe status of this map.
+ *
+ * @param toKey the exclusive upper range of the submap.
+ * @return a submap from <code>firstKey()</code> 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 <code>lastKey()</code>.
+ * @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 @@
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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * Returns a subset containing the element from the first
+ * element (as returned by <code>first()</code>) 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 <code>subSet(first(), toElement)</code>.
+ * The subset retains the thread-safe status of this set.
+ *
+ * @param toElement the exclusive upper range of the subset.
+ * @return a subset from <code>first()</code> 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 @@
}
}
+ /**
+ * 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 <code>last()</code>.
+ * @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 @@
* 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.
* <p>
*
* Since the collection might be a List or a Set, and those have incompatible
@@ -2977,71 +4047,199 @@
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 <code>true</code> 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 <code>true</code> if the collection was modified as a result of this action.
+ * @throws UnsupportedOperationException as an unmodifiable collection does not
+ * support the <code>addAll</code> 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 <code>clear()</code> 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 <code>true</code> if the underlying collection contains at least
+ * one element e such that
+ * <code>o == null ? e == null : o.equals(e)</code>.
+ * @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 <code>true</code> if for every element o in c, contains(o) would
+ * return <code>true</code>.
+ * @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 <code>true</code> 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 <code>true</code> 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 <code>remove()</code> 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 <code>true</code> if the collection was modified.
+ * @throws UnsupportedOperationException as an unmodifiable collection
+ * does not support the <code>removeAll()</code> 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 <code>true</code> if the collection was modified.
+ * @throws UnsupportedOperationException as an unmodifiable collection
+ * does not support the <code>retainAll()</code> 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 <code>String</code>.
+ */
public String toString()
{
return c.toString();
@@ -3070,16 +4268,37 @@
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 <code>next()</code>. When this method
+ * returns <code>true</code>, an exception will not be thrown on calling
+ * <code>next()</code>.
+ *
+ * @return <code>true</code> 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 @@
* "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.
* <p>
*
* The returned List implements Serializable, but can only be serialized if
@@ -3143,61 +4365,184 @@
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 <code>add()</code> 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 <code>addAll()</code> operation.
+ */
public boolean addAll(int index, Collection c)
{
throw new UnsupportedOperationException();
}
+ /**
+ * Returns <code>true</code> if the object, o, is an instance of
+ * <code>List</code> with the same size and elements
+ * as the underlying list.
+ *
+ * @param o The object to compare.
+ * @return <code>true</code> 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 <code>List</code> 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 <code>o == null ? get(n) == null :
+ * o.equals(get(n))</code>, 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 <code>o == null ? get(n) == null
+ * : o.equals(get(n))</code>, 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 <code>UnmodifiableListIterator</code> 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 <code>next()</code> will retrieve the element at the specified index,
+ * and an initial call to <code>previous()</code> will retrieve the element
+ * at index - 1.
+ *
+ *
+ * @param index the position, between 0 and size() inclusive, to begin the
+ * iteration from.
+ * @return a <code>UnmodifiableListIterator</code> 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 <code>remove()</code>
+ * 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 <code>set()</code>
+ * 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 @@
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 <code>add()</code> operation.
+ */
public void add(Object o)
{
throw new UnsupportedOperationException();
}
+ /**
+ * Tests whether there are still elements to be retrieved from the
+ * underlying collection by <code>previous()</code>. When this method
+ * returns <code>true</code>, an exception will not be thrown on calling
+ * <code>previous()</code>.
+ *
+ * @return <code>true</code> 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 <code>hasNext()</code> returns <code>false</code>, this returns the list size.
+ *
+ * @return the index of the element that would be returned by
+ * <code>next()</code>.
+ */
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 <code>hasPrevious()</code> returns <code>false</code>,
+ * this returns -1.
+ *
+ * @return the index of the element that would be returned by
+ * <code>previous()</code>.
+ */
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 <code>set()</code> operation.
+ */
public void set(Object o)
{
throw new UnsupportedOperationException();
@@ -3290,6 +4681,9 @@
* 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.
* <p>
*
* The returned Map implements Serializable, but can only be serialized if
@@ -3350,21 +4744,62 @@
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 <code>clear()</code> operation.
+ */
public void clear()
{
throw new UnsupportedOperationException();
}
+ /**
+ * Returns <code>true</code> if the underlying map contains a mapping for
+ * the given key.
+ *
+ * @param key the key to search for
+ * @return <code>true</code> if the map contains the key
+ * @throws ClassCastException if the key is of an inappropriate type
+ * @throws NullPointerException if key is <code>null</code> but the map
+ * does not permit null keys
+ */
public boolean containsKey(Object key)
{
return m.containsKey(key);
}
+ /**
+ * Returns <code>true</code> if the underlying map contains at least one mapping with
+ * the given value. In other words, it returns <code>true</code> if a value v exists where
+ * <code>(value == null ? v == null : value.equals(v))</code>. This usually
+ * requires linear time.
+ *
+ * @param value the value to search for
+ * @return <code>true</code> 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 <code>Map.Entry</code>.
+ * 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 @@
{
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 <code>true</code> if the object, o, is also a map entry with an
+ * identical key and value.
+ *
+ * @param o the object to compare.
+ * @return <code>true</code> 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 <code>Map</code>
+ * 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 <code>setValue()</code>
+ * operation.
+ */
public Object setValue(Object value)
{
throw new UnsupportedOperationException();
}
+
+ /**
+ * Returns a textual representation of the map entry.
+ *
+ * @return The map entry as a <code>String</code>.
+ */
public String toString()
{
return e.toString();
@@ -3435,31 +4921,82 @@
}
} // class UnmodifiableEntrySet
+ /**
+ * Returns <code>true</code> if the object, o, is also an instance
+ * of <code>Map</code> with an equal set of map entries.
+ *
+ * @param o The object to compare.
+ * @return <code>true</code> 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, <code>containsKey()</code> 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 <code>put()</code> 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 <code>true</code> if the underlying map contains no entries.
+ *
+ * @return <code>true</code> 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 @@
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 <code>putAll</code> 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 <code>remove</code> 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 <code>String</code>.
+ */
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 @@
* "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.
* <p>
*
* The returned Set implements Serializable, but can only be serialized if
@@ -3538,11 +5120,23 @@
super(s);
}
+ /**
+ * Returns <code>true</code> if the object, o, is also an instance of
+ * <code>Set</code> of the same size and with the same entries.
+ *
+ * @return <code>true</code> 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 @@
* "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.
* <p>
*
* The returned SortedMap implements Serializable, but can only be
@@ -3600,31 +5197,119 @@
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
+ * <code>subMap(firstKey(), toKey)</code>.
+ * <p>
+ *
+ * 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
+ * <code>headMap(new Integer(limit.intValue() + 1))</code>.
+ *
+ * @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.
+ * <p>
+ *
+ * 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
+ * <code>subMap(new Integer(lowlimit.intValue() + 1),
+ * new Integer(highlimit.intValue() + 1))</code> 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.
+ * <p>
+ *
+ * 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
+ * <code>tailMap(new Integer(limit.intValue() + 1))</code>.
+ *
+ * @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 @@
* "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.
* <p>
*
* The returns SortedSet implements Serializable, but can only be
@@ -3682,31 +5370,121 @@
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 <code>subSet(first(), toElement)</code>.
+ * <p>
+ *
+ * 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
+ * <code>headSet(new Integer(limit.intValue() + 1))</code>.
+ *
+ * @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.
+ * <p>
+ *
+ * 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
+ * <code>subSet(new Integer(lowlimit.intValue() + 1),
+ * new Integer(highlimit.intValue() + 1))</code> 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.
+ * <p>
+ *
+ * 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
+ * <code>tailSet(new Integer(limit.intValue() + 1))</code>.
+ *
+ * @param fromElement the inclusive lower range of the subset
+ * @return the subset.
+ * @throws ClassCastException if fromElement is not comparable to the set
+ * contents.
+ * @throws IllegalArgumentException if this is a subSet, and fromElement is
+ * out of range.
+ * @throws NullPointerException if fromElement is null but the set does not
+ * allow null elements.
+ */
public SortedSet tailSet(Object fromElement)
{
return new UnmodifiableSortedSet(ss.tailSet(fromElement));
Index: java/util/SortedMap.java
===================================================================
RCS file: /cvs/gcc/gcc/libjava/java/util/SortedMap.java,v
retrieving revision 1.5
diff -u -r1.5 SortedMap.java
--- java/util/SortedMap.java 1 Aug 2004 11:14:42 -0000 1.5
+++ java/util/SortedMap.java 7 Nov 2004 11:41:06 -0000
@@ -97,10 +97,10 @@
* <p>
*
* 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
- * <code>headMap(limit + "\0")</code>.
+ * 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
+ * <code>headMap(new Integer(limit.intValue() + 1))</code>.
*
* @param toKey the exclusive upper range of the submap
* @return the submap
@@ -130,9 +130,10 @@
* 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
- * <code>subMap(lowlimit + "\0", highlimit + "\0")</code> to reverse
+ * change the inclusion or exclusion of an endpoint, pass its successor
+ * object in instead. For example, for Integers, you could request
+ * <code>subMap(new Integer(lowlimit.intValue() + 1),
+ * new Integer(highlimit.intValue() + 1))</code> to reverse
* the inclusiveness of both endpoints.
*
* @param fromKey the inclusive lower range of the submap
@@ -154,10 +155,10 @@
* <p>
*
* 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
- * <code>tailMap(limit + "\0")</code>.
+ * 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
+ * <code>tailMap(new Integer(limit.intValue() + 1))</code>.
*
* @param fromKey the inclusive lower range of the submap
* @return the submap
Index: java/util/SortedSet.java
===================================================================
RCS file: /cvs/gcc/gcc/libjava/java/util/SortedSet.java,v
retrieving revision 1.6
diff -u -r1.6 SortedSet.java
--- java/util/SortedSet.java 29 Aug 2004 17:28:09 -0000 1.6
+++ java/util/SortedSet.java 7 Nov 2004 11:41:06 -0000
@@ -99,10 +99,10 @@
* <p>
*
* 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
- * <code>headSet(limit + "\0")</code>.
+ * 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
+ * <code>headSet(new Integer(limit.intValue() + 1))</code>.
*
* @param toElement the exclusive upper range of the subset
* @return the subset
@@ -133,9 +133,10 @@
* 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
- * <code>subSet(lowlimit + "\0", highlimit + "\0")</code> to reverse
+ * change the inclusion or exclusion of an endpoint, pass its successor
+ * object in instead. For example, for Integers, you can request
+ * <code>subSet(new Integer(lowlimit.intValue() + 1),
+ * new Integer(highlimit.intValue() + 1))</code> to reverse
* the inclusiveness of both endpoints.
*
* @param fromElement the inclusive lower range of the subset
@@ -157,10 +158,10 @@
* <p>
*
* 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
- * <code>tailSet(limit + "\0")</code>.
+ * 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
+ * <code>tailSet(new Integer(limit.intValue() + 1))</code>.
*
* @param fromElement the inclusive lower range of the subset
* @return the subset
Attachment:
signature.asc
Description: This is a digitally signed message part
| Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
|---|---|---|
| Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |