src/share/classes/java/util/Collection.java
Print this page
rev 3977 : 6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
@@ -58,11 +58,12 @@
* invocation would have no effect on the collection. For example, invoking
* the {@link #addAll(Collection)} method on an unmodifiable collection may,
* but is not required to, throw the exception if the collection to be added
* is empty.
*
- * <p>Some collection implementations have restrictions on the elements that
+ * <p><a name="optional-restrictions"/>
+ * Some collection implementations have restrictions on the elements that
* they may contain. For example, some implementations prohibit null elements,
* and some have restrictions on the types of their elements. Attempting to
* add an ineligible element throws an unchecked exception, typically
* <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting
* to query the presence of an ineligible element may throw an exception,
@@ -150,13 +151,15 @@
*
* @param o element whose presence in this collection is to be tested
* @return <tt>true</tt> if this collection contains the specified
* element
* @throws ClassCastException if the type of the specified element
- * is incompatible with this collection (optional)
+ * is incompatible with this collection
+ * (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException if the specified element is null and this
- * collection does not permit null elements (optional)
+ * collection does not permit null elements
+ * (<a href="#optional-restrictions">optional</a>)
*/
boolean contains(Object o);
/**
* Returns an iterator over the elements in this collection. There are no
@@ -224,11 +227,11 @@
* runtime type is allocated for this purpose.
* @return an array containing all of the elements in this collection
* @throws ArrayStoreException if the runtime type of the specified array
* is not a supertype of the runtime type of every element in
* this collection
- * @throws NullPointerException if the specified array is null
+ * @throws NullPointerException if the specified array is {@code null}
*/
<T> T[] toArray(T[] a);
// Modification Operations
@@ -277,13 +280,15 @@
* equivalently, if this collection changed as a result of the call).
*
* @param o element to be removed from this collection, if present
* @return <tt>true</tt> if an element was removed as a result of this call
* @throws ClassCastException if the type of the specified element
- * is incompatible with this collection (optional)
+ * is incompatible with this collection
+ * (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException if the specified element is null and this
- * collection does not permit null elements (optional)
+ * collection does not permit null elements
+ * (<a href="#optional-restrictions">optional</a>)
* @throws UnsupportedOperationException if the <tt>remove</tt> operation
* is not supported by this collection
*/
boolean remove(Object o);
@@ -297,14 +302,17 @@
* @param c collection to be checked for containment in this collection
* @return <tt>true</tt> if this collection contains all of the elements
* in the specified collection
* @throws ClassCastException if the types of one or more elements
* in the specified collection are incompatible with this
- * collection (optional)
+ * collection
+ * (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException if the specified collection contains one
* or more null elements and this collection does not permit null
- * elements (optional), or if the specified collection is null
+ * elements
+ * (<a href="#optional-restrictions">optional</a>),
+ * or if the specified collection is {@code null}.
* @see #contains(Object)
*/
boolean containsAll(Collection<?> c);
/**
@@ -321,11 +329,11 @@
* is not supported by this collection
* @throws ClassCastException if the class of an element of the specified
* collection prevents it from being added to this collection
* @throws NullPointerException if the specified collection contains a
* null element and this collection does not permit null elements,
- * or if the specified collection is null
+ * or if the specified collection is {@code null}
* @throws IllegalArgumentException if some property of an element of the
* specified collection prevents it from being added to this
* collection
* @throws IllegalStateException if not all the elements can be added at
* this time due to insertion restrictions
@@ -344,14 +352,17 @@
* call
* @throws UnsupportedOperationException if the <tt>removeAll</tt> method
* is not supported by this collection
* @throws ClassCastException if the types of one or more elements
* in this collection are incompatible with the specified
- * collection (optional)
+ * collection
+ * (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException if this collection contains one or more
* null elements and the specified collection does not support
- * null elements (optional), or if the specified collection is null
+ * null elements
+ * (<a href="#optional-restrictions">optional</a>),
+ * or if the specified collection is {@code null}
* @see #remove(Object)
* @see #contains(Object)
*/
boolean removeAll(Collection<?> c);
@@ -365,14 +376,17 @@
* @return <tt>true</tt> if this collection changed as a result of the call
* @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
* is not supported by this collection
* @throws ClassCastException if the types of one or more elements
* in this collection are incompatible with the specified
- * collection (optional)
+ * collection
+ * (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException if this collection contains one or more
* null elements and the specified collection does not permit null
- * elements (optional), or if the specified collection is null
+ * elements
+ * (<a href="#optional-restrictions">optional</a>),
+ * or if the specified collection is {@code null}
* @see #remove(Object)
* @see #contains(Object)
*/
boolean retainAll(Collection<?> c);