Commit b828123e by Andrew John Hughes Committed by Michael Koch

Collection.java, [...]: Added additional exceptions to documentation.

2004-08-01  Andrew John Hughes  <gnu_andrew@member.fsf.org>

	* 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
parent 5b5662ee
2004-08-01 Andrew John Hughes <gnu_andrew@member.fsf.org>
* 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 <dannysmith@users.sourceforge.net> 2004-08-01 Danny Smith <dannysmith@users.sourceforge.net>
PR libgcj/16814 PR libgcj/16814
......
...@@ -94,6 +94,8 @@ public interface Collection ...@@ -94,6 +94,8 @@ public interface Collection
* support the add operation. * support the add operation.
* @throws ClassCastException if o cannot be added to this collection due * @throws ClassCastException if o cannot be added to this collection due
* to its type. * 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 * @throws IllegalArgumentException if o cannot be added to this
* collection for some other reason. * collection for some other reason.
*/ */
...@@ -108,6 +110,9 @@ public interface Collection ...@@ -108,6 +110,9 @@ public interface Collection
* support the addAll operation. * support the addAll operation.
* @throws ClassCastException if some element of c cannot be added to this * @throws ClassCastException if some element of c cannot be added to this
* collection due to its type. * 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 * @throws IllegalArgumentException if some element of c cannot be added
* to this collection for some other reason. * to this collection for some other reason.
*/ */
...@@ -129,6 +134,10 @@ public interface Collection ...@@ -129,6 +134,10 @@ public interface Collection
* @param o the element to look for. * @param o the element to look for.
* @return true if this collection contains at least one element e such that * @return true if this collection contains at least one element e such that
* <code>o == null ? e == null : o.equals(e)</code>. * <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.
*/ */
boolean contains(Object o); boolean contains(Object o);
...@@ -137,6 +146,11 @@ public interface Collection ...@@ -137,6 +146,11 @@ public interface Collection
* *
* @param c the collection to test for. * @param c the collection to test for.
* @return true if for every element o in c, contains(o) would return true. * @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); boolean containsAll(Collection c);
...@@ -198,6 +212,10 @@ public interface Collection ...@@ -198,6 +212,10 @@ public interface Collection
* if the collection contained at least one occurrence of o. * if the collection contained at least one occurrence of o.
* @throws UnsupportedOperationException if this collection does not * @throws UnsupportedOperationException if this collection does not
* support the remove operation. * 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); boolean remove(Object o);
...@@ -208,6 +226,11 @@ public interface Collection ...@@ -208,6 +226,11 @@ public interface Collection
* @return true if this collection was modified as a result of this call. * @return true if this collection was modified as a result of this call.
* @throws UnsupportedOperationException if this collection does not * @throws UnsupportedOperationException if this collection does not
* support the removeAll operation. * 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); boolean removeAll(Collection c);
...@@ -218,6 +241,11 @@ public interface Collection ...@@ -218,6 +241,11 @@ public interface Collection
* @return true if this collection was modified as a result of this call. * @return true if this collection was modified as a result of this call.
* @throws UnsupportedOperationException if this collection does not * @throws UnsupportedOperationException if this collection does not
* support the retainAll operation. * 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); boolean retainAll(Collection c);
......
...@@ -97,6 +97,8 @@ public interface List extends Collection ...@@ -97,6 +97,8 @@ public interface List extends Collection
* type * type
* @throws IllegalArgumentException if o cannot be added to this list for * @throws IllegalArgumentException if o cannot be added to this list for
* some other reason * 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); void add(int index, Object o);
...@@ -113,6 +115,8 @@ public interface List extends Collection ...@@ -113,6 +115,8 @@ public interface List extends Collection
* type * type
* @throws IllegalArgumentException if o cannot be added to this list for * @throws IllegalArgumentException if o cannot be added to this list for
* some other reason * some other reason
* @throws NullPointerException if o is null and this list doesn't support
* the addition of null values.
*/ */
boolean add(Object o); boolean add(Object o);
...@@ -134,6 +138,8 @@ public interface List extends Collection ...@@ -134,6 +138,8 @@ public interface List extends Collection
* list due to its type * list due to its type
* @throws IllegalArgumentException if some element of c cannot be added * @throws IllegalArgumentException if some element of c cannot be added
* to this list for some other reason * 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 * @throws NullPointerException if the specified collection is null
* @see #add(int, Object) * @see #add(int, Object)
*/ */
...@@ -155,6 +161,8 @@ public interface List extends Collection ...@@ -155,6 +161,8 @@ public interface List extends Collection
* @throws IllegalArgumentException if some element of c cannot be added * @throws IllegalArgumentException if some element of c cannot be added
* to this list for some other reason * to this list for some other reason
* @throws NullPointerException if the specified collection is null * @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) * @see #add(Object)
*/ */
boolean addAll(Collection c); boolean addAll(Collection c);
...@@ -175,6 +183,10 @@ public interface List extends Collection ...@@ -175,6 +183,10 @@ public interface List extends Collection
* *
* @param o the element to look for * @param o the element to look for
* @return true if this list contains the element * @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); boolean contains(Object o);
...@@ -184,6 +196,10 @@ public interface List extends Collection ...@@ -184,6 +196,10 @@ public interface List extends Collection
* @param c the collection to test for * @param c the collection to test for
* @return true if for every element o in c, contains(o) would return true * @return true if for every element o in c, contains(o) would return true
* @throws NullPointerException if the collection is null * @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) * @see #contains(Object)
*/ */
boolean containsAll(Collection c); boolean containsAll(Collection c);
...@@ -240,7 +256,11 @@ while (i.hasNext()) ...@@ -240,7 +256,11 @@ while (i.hasNext())
* *
* @param o the object to search for * @param o the object to search for
* @return the least integer n such that <code>o == null ? get(n) == null : * @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 * 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.
*/ */
int indexOf(Object o); int indexOf(Object o);
...@@ -263,7 +283,11 @@ while (i.hasNext()) ...@@ -263,7 +283,11 @@ while (i.hasNext())
* list. * list.
* *
* @return the greatest integer n such that <code>o == null ? get(n) == null * @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 * : 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.
*/ */
int lastIndexOf(Object o); int lastIndexOf(Object o);
...@@ -310,6 +334,10 @@ while (i.hasNext()) ...@@ -310,6 +334,10 @@ while (i.hasNext())
* the list contained at least one occurrence of o * the list contained at least one occurrence of o
* @throws UnsupportedOperationException if this list does not support the * @throws UnsupportedOperationException if this list does not support the
* remove operation * 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); boolean remove(Object o);
...@@ -322,6 +350,10 @@ while (i.hasNext()) ...@@ -322,6 +350,10 @@ while (i.hasNext())
* @throws UnsupportedOperationException if this list does not support the * @throws UnsupportedOperationException if this list does not support the
* removeAll operation * removeAll operation
* @throws NullPointerException if the collection is null * @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 #remove(Object)
* @see #contains(Object) * @see #contains(Object)
*/ */
...@@ -337,6 +369,10 @@ while (i.hasNext()) ...@@ -337,6 +369,10 @@ while (i.hasNext())
* @throws UnsupportedOperationException if this list does not support the * @throws UnsupportedOperationException if this list does not support the
* retainAll operation * retainAll operation
* @throws NullPointerException if the collection is null * @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 #remove(Object)
* @see #contains(Object) * @see #contains(Object)
*/ */
...@@ -355,6 +391,8 @@ while (i.hasNext()) ...@@ -355,6 +391,8 @@ while (i.hasNext())
* type * type
* @throws IllegalArgumentException if o cannot be added to this list for * @throws IllegalArgumentException if o cannot be added to this list for
* some other reason * some other reason
* @throws NullPointerException if o is null and this
* list does not support null values.
*/ */
Object set(int index, Object o); Object set(int index, Object o);
...@@ -381,8 +419,6 @@ while (i.hasNext()) ...@@ -381,8 +419,6 @@ while (i.hasNext())
* @return a List backed by a subsection of this list * @return a List backed by a subsection of this list
* @throws IndexOutOfBoundsException if fromIndex &lt; 0 * @throws IndexOutOfBoundsException if fromIndex &lt; 0
* || toIndex &gt; size() || fromIndex &gt; toIndex * || toIndex &gt; size() || fromIndex &gt; toIndex
* @throws IllegalArgumentException if fromIndex &gt; toIndex (according to
* AbstractList). Don't you love Sun's inconsistent specifications?
*/ */
List subList(int fromIndex, int toIndex); List subList(int fromIndex, int toIndex);
......
...@@ -106,6 +106,10 @@ public interface Map ...@@ -106,6 +106,10 @@ public interface Map
* *
* @param value the value to search for * @param value the value to search for
* @return true if the map contains the value * @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); boolean containsValue(Object value);
...@@ -164,7 +168,8 @@ public interface Map ...@@ -164,7 +168,8 @@ public interface Map
* @throws ClassCastException if the key or value is of the wrong type * @throws ClassCastException if the key or value is of the wrong type
* @throws IllegalArgumentException if something about this key or value * @throws IllegalArgumentException if something about this key or value
* prevents it from existing in this map * 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) * @see #containsKey(Object)
*/ */
Object put(Object key, Object value); Object put(Object key, Object value);
...@@ -224,8 +229,12 @@ public interface Map ...@@ -224,8 +229,12 @@ public interface Map
* @param key the key to remove * @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 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 * Returns the number of key-value mappings in the map. If there are more
......
...@@ -118,6 +118,10 @@ public interface Set extends Collection ...@@ -118,6 +118,10 @@ public interface Set extends Collection
* *
* @param o the object to look for * @param o the object to look for
* @return true if it is found in the set * @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); boolean contains(Object o);
...@@ -129,6 +133,10 @@ public interface Set extends Collection ...@@ -129,6 +133,10 @@ public interface Set extends Collection
* @param c the collection to check membership in * @param c the collection to check membership in
* @return true if all elements in this set are in c * @return true if all elements in this set are in c
* @throws NullPointerException if c is null * @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) * @see #contains(Object)
*/ */
boolean containsAll(Collection c); boolean containsAll(Collection c);
...@@ -148,6 +156,7 @@ public interface Set extends Collection ...@@ -148,6 +156,7 @@ public interface Set extends Collection
* equals, this is the sum of the hashcode of all elements in the set. * equals, this is the sum of the hashcode of all elements in the set.
* *
* @return the sum of the hashcodes of all set elements * @return the sum of the hashcodes of all set elements
* @see #equals(Object)
*/ */
int hashCode(); int hashCode();
...@@ -174,6 +183,10 @@ public interface Set extends Collection ...@@ -174,6 +183,10 @@ public interface Set extends Collection
* @param o the object to remove * @param o the object to remove
* @return true if the set changed (an object was removed) * @return true if the set changed (an object was removed)
* @throws UnsupportedOperationException if this operation is not allowed * @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); boolean remove(Object o);
...@@ -186,6 +199,10 @@ public interface Set extends Collection ...@@ -186,6 +199,10 @@ public interface Set extends Collection
* @return true if this set changed as a result * @return true if this set changed as a result
* @throws UnsupportedOperationException if this operation is not allowed * @throws UnsupportedOperationException if this operation is not allowed
* @throws NullPointerException if c is null * @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) * @see #remove(Object)
*/ */
boolean removeAll(Collection c); boolean removeAll(Collection c);
...@@ -199,6 +216,10 @@ public interface Set extends Collection ...@@ -199,6 +216,10 @@ public interface Set extends Collection
* @return true if this set was modified * @return true if this set was modified
* @throws UnsupportedOperationException if this operation is not allowed * @throws UnsupportedOperationException if this operation is not allowed
* @throws NullPointerException if c is null * @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) * @see #remove(Object)
*/ */
boolean retainAll(Collection c); boolean retainAll(Collection c);
......
...@@ -86,6 +86,7 @@ public interface SortedMap extends Map ...@@ -86,6 +86,7 @@ public interface SortedMap extends Map
* Returns the first (lowest sorted) key in the map. * Returns the first (lowest sorted) key in the map.
* *
* @return the first key * @return the first key
* @throws NoSuchElementException if this map is empty.
*/ */
Object firstKey(); Object firstKey();
...@@ -115,6 +116,7 @@ public interface SortedMap extends Map ...@@ -115,6 +116,7 @@ public interface SortedMap extends Map
* Returns the last (highest sorted) key in the map. * Returns the last (highest sorted) key in the map.
* *
* @return the last key * @return the last key
* @throws NoSuchElementException if this map is empty.
*/ */
Object lastKey(); Object lastKey();
......
...@@ -88,6 +88,7 @@ public interface SortedSet extends Set ...@@ -88,6 +88,7 @@ public interface SortedSet extends Set
* Returns the first (lowest sorted) element in the map. * Returns the first (lowest sorted) element in the map.
* *
* @return the first element * @return the first element
* @throws NoSuchElementException if the set is empty.
*/ */
Object first(); Object first();
...@@ -118,6 +119,7 @@ public interface SortedSet extends Set ...@@ -118,6 +119,7 @@ public interface SortedSet extends Set
* Returns the last (highest sorted) element in the map. * Returns the last (highest sorted) element in the map.
* *
* @return the last element * @return the last element
* @throws NoSuchElementException if the set is empty.
*/ */
Object last(); Object last();
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment