From b828123e23c9a8fb42b98a54b34141fe4dace764 Mon Sep 17 00:00:00 2001 From: Andrew John Hughes Date: Sun, 1 Aug 2004 11:14:42 +0000 Subject: [PATCH] Collection.java, [...]: Added additional exceptions to documentation. 2004-08-01 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. From-SVN: r85403 --- libjava/ChangeLog | 7 +++++ libjava/java/util/Collection.java | 28 ++++++++++++++++++++ libjava/java/util/List.java | 44 ++++++++++++++++++++++++++++--- libjava/java/util/Map.java | 13 +++++++-- libjava/java/util/Set.java | 21 +++++++++++++++ libjava/java/util/SortedMap.java | 2 ++ libjava/java/util/SortedSet.java | 2 ++ 7 files changed, 111 insertions(+), 6 deletions(-) diff --git a/libjava/ChangeLog b/libjava/ChangeLog index a08c38662a7..28973292b36 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,3 +1,10 @@ +2004-08-01 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-08-01 Danny Smith PR libgcj/16814 diff --git a/libjava/java/util/Collection.java b/libjava/java/util/Collection.java index 977c603e086..6ec9c4e3a02 100644 --- a/libjava/java/util/Collection.java +++ b/libjava/java/util/Collection.java @@ -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); diff --git a/libjava/java/util/List.java b/libjava/java/util/List.java index 22a6b83fc37..0f7f409dae6 100644 --- a/libjava/java/util/List.java +++ b/libjava/java/util/List.java @@ -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); diff --git a/libjava/java/util/Map.java b/libjava/java/util/Map.java index f7643f92a5e..75658da5698 100644 --- a/libjava/java/util/Map.java +++ b/libjava/java/util/Map.java @@ -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 diff --git a/libjava/java/util/Set.java b/libjava/java/util/Set.java index 8a3290f1e40..eb4df3ef299 100644 --- a/libjava/java/util/Set.java +++ b/libjava/java/util/Set.java @@ -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); diff --git a/libjava/java/util/SortedMap.java b/libjava/java/util/SortedMap.java index 2ae36f97b3c..742524e7a68 100644 --- a/libjava/java/util/SortedMap.java +++ b/libjava/java/util/SortedMap.java @@ -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(); diff --git a/libjava/java/util/SortedSet.java b/libjava/java/util/SortedSet.java index 401edb97395..81dff0ca229 100644 --- a/libjava/java/util/SortedSet.java +++ b/libjava/java/util/SortedSet.java @@ -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(); -- 2.30.2