Index: ChangeLog =================================================================== RCS file: /cvsroot/classpath/classpath/ChangeLog,v retrieving revision 1.2351 diff -u -3 -p -u -r1.2351 ChangeLog --- ChangeLog 28 Jul 2004 22:32:30 -0000 1.2351 +++ ChangeLog 29 Jul 2004 07:38:04 -0000 @@ -1,3 +1,10 @@ +2004-07-29 Andrew John Hughes + + * java/util/Collection.java, java/util/List.java, + java/util/Map.java, java/util/Set.java, + java/util/SortedMap.java, java/util/SortedSet.java: + Added additional exceptions to documentation. + 2004-07-28 Bryce McKinlay * gnu/java/security/action/GetPropertyAction.java (setParameters): Index: java/util/Collection.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/Collection.java,v retrieving revision 1.8 diff -u -3 -p -u -r1.8 Collection.java --- java/util/Collection.java 22 Jan 2002 22:27:01 -0000 1.8 +++ java/util/Collection.java 29 Jul 2004 07:38:05 -0000 @@ -94,6 +94,8 @@ public interface Collection * 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. */ @@ -108,6 +110,9 @@ public interface Collection * support the addAll operation. * @throws ClassCastException if some element of c cannot be added to this * collection due to its type. + * @throws NullPointerException if some element of c is null and this + * collection does not support the addition of null values. + * @throws NullPointerException if c itself is null. * @throws IllegalArgumentException if some element of c cannot be added * to this collection for some other reason. */ @@ -129,6 +134,10 @@ public interface Collection * @param o the element to look for. * @return true if this collection contains at least one element e such that * o == null ? e == null : o.equals(e). + * @throws ClassCastException if the type of o is not a valid type for this + * collection. + * @throws NullPointerException if o is null and this collection doesn't + * support null values. */ boolean contains(Object o); @@ -137,6 +146,11 @@ public interface Collection * * @param c the collection to test for. * @return true if for every element o in c, contains(o) would return true. + * @throws ClassCastException if the type of any element in c is not a valid + * type for this collection. + * @throws NullPointerException if some element of c is null and this + * collection does not support null values. + * @throws NullPointerException if c itself is null. */ boolean containsAll(Collection c); @@ -198,6 +212,10 @@ public interface Collection * 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. */ boolean remove(Object o); @@ -208,6 +226,11 @@ public interface Collection * @return true if this collection was modified as a result of this call. * @throws UnsupportedOperationException if this collection does not * support the removeAll operation. + * @throws ClassCastException if the type of any element in c is not a valid + * type for this collection. + * @throws NullPointerException if some element of c is null and this + * collection does not support removing null values. + * @throws NullPointerException if c itself is null. */ boolean removeAll(Collection c); @@ -218,6 +241,11 @@ public interface Collection * @return true if this collection was modified as a result of this call. * @throws UnsupportedOperationException if this collection does not * support the retainAll 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 retaining null values. + * @throws NullPointerException if c itself is null. */ boolean retainAll(Collection c); Index: java/util/List.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/List.java,v retrieving revision 1.9 diff -u -3 -p -u -r1.9 List.java --- java/util/List.java 30 Apr 2002 22:00:25 -0000 1.9 +++ java/util/List.java 29 Jul 2004 07:38:05 -0000 @@ -97,6 +97,8 @@ public interface List extends Collection * 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. */ void add(int index, Object o); @@ -113,6 +115,8 @@ public interface List extends Collection * 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. */ boolean add(Object o); @@ -134,6 +138,8 @@ public interface List extends Collection * 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 some element of c is null and this list + * doesn't support the addition of null values. * @throws NullPointerException if the specified collection is null * @see #add(int, Object) */ @@ -155,6 +161,8 @@ public interface List extends Collection * @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 some element of c is null and this list + * doesn't support the addition of null values. * @see #add(Object) */ boolean addAll(Collection c); @@ -175,6 +183,10 @@ public interface List extends Collection * * @param o the element to look for * @return true if this list contains the element + * @throws ClassCastException if the type of o is not a valid type + * for this list. + * @throws NullPointerException if o is null and the list doesn't + * support null values. */ boolean contains(Object o); @@ -184,6 +196,10 @@ public interface List extends Collection * @param c the collection to test for * @return true if for every element o in c, contains(o) would return true * @throws NullPointerException if the collection is null + * @throws ClassCastException if the type of any element in c is not a valid + * type for this list. + * @throws NullPointerException if some element of c is null and this + * list does not support null values. * @see #contains(Object) */ boolean containsAll(Collection c); @@ -240,7 +256,11 @@ while (i.hasNext()) * * @param o the object to search for * @return the least integer n such that o == null ? get(n) == null : - * o.equals(get(n)), or -1 if there is no such index + * o.equals(get(n)), or -1 if there is no such index. + * @throws ClassCastException if the type of o is not a valid + * type for this list. + * @throws NullPointerException if o is null and this + * list does not support null values. */ int indexOf(Object o); @@ -263,7 +283,11 @@ while (i.hasNext()) * list. * * @return the greatest integer n such that o == null ? get(n) == null - * : o.equals(get(n)), or -1 if there is no such index + * : o.equals(get(n)), or -1 if there is no such index. + * @throws ClassCastException if the type of o is not a valid + * type for this list. + * @throws NullPointerException if o is null and this + * list does not support null values. */ int lastIndexOf(Object o); @@ -310,6 +334,10 @@ while (i.hasNext()) * the list contained at least one occurrence of o * @throws UnsupportedOperationException if this list does not support the * remove operation + * @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 removing null values. */ boolean remove(Object o); @@ -322,6 +350,10 @@ while (i.hasNext()) * @throws UnsupportedOperationException if this list does not support the * removeAll operation * @throws NullPointerException if the collection is null + * @throws ClassCastException if the type of any element in c is not a valid + * type for this list. + * @throws NullPointerException if some element of c is null and this + * list does not support removing null values. * @see #remove(Object) * @see #contains(Object) */ @@ -337,6 +369,10 @@ while (i.hasNext()) * @throws UnsupportedOperationException if this list does not support the * retainAll operation * @throws NullPointerException if the collection is null + * @throws ClassCastException if the type of any element in c is not a valid + * type for this list. + * @throws NullPointerException if some element of c is null and this + * list does not support retaining null values. * @see #remove(Object) * @see #contains(Object) */ @@ -355,6 +391,8 @@ while (i.hasNext()) * 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. */ Object set(int index, Object o); @@ -381,8 +419,6 @@ while (i.hasNext()) * @return a List backed by a subsection of this list * @throws IndexOutOfBoundsException if fromIndex < 0 * || toIndex > size() || fromIndex > toIndex - * @throws IllegalArgumentException if fromIndex > toIndex (according to - * AbstractList). Don't you love Sun's inconsistent specifications? */ List subList(int fromIndex, int toIndex); Index: java/util/Map.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/Map.java,v retrieving revision 1.12 diff -u -3 -p -u -r1.12 Map.java --- java/util/Map.java 2 Apr 2004 21:29:34 -0000 1.12 +++ java/util/Map.java 29 Jul 2004 07:38:05 -0000 @@ -106,6 +106,10 @@ public interface Map * * @param value the value to search for * @return true if the map contains the value + * @throws ClassCastException if the type of the value is not a valid type + * for this map. + * @throws NullPointerException if the value is null and the map doesn't + * support null values. */ boolean containsValue(Object value); @@ -164,7 +168,8 @@ public interface Map * @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 the map forbids null keys or values + * @throws NullPointerException if either the key or the value is null, + * and the map forbids null keys or values * @see #containsKey(Object) */ Object put(Object key, Object value); @@ -224,8 +229,12 @@ public interface Map * @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. */ - Object remove(Object o); + Object remove(Object key); /** * Returns the number of key-value mappings in the map. If there are more Index: java/util/Set.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/Set.java,v retrieving revision 1.7 diff -u -3 -p -u -r1.7 Set.java --- java/util/Set.java 22 Jan 2002 22:27:01 -0000 1.7 +++ java/util/Set.java 29 Jul 2004 07:38:05 -0000 @@ -118,6 +118,10 @@ public interface Set extends Collection * * @param o the object to look for * @return true if it is found in the set + * @throws ClassCastException if the type of o is not a valid type + * for this set. + * @throws NullPointerException if o is null and this set doesn't + * support null values. */ boolean contains(Object o); @@ -129,6 +133,10 @@ public interface Set extends Collection * @param c the collection to check membership in * @return true if all elements in this set are in c * @throws NullPointerException if c is null + * @throws ClassCastException if the type of any element in c is not + * a valid type for this set. + * @throws NullPointerException if some element of c is null and this + * set doesn't support null values. * @see #contains(Object) */ boolean containsAll(Collection c); @@ -148,6 +156,7 @@ public interface Set extends Collection * equals, this is the sum of the hashcode of all elements in the set. * * @return the sum of the hashcodes of all set elements + * @see #equals(Object) */ int hashCode(); @@ -174,6 +183,10 @@ public interface Set extends Collection * @param o the object to remove * @return true if the set changed (an object was removed) * @throws UnsupportedOperationException if this operation is not allowed + * @throws ClassCastException if the type of o is not a valid type + * for this set. + * @throws NullPointerException if o is null and this set doesn't allow + * the removal of a null value. */ boolean remove(Object o); @@ -186,6 +199,10 @@ public interface Set extends Collection * @return true if this set changed as a result * @throws UnsupportedOperationException if this operation is not allowed * @throws NullPointerException if c is null + * @throws ClassCastException if the type of any element in c is not + * a valid type for this set. + * @throws NullPointerException if some element of c is null and this + * set doesn't support removing null values. * @see #remove(Object) */ boolean removeAll(Collection c); @@ -199,6 +216,10 @@ public interface Set extends Collection * @return true if this set was modified * @throws UnsupportedOperationException if this operation is not allowed * @throws NullPointerException if c is null + * @throws ClassCastException if the type of any element in c is not + * a valid type for this set. + * @throws NullPointerException if some element of c is null and this + * set doesn't support retaining null values. * @see #remove(Object) */ boolean retainAll(Collection c); Index: java/util/SortedMap.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/SortedMap.java,v retrieving revision 1.6 diff -u -3 -p -u -r1.6 SortedMap.java --- java/util/SortedMap.java 22 Jan 2002 22:27:01 -0000 1.6 +++ java/util/SortedMap.java 29 Jul 2004 07:38:06 -0000 @@ -86,6 +86,7 @@ public interface SortedMap extends Map * Returns the first (lowest sorted) key in the map. * * @return the first key + * @throws NoSuchElementException if this map is empty. */ Object firstKey(); @@ -115,6 +116,7 @@ public interface SortedMap extends Map * Returns the last (highest sorted) key in the map. * * @return the last key + * @throws NoSuchElementException if this map is empty. */ Object lastKey(); Index: java/util/SortedSet.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/util/SortedSet.java,v retrieving revision 1.6 diff -u -3 -p -u -r1.6 SortedSet.java --- java/util/SortedSet.java 22 Jan 2002 22:27:01 -0000 1.6 +++ java/util/SortedSet.java 29 Jul 2004 07:38:06 -0000 @@ -88,6 +88,7 @@ public interface SortedSet extends Set * Returns the first (lowest sorted) element in the map. * * @return the first element + * @throws NoSuchElementException if the set is empty. */ Object first(); @@ -118,6 +119,7 @@ public interface SortedSet extends Set * Returns the last (highest sorted) element in the map. * * @return the last element + * @throws NoSuchElementException if the set is empty. */ Object last();