From 477a21f7f9b31c687d45f1001dd93c90df52cf29 Mon Sep 17 00:00:00 2001 From: Andrew John Hughes Date: Sun, 29 Aug 2004 17:28:09 +0000 Subject: [PATCH] AbstractCollection.java, [...]: Added additional exceptions to documentation... 2004-08-29 Andrew John Hughes * java/util/AbstractCollection.java, java/util/AbstractList.java, java/util/AbstractMap.java, java/util/AbstractSequentialList.java, java/util/ArrayList.java, java/util/Arrays.java, java/util/BitSet.java, java/util/Calendar.java, java/util/Collection.java, java/util/ListIterator.java, java/util/Map.java, java/util/SortedSet.java: Added additional exceptions to documentation, along with some additions and corrections. From-SVN: r86730 --- libjava/ChangeLog | 11 + libjava/java/util/AbstractCollection.java | 18 +- libjava/java/util/AbstractList.java | 298 +++++++++++++++++- libjava/java/util/AbstractMap.java | 145 +++++++-- libjava/java/util/AbstractSequentialList.java | 8 +- libjava/java/util/ArrayList.java | 13 +- libjava/java/util/Arrays.java | 57 ++++ libjava/java/util/BitSet.java | 18 +- libjava/java/util/Calendar.java | 32 +- libjava/java/util/Collection.java | 2 + libjava/java/util/ListIterator.java | 10 +- libjava/java/util/Map.java | 2 +- libjava/java/util/SortedSet.java | 8 +- 13 files changed, 568 insertions(+), 54 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index fb67852b28a..0b5bef2474e 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,14 @@ +2004-08-29 Andrew John Hughes + + * java/util/AbstractCollection.java, java/util/AbstractList.java, + java/util/AbstractMap.java, java/util/AbstractSequentialList.java, + java/util/ArrayList.java, java/util/Arrays.java, + java/util/BitSet.java, java/util/Calendar.java, + java/util/Collection.java, java/util/ListIterator.java, + java/util/Map.java, java/util/SortedSet.java: + Added additional exceptions to documentation, along + with some additions and corrections. + 2004-08-27 Hans Boehm * configure.ac: Handle --enable-gc-debug. diff --git a/libjava/java/util/AbstractCollection.java b/libjava/java/util/AbstractCollection.java index fc0c23a807e..a98f41efbea 100644 --- a/libjava/java/util/AbstractCollection.java +++ b/libjava/java/util/AbstractCollection.java @@ -129,11 +129,13 @@ public abstract class AbstractCollection implements Collection * @return true if the add operation caused the Collection to change * @throws UnsupportedOperationException if the add operation is not * supported on this collection - * @throws NullPointerException if this collection does not support null, - * or if the specified collection is null - * @throws ClassCastException if an object in c is of the wrong type - * @throws IllegalArgumentException if some aspect of an object in c prevents - * it from being added + * @throws NullPointerException if the specified collection is null + * @throws ClassCastException if the type of any element in c is + * not a valid type for addition. + * @throws IllegalArgumentException if some aspect of any element + * in c prevents it being added. + * @throws NullPointerException if any element in c is null and this + * collection doesn't allow null values. * @see #add(Object) */ public boolean addAll(Collection c) @@ -268,6 +270,7 @@ public abstract class AbstractCollection implements Collection * @return true if the remove operation caused the Collection to change * @throws UnsupportedOperationException if this collection's Iterator * does not support the remove method + * @throws NullPointerException if the collection, c, is null. * @see Iterator#remove() */ public boolean removeAll(Collection c) @@ -288,8 +291,10 @@ public abstract class AbstractCollection implements Collection * @return true if the remove operation caused the Collection to change * @throws UnsupportedOperationException if this collection's Iterator * does not support the remove method + * @throws NullPointerException if the collection, c, is null. * @see Iterator#remove() */ + // Package visible for use throughout java.util. boolean removeAllInternal(Collection c) { Iterator itr = iterator(); @@ -316,6 +321,7 @@ public abstract class AbstractCollection implements Collection * @return true if the remove operation caused the Collection to change * @throws UnsupportedOperationException if this collection's Iterator * does not support the remove method + * @throws NullPointerException if the collection, c, is null. * @see Iterator#remove() */ public boolean retainAll(Collection c) @@ -337,8 +343,10 @@ public abstract class AbstractCollection implements Collection * @return true if the remove operation caused the Collection to change * @throws UnsupportedOperationException if this collection's Iterator * does not support the remove method + * @throws NullPointerException if the collection, c, is null. * @see Iterator#remove() */ + // Package visible for use throughout java.util. boolean retainAllInternal(Collection c) { Iterator itr = iterator(); diff --git a/libjava/java/util/AbstractList.java b/libjava/java/util/AbstractList.java index be0bc307a56..15cb5814ab8 100644 --- a/libjava/java/util/AbstractList.java +++ b/libjava/java/util/AbstractList.java @@ -85,7 +85,7 @@ public abstract class AbstractList extends AbstractCollection implements List * add(int, Object) and remove(int) methods. * Otherwise, this field may be ignored. */ - protected int modCount; + protected transient int modCount; /** * The main constructor, for use by subclasses. @@ -308,18 +308,43 @@ while (i.hasNext()) private int knownMod = modCount; // This will get inlined, since it is private. + /** + * Checks for modifications made to the list from + * elsewhere while iteration is in progress. + * + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ private void checkMod() { if (knownMod != modCount) throw new ConcurrentModificationException(); } + /** + * Tests to see if there are any more objects to + * return. + * + * @return True if the end of the list has not yet been + * reached. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public boolean hasNext() { checkMod(); return pos < size; } + /** + * Retrieves the next object from the list. + * + * @return The next object. + * @throws NoSuchElementException if there are + * no more objects to retrieve. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public Object next() { checkMod(); @@ -329,6 +354,18 @@ while (i.hasNext()) return get(pos++); } + /** + * Removes the last object retrieved by next() + * from the list, if the list supports object removal. + * + * @throws ConcurrentModificationException if the list + * has been modified elsewhere. + * @throws IllegalStateException if the iterator is positioned + * before the start of the list or the last object has already + * been removed. + * @throws UnsupportedOperationException if the list does + * not support removing elements. + */ public void remove() { checkMod(); @@ -405,24 +442,58 @@ while (i.hasNext()) private int size = size(); // This will get inlined, since it is private. + /** + * Checks for modifications made to the list from + * elsewhere while iteration is in progress. + * + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ private void checkMod() { if (knownMod != modCount) throw new ConcurrentModificationException(); } + /** + * Tests to see if there are any more objects to + * return. + * + * @return True if the end of the list has not yet been + * reached. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public boolean hasNext() { checkMod(); return position < size; } + /** + * Tests to see if there are objects prior to the + * current position in the list. + * + * @return True if objects exist prior to the current + * position of the iterator. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public boolean hasPrevious() { checkMod(); return position > 0; } + /** + * Retrieves the next object from the list. + * + * @return The next object. + * @throws NoSuchElementException if there are no + * more objects to retrieve. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public Object next() { checkMod(); @@ -432,6 +503,15 @@ while (i.hasNext()) return get(position++); } + /** + * Retrieves the previous object from the list. + * + * @return The next object. + * @throws NoSuchElementException if there are no + * previous objects to retrieve. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public Object previous() { checkMod(); @@ -441,18 +521,47 @@ while (i.hasNext()) return get(lastReturned); } + /** + * Returns the index of the next element in the + * list, which will be retrieved by next() + * + * @return The index of the next element. + * @throws ConcurrentModificationException if the list + * has been modified elsewhere. + */ public int nextIndex() { checkMod(); return position; } + /** + * Returns the index of the previous element in the + * list, which will be retrieved by previous() + * + * @return The index of the previous element. + * @throws ConcurrentModificationException if the list + * has been modified elsewhere. + */ public int previousIndex() { checkMod(); return position - 1; } + /** + * Removes the last object retrieved by next() + * or previous() from the list, if the list + * supports object removal. + * + * @throws IllegalStateException if the iterator is positioned + * before the start of the list or the last object has already + * been removed. + * @throws UnsupportedOperationException if the list does + * not support removing elements. + * @throws ConcurrentModificationException if the list + * has been modified elsewhere. + */ public void remove() { checkMod(); @@ -465,6 +574,24 @@ while (i.hasNext()) knownMod = modCount; } + /** + * Replaces the last object retrieved by next() + * or previous with o, if the list supports object + * replacement and an add or remove operation has not already + * been performed. + * + * @throws IllegalStateException if the iterator is positioned + * before the start of the list or the last object has already + * been removed. + * @throws UnsupportedOperationException if the list doesn't support + * the addition or removal of elements. + * @throws ClassCastException if the type of o is not a valid type + * for this list. + * @throws IllegalArgumentException if something else related to o + * prevents its addition. + * @throws ConcurrentModificationException if the list + * has been modified elsewhere. + */ public void set(Object o) { checkMod(); @@ -473,6 +600,20 @@ while (i.hasNext()) AbstractList.this.set(lastReturned, o); } + /** + * Adds the supplied object before the element that would be returned + * by a call to next(), if the list supports addition. + * + * @param o The object to add to the list. + * @throws UnsupportedOperationException if the list doesn't support + * the addition of new elements. + * @throws ClassCastException if the type of o is not a valid type + * for this list. + * @throws IllegalArgumentException if something else related to o + * prevents its addition. + * @throws ConcurrentModificationException if the list + * has been modified elsewhere. + */ public void add(Object o) { checkMod(); @@ -519,6 +660,8 @@ while (i.hasNext()) * * @param fromIndex the index, inclusive, to remove from. * @param toIndex the index, exclusive, to remove to. + * @throws UnsupportedOperationException if the list does + * not support removing elements. */ protected void removeRange(int fromIndex, int toIndex) { @@ -663,7 +806,7 @@ class SubList extends AbstractList * it is not, an exception is thrown. * * @param index the value to check - * @throws IndexOutOfBoundsException if the value is out of range + * @throws IndexOutOfBoundsException if index < 0 || index > size() */ // This will get inlined, since it is private. private void checkBoundsInclusive(int index) @@ -678,7 +821,7 @@ class SubList extends AbstractList * (exclusive). If it is not, an exception is thrown. * * @param index the value to check - * @throws IndexOutOfBoundsException if the value is out of range + * @throws IndexOutOfBoundsException if index < 0 || index >= size() */ // This will get inlined, since it is private. private void checkBoundsExclusive(int index) @@ -692,6 +835,8 @@ class SubList extends AbstractList * Specified by AbstractList.subList to return the private field size. * * @return the sublist size + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist */ public int size() { @@ -705,6 +850,15 @@ class SubList extends AbstractList * @param index the location to modify * @param o the new value * @return the old value + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist + * @throws UnsupportedOperationException if the backing list does not + * support the set operation + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + * @throws ClassCastException if o cannot be added to the backing list due + * to its type + * @throws IllegalArgumentException if o cannot be added to the backing list + * for some other reason */ public Object set(int index, Object o) { @@ -718,6 +872,9 @@ class SubList extends AbstractList * * @param index the location to get from * @return the object at that location + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist + * @throws IndexOutOfBoundsException if index < 0 || index >= size() */ public Object get(int index) { @@ -731,6 +888,15 @@ class SubList extends AbstractList * * @param index the index to insert at * @param o the object to add + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist + * @throws IndexOutOfBoundsException if index < 0 || index > size() + * @throws UnsupportedOperationException if the backing list does not + * support the add operation. + * @throws ClassCastException if o cannot be added to the backing list due + * to its type. + * @throws IllegalArgumentException if o cannot be added to the backing + * list for some other reason. */ public void add(int index, Object o) { @@ -746,6 +912,11 @@ class SubList extends AbstractList * * @param index the index to remove * @return the removed object + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist + * @throws IndexOutOfBoundsException if index < 0 || index >= size() + * @throws UnsupportedOperationException if the backing list does not + * support the remove operation */ public Object remove(int index) { @@ -764,6 +935,10 @@ class SubList extends AbstractList * * @param fromIndex the lower bound, inclusive * @param toIndex the upper bound, exclusive + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist + * @throws UnsupportedOperationException if the backing list does + * not support removing elements. */ protected void removeRange(int fromIndex, int toIndex) { @@ -780,6 +955,16 @@ class SubList extends AbstractList * @param index the location to insert at * @param c the collection to insert * @return true if this list was modified, in other words, c is non-empty + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist + * @throws IndexOutOfBoundsException if index < 0 || index > size() + * @throws UnsupportedOperationException if this list does not support the + * addAll operation + * @throws ClassCastException if some element of c cannot be added to this + * list due to its type + * @throws IllegalArgumentException if some element of c cannot be added + * to this list for some other reason + * @throws NullPointerException if the specified collection is null */ public boolean addAll(int index, Collection c) { @@ -797,6 +982,15 @@ class SubList extends AbstractList * * @param c the collection to insert * @return true if this list was modified, in other words, c is non-empty + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist + * @throws UnsupportedOperationException if this list does not support the + * addAll operation + * @throws ClassCastException if some element of c cannot be added to this + * list due to its type + * @throws IllegalArgumentException if some element of c cannot be added + * to this list for some other reason + * @throws NullPointerException if the specified collection is null */ public boolean addAll(Collection c) { @@ -819,6 +1013,9 @@ class SubList extends AbstractList * * @param index the start location of the iterator * @return a list iterator over the sublist + * @throws ConcurrentModificationException if the backing list has been + * modified externally to this sublist + * @throws IndexOutOfBoundsException if the value is out of range */ public ListIterator listIterator(final int index) { @@ -830,18 +1027,45 @@ class SubList extends AbstractList private final ListIterator i = backingList.listIterator(index + offset); private int position = index; + /** + * Tests to see if there are any more objects to + * return. + * + * @return True if the end of the list has not yet been + * reached. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public boolean hasNext() { checkMod(); return position < size; } + /** + * Tests to see if there are objects prior to the + * current position in the list. + * + * @return True if objects exist prior to the current + * position of the iterator. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public boolean hasPrevious() { checkMod(); return position > 0; } + /** + * Retrieves the next object from the list. + * + * @return The next object. + * @throws NoSuchElementException if there are no + * more objects to retrieve. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public Object next() { if (position == size) @@ -850,6 +1074,15 @@ class SubList extends AbstractList return i.next(); } + /** + * Retrieves the previous object from the list. + * + * @return The next object. + * @throws NoSuchElementException if there are no + * previous objects to retrieve. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public Object previous() { if (position == 0) @@ -858,16 +1091,42 @@ class SubList extends AbstractList return i.previous(); } + /** + * Returns the index of the next element in the + * list, which will be retrieved by next() + * + * @return The index of the next element. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public int nextIndex() { return i.nextIndex() - offset; } + /** + * Returns the index of the previous element in the + * list, which will be retrieved by previous() + * + * @return The index of the previous element. + * @throws ConcurrentModificationException if the + * list has been modified elsewhere. + */ public int previousIndex() { return i.previousIndex() - offset; } + /** + * Removes the last object retrieved by next() + * from the list, if the list supports object removal. + * + * @throws IllegalStateException if the iterator is positioned + * before the start of the list or the last object has already + * been removed. + * @throws UnsupportedOperationException if the list does + * not support removing elements. + */ public void remove() { i.remove(); @@ -876,11 +1135,44 @@ class SubList extends AbstractList modCount = backingList.modCount; } + + /** + * Replaces the last object retrieved by next() + * or previous with o, if the list supports object + * replacement and an add or remove operation has not already + * been performed. + * + * @throws IllegalStateException if the iterator is positioned + * before the start of the list or the last object has already + * been removed. + * @throws UnsupportedOperationException if the list doesn't support + * the addition or removal of elements. + * @throws ClassCastException if the type of o is not a valid type + * for this list. + * @throws IllegalArgumentException if something else related to o + * prevents its addition. + * @throws ConcurrentModificationException if the list + * has been modified elsewhere. + */ public void set(Object o) { i.set(o); } + /** + * Adds the supplied object before the element that would be returned + * by a call to next(), if the list supports addition. + * + * @param o The object to add to the list. + * @throws UnsupportedOperationException if the list doesn't support + * the addition of new elements. + * @throws ClassCastException if the type of o is not a valid type + * for this list. + * @throws IllegalArgumentException if something else related to o + * prevents its addition. + * @throws ConcurrentModificationException if the list + * has been modified elsewhere. + */ public void add(Object o) { i.add(o); diff --git a/libjava/java/util/AbstractMap.java b/libjava/java/util/AbstractMap.java index 4be5f3dbd94..d27e93b65d1 100644 --- a/libjava/java/util/AbstractMap.java +++ b/libjava/java/util/AbstractMap.java @@ -91,6 +91,21 @@ public abstract class AbstractMap implements Map { } + /** + * Returns a set view of the mappings in this Map. Each element in the + * set must be an implementation of Map.Entry. The set is backed by + * the map, so that changes in one show up in the other. Modifications + * made while an iterator is in progress cause undefined behavior. If + * the set supports removal, these methods must be valid: + * Iterator.remove, Set.remove, + * removeAll, retainAll, and clear. + * Element addition is not supported via this set. + * + * @return the entry set + * @see Map.Entry + */ + public abstract Set entrySet(); + /** * Remove all entries from this Map (optional operation). This default * implementation calls entrySet().clear(). NOTE: If the entry set does @@ -153,8 +168,9 @@ public abstract class AbstractMap implements Map * This implementation does a linear search, O(n), over the * entrySet(), returning true if a match * is found, false if the iteration ends. A match is - * defined as (value == null ? v == null : value.equals(v)) - * Subclasses are unlikely to implement this more efficiently. + * defined as a value, v, where (value == null ? v == null : + * value.equals(v)). Subclasses are unlikely to implement + * this more efficiently. * * @param value the value to search for * @return true if the map contains the value @@ -170,21 +186,6 @@ public abstract class AbstractMap implements Map return false; } - /** - * Returns a set view of the mappings in this Map. Each element in the - * set must be an implementation of Map.Entry. The set is backed by - * the map, so that changes in one show up in the other. Modifications - * made while an iterator is in progress cause undefined behavior. If - * the set supports removal, these methods must be valid: - * Iterator.remove, Set.remove, - * removeAll, retainAll, and clear. - * Element addition is not supported via this set. - * - * @return the entry set - * @see Map.Entry - */ - public abstract Set entrySet(); - /** * Compares the specified object with this map for equality. Returns * true if the other object is a Map with the same mappings, @@ -277,32 +278,75 @@ public abstract class AbstractMap implements Map if (keys == null) keys = new AbstractSet() { + /** + * Retrieves the number of keys in the backing map. + * + * @return The number of keys. + */ public int size() { return AbstractMap.this.size(); } + /** + * Returns true if the backing map contains the + * supplied key. + * + * @param key The key to search for. + * @return True if the key was found, false otherwise. + */ public boolean contains(Object key) { return containsKey(key); } + /** + * Returns an iterator which iterates over the keys + * in the backing map, using a wrapper around the + * iterator returned by entrySet(). + * + * @return An iterator over the keys. + */ public Iterator iterator() { return new Iterator() { + /** + * The iterator returned by entrySet(). + */ private final Iterator map_iterator = entrySet().iterator(); + /** + * Returns true if a call to next() will + * return another key. + * + * @return True if the iterator has not yet reached + * the last key. + */ public boolean hasNext() { return map_iterator.hasNext(); } + /** + * Returns the key from the next entry retrieved + * by the underlying entrySet() iterator. + * + * @return The next key. + */ public Object next() { return ((Map.Entry) map_iterator.next()).getKey(); } + /** + * Removes the map entry which has a key equal + * to that returned by the last call to + * next(). + * + * @throws UnsupportedOperationException if the + * map doesn't support removal. + */ public void remove() { map_iterator.remove(); @@ -343,11 +387,13 @@ public abstract class AbstractMap implements Map * * @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 + * by this map. + * @throws ClassCastException if a key or value is of the wrong type for + * adding to this map. * @throws IllegalArgumentException if something about a key or value - * prevents it from existing in this map - * @throws NullPointerException if the map forbids null keys or values, or - * if m is null. + * prevents it from existing in this map. + * @throws NullPointerException if the map forbids null keys or values. + * @throws NullPointerException if m is null. * @see #put(Object, Object) */ public void putAll(Map m) @@ -372,7 +418,9 @@ public abstract class AbstractMap implements Map * implementations override it for efficiency. * * @param key the key to remove - * @return the value the key mapped to, or null if not present + * @return the value the key mapped to, or null if not present. + * Null may also be returned if null values are allowed + * in the map and the value of this mapping is null. * @throws UnsupportedOperationException if deletion is unsupported * @see Iterator#remove() */ @@ -461,32 +509,76 @@ public abstract class AbstractMap implements Map if (values == null) values = new AbstractCollection() { + /** + * Returns the number of values stored in + * the backing map. + * + * @return The number of values. + */ public int size() { return AbstractMap.this.size(); } + /** + * Returns true if the backing map contains + * the supplied value. + * + * @param value The value to search for. + * @return True if the value was found, false otherwise. + */ public boolean contains(Object value) { return containsValue(value); } + /** + * Returns an iterator which iterates over the + * values in the backing map, by using a wrapper + * around the iterator returned by entrySet(). + * + * @return An iterator over the values. + */ public Iterator iterator() { return new Iterator() { + /** + * The iterator returned by entrySet(). + */ private final Iterator map_iterator = entrySet().iterator(); + /** + * Returns true if a call to next() will + * return another value. + * + * @return True if the iterator has not yet reached + * the last value. + */ public boolean hasNext() { return map_iterator.hasNext(); } + /** + * Returns the value from the next entry retrieved + * by the underlying entrySet() iterator. + * + * @return The next value. + */ public Object next() { return ((Map.Entry) map_iterator.next()).getValue(); } + /** + * Removes the map entry which has a key equal + * to that returned by the last call to + * next(). + * + * @throws UnsupportedOperationException if the + * map doesn't support removal. + */ public void remove() { map_iterator.remove(); @@ -533,6 +625,7 @@ public abstract class AbstractMap implements Map * @author Eric Blake */ // XXX - FIXME Use fully qualified implements as gcj 3.1 workaround. + // Bug still exists in 3.4.1 static class BasicMapEntry implements Map.Entry { /** @@ -627,7 +720,13 @@ public abstract class AbstractMap implements Map * * @param newVal the new value to store * @return the old value - * @throws NullPointerException if the map forbids null values + * @throws NullPointerException if the map forbids null values. + * @throws UnsupportedOperationException if the map doesn't support + * put(). + * @throws ClassCastException if the value is of a type unsupported + * by the map. + * @throws IllegalArgumentException if something else about this + * value prevents it being stored in the map. */ public Object setValue(Object newVal) { diff --git a/libjava/java/util/AbstractSequentialList.java b/libjava/java/util/AbstractSequentialList.java index e74c75c4fdb..0e5d59fceec 100644 --- a/libjava/java/util/AbstractSequentialList.java +++ b/libjava/java/util/AbstractSequentialList.java @@ -105,7 +105,9 @@ public abstract class AbstractSequentialList extends AbstractList * @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 + * some other reason. + * @throws NullPointerException if o is null and the list does not permit + * the addition of null values. */ public void add(int index, Object o) { @@ -137,6 +139,8 @@ public abstract class AbstractSequentialList extends AbstractList * @throws IllegalArgumentException if some element of c cannot be added * to this list for some other reason * @throws NullPointerException if the specified collection is null + * @throws NullPointerException if an object, o, in c is null and the list + * does not permit the addition of null values. * @see #add(int, Object) */ public boolean addAll(int index, Collection c) @@ -214,6 +218,8 @@ public abstract class AbstractSequentialList extends AbstractList * type * @throws IllegalArgumentException if o cannot be added to this list for * some other reason + * @throws NullPointerException if o is null and the list does not allow + * a value to be set to null. */ public Object set(int index, Object o) { diff --git a/libjava/java/util/ArrayList.java b/libjava/java/util/ArrayList.java index a451f1e4c4a..e39e4e0171b 100644 --- a/libjava/java/util/ArrayList.java +++ b/libjava/java/util/ArrayList.java @@ -120,7 +120,7 @@ public class ArrayList extends AbstractList } /** - * Construct a new ArrayList with the default capcity (16). + * Construct a new ArrayList with the default capacity (16). */ public ArrayList() { @@ -311,7 +311,8 @@ public class ArrayList extends AbstractList } /** - * Sets the element at the specified index. + * Sets the element at the specified index. The new element, e, + * can be an object of any type or null. * * @param index the index at which the element is being set * @param e the element to be set @@ -328,6 +329,7 @@ public class ArrayList extends AbstractList /** * Appends the supplied element to the end of this list. + * The element, e, can be an object of any type or null. * * @param e the element to be appended to this list * @return true, the add will always succeed @@ -344,6 +346,7 @@ public class ArrayList extends AbstractList /** * Adds the supplied element at the specified index, shifting all * elements currently at that index or higher one to the right. + * The element, e, can be an object of any type or null. * * @param index the index at which the element is being added * @param e the item being added @@ -397,7 +400,8 @@ public class ArrayList extends AbstractList /** * Add each element in the supplied Collection to this List. It is undefined * what happens if you modify the list while this is taking place; for - * example, if the collection contains this list. + * example, if the collection contains this list. c can contain objects + * of any type, as well as null values. * * @param c a Collection containing elements to be added to this List * @return true if the list was modified, in other words c is not empty @@ -410,7 +414,8 @@ public class ArrayList extends AbstractList /** * Add all elements in the supplied collection, inserting them beginning - * at the specified index. + * at the specified index. c can contain objects of any type, as well + * as null values. * * @param index the index at which the elements will be inserted * @param c the Collection containing the elements to be inserted diff --git a/libjava/java/util/Arrays.java b/libjava/java/util/Arrays.java index cc32d153900..bd6458def00 100644 --- a/libjava/java/util/Arrays.java +++ b/libjava/java/util/Arrays.java @@ -2374,16 +2374,35 @@ public class Arrays this.a = a; } + /** + * Returns the object at the specified index in + * the array. + * + * @param index The index to retrieve an object from. + * @return The object at the array index specified. + */ public Object get(int index) { return a[index]; } + /** + * Returns the size of the array. + * + * @return The size. + */ public int size() { return a.length; } + /** + * Replaces the object at the specified index + * with the supplied element. + * + * @param index The index at which to place the new object. + * @return The object replaced by this operation. + */ public Object set(int index, Object element) { Object old = a[index]; @@ -2391,11 +2410,25 @@ public class Arrays return old; } + /** + * Returns true if the array contains the + * supplied object. + * + * @param o The object to look for. + * @return True if the object was found. + */ public boolean contains(Object o) { return lastIndexOf(o) >= 0; } + /** + * Returns the first index at which the + * object, o, occurs in the array. + * + * @param o The object to search for. + * @return The first relevant index. + */ public int indexOf(Object o) { int size = a.length; @@ -2405,6 +2438,13 @@ public class Arrays return -1; } + /** + * Returns the last index at which the + * object, o, occurs in the array. + * + * @param o The object to search for. + * @return The last relevant index. + */ public int lastIndexOf(Object o) { int i = a.length; @@ -2414,11 +2454,28 @@ public class Arrays return -1; } + /** + * Transforms the list into an array of + * objects, by simplying cloning the array + * wrapped by this list. + * + * @return A clone of the internal array. + */ public Object[] toArray() { return (Object[]) a.clone(); } + /** + * Copies the objects from this list into + * the supplied array. The supplied array + * is shrunk or enlarged to the size of the + * internal array, and filled with its objects. + * + * @param The array to fill with the objects in this list. + * @return The array containing the objects in this list, + * which may or may not be == to array. + */ public Object[] toArray(Object[] array) { int size = a.length; diff --git a/libjava/java/util/BitSet.java b/libjava/java/util/BitSet.java index c56c0d18c7f..f81ba1506ed 100644 --- a/libjava/java/util/BitSet.java +++ b/libjava/java/util/BitSet.java @@ -133,7 +133,8 @@ public class BitSet implements Cloneable, Serializable * Performs the logical AND operation on this bit set and the * complement of the given set. This means it * selects every element in the first set, that isn't in the - * second set. The result is stored into this bit set. + * second set. The result is stored into this bit set and is + * effectively the set difference of the two. * * @param set the second bit set * @throws NullPointerException if set is null @@ -210,7 +211,8 @@ public class BitSet implements Cloneable, Serializable * * @param from the start range (inclusive) * @param to the end range (exclusive) - * @throws IndexOutOfBoundsException if from < 0 || from > to + * @throws IndexOutOfBoundsException if from < 0 || to < 0 || + * from > to * @since 1.4 */ public void clear(int from, int to) @@ -304,7 +306,8 @@ public class BitSet implements Cloneable, Serializable * * @param from the low index (inclusive) * @param to the high index (exclusive) - * @throws IndexOutOfBoundsException if from > to || from < 0 + * @throws IndexOutOfBoundsException if from > to || from < 0 || + * to < 0 * @since 1.4 */ public void flip(int from, int to) @@ -352,7 +355,8 @@ public class BitSet implements Cloneable, Serializable * * @param from the low index (inclusive) * @param to the high index (exclusive) - * @throws IndexOutOfBoundsException if from > to || from < 0 + * @throws IndexOutOfBoundsException if from > to || from < 0 || + * to < 0 * @since 1.4 */ public BitSet get(int from, int to) @@ -618,7 +622,8 @@ public class BitSet implements Cloneable, Serializable * * @param from the start range (inclusive) * @param to the end range (exclusive) - * @throws IndexOutOfBoundsException if from < 0 || from > to + * @throws IndexOutOfBoundsException if from < 0 || from > to || + * to < 0 * @since 1.4 */ public void set(int from, int to) @@ -649,7 +654,8 @@ public class BitSet implements Cloneable, Serializable * @param from the start range (inclusive) * @param to the end range (exclusive) * @param value the value to set it to - * @throws IndexOutOfBoundsException if from < 0 || from > to + * @throws IndexOutOfBoundsException if from < 0 || from > to || + * to < 0 * @since 1.4 */ public void set(int from, int to, boolean value) diff --git a/libjava/java/util/Calendar.java b/libjava/java/util/Calendar.java index b7ffb338106..05d48c2753c 100644 --- a/libjava/java/util/Calendar.java +++ b/libjava/java/util/Calendar.java @@ -585,7 +585,9 @@ public abstract class Calendar implements Serializable, Cloneable * if they are invalid. * @param field the time field. One of the time field constants. * @return the value of the specified field - * + * @throws ArrayIndexOutOfBoundsException if the field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. * @specnote Not final since JDK 1.4 */ public int get(int field) @@ -603,6 +605,9 @@ public abstract class Calendar implements Serializable, Cloneable * @param field the time field. One of the time field constants. * @return the value of the specified field, undefined if * areFieldsSet or isSet[field] is false. + * @throws ArrayIndexOutOfBoundsException if the field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. */ protected final int internalGet(int field) { @@ -614,7 +619,9 @@ public abstract class Calendar implements Serializable, Cloneable * the time in milliseconds. * @param field the time field. One of the time field constants * @param value the value to be set. - * + * @throws ArrayIndexOutOfBoundsException if field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. * @specnote Not final since JDK 1.4 */ public void set(int field, int value) @@ -718,6 +725,9 @@ public abstract class Calendar implements Serializable, Cloneable /** * Clears the values of the specified time field. * @param field the time field. One of the time field constants. + * @throws ArrayIndexOutOfBoundsException if field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. */ public final void clear(int field) { @@ -730,6 +740,9 @@ public abstract class Calendar implements Serializable, Cloneable /** * Determines if the specified field has a valid value. * @return true if the specified field has a value. + * @throws ArrayIndexOutOfBoundsException if the field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. */ public final boolean isSet(int field) { @@ -803,6 +816,9 @@ public abstract class Calendar implements Serializable, Cloneable * it does what you expect: Jan, 25 + 10 Days is Feb, 4. * @param field the time field. One of the time field constants. * @param amount the amount of time. + * @throws ArrayIndexOutOfBoundsException if the field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. */ public abstract void add(int field, int amount); @@ -817,6 +833,9 @@ public abstract class Calendar implements Serializable, Cloneable * The date June, 31 is automatically converted to July, 1. * @param field the time field. One of the time field constants. * @param up the direction, true for up, false for down. + * @throws ArrayIndexOutOfBoundsException if the field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. */ public abstract void roll(int field, boolean up); @@ -830,6 +849,9 @@ public abstract class Calendar implements Serializable, Cloneable * @param field the time field. One of the time field constants. * @param amount the amount to roll by, positive for rolling up, * negative for rolling down. + * @throws ArrayIndexOutOfBoundsException if the field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. * @since JDK1.2 */ public void roll(int field, int amount) @@ -965,6 +987,9 @@ public abstract class Calendar implements Serializable, Cloneable * This value is dependent on the values of the other fields. * @param field the time field. One of the time field constants. * @return the actual minimum value. + * @throws ArrayIndexOutOfBoundsException if the field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. * @since jdk1.2 */ public int getActualMinimum(int field) @@ -988,6 +1013,9 @@ public abstract class Calendar implements Serializable, Cloneable * This value is dependent on the values of the other fields. * @param field the time field. One of the time field constants. * @return the actual maximum value. + * @throws ArrayIndexOutOfBoundsException if the field is outside + * the valid range. The value of field must be >= 0 and + * <= FIELD_COUNT. * @since jdk1.2 */ public int getActualMaximum(int field) diff --git a/libjava/java/util/Collection.java b/libjava/java/util/Collection.java index 6ec9c4e3a02..be500b20086 100644 --- a/libjava/java/util/Collection.java +++ b/libjava/java/util/Collection.java @@ -223,6 +223,7 @@ public interface Collection * Remove all elements of a given collection from this collection. That is, * remove every element e such that c.contains(e). * + * @param c The collection of objects to be removed. * @return true if this collection was modified as a result of this call. * @throws UnsupportedOperationException if this collection does not * support the removeAll operation. @@ -238,6 +239,7 @@ public interface Collection * Remove all elements of this collection that are not contained in a given * collection. That is, remove every element e such that !c.contains(e). * + * @param c The collection of objects to be retained. * @return true if this collection was modified as a result of this call. * @throws UnsupportedOperationException if this collection does not * support the retainAll operation. diff --git a/libjava/java/util/ListIterator.java b/libjava/java/util/ListIterator.java index b4a6680c05f..6d53469ec99 100644 --- a/libjava/java/util/ListIterator.java +++ b/libjava/java/util/ListIterator.java @@ -127,12 +127,12 @@ public interface ListIterator extends Iterator * by nextIndex() and previousIndex() are incremented. * * @param o the object to insert into the list - * @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 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 + * support the add operation. */ void add(Object o); diff --git a/libjava/java/util/Map.java b/libjava/java/util/Map.java index 75658da5698..093e13d215d 100644 --- a/libjava/java/util/Map.java +++ b/libjava/java/util/Map.java @@ -227,7 +227,7 @@ public interface Map * null values may also return null if the key was removed. * * @param key the key to remove - * @return the value the key mapped to, or null if not present + * @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. diff --git a/libjava/java/util/SortedSet.java b/libjava/java/util/SortedSet.java index 81dff0ca229..415e95f8f18 100644 --- a/libjava/java/util/SortedSet.java +++ b/libjava/java/util/SortedSet.java @@ -50,7 +50,7 @@ package java.util; * k1.compareTo(k2) or comparator.compare(k1, k2) * must not throw a ClassCastException. The ordering must be consistent * with equals (see {@link Comparator} for this definition), if the - * map is to obey the general contract of the Set interface. If not, + * set is to obey the general contract of the Set interface. If not, * the results are well-defined, but probably not what you wanted. *

* @@ -85,7 +85,7 @@ public interface SortedSet extends Set Comparator comparator(); /** - * Returns the first (lowest sorted) element in the map. + * Returns the first (lowest sorted) element in the set. * * @return the first element * @throws NoSuchElementException if the set is empty. @@ -110,13 +110,13 @@ public interface SortedSet extends Set * contents * @throws IllegalArgumentException if this is a subSet, and toElement is out * of range - * @throws NullPointerException if toElement is null but the map does not + * @throws NullPointerException if toElement is null but the set does not * allow null elements */ SortedSet headSet(Object toElement); /** - * Returns the last (highest sorted) element in the map. + * Returns the last (highest sorted) element in the set. * * @return the last element * @throws NoSuchElementException if the set is empty. -- 2.30.2