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,68 ****
* 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
* 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,
--- 58,69 ----
* 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><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,162 ****
*
* @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)
* @throws NullPointerException if the specified element is null and this
! * collection does not permit null elements (optional)
*/
boolean contains(Object o);
/**
* Returns an iterator over the elements in this collection. There are no
--- 151,165 ----
*
* @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
! * (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException if the specified element is null and this
! * 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,234 ****
* 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
*/
<T> T[] toArray(T[] a);
// Modification Operations
--- 227,237 ----
* 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 {@code null}
*/
<T> T[] toArray(T[] a);
// Modification Operations
*** 277,289 ****
* 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)
* @throws NullPointerException if the specified element is null and this
! * collection does not permit null elements (optional)
* @throws UnsupportedOperationException if the <tt>remove</tt> operation
* is not supported by this collection
*/
boolean remove(Object o);
--- 280,294 ----
* 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
! * (<a href="#optional-restrictions">optional</a>)
* @throws NullPointerException if the specified element is null and this
! * 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,310 ****
* @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)
* @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
* @see #contains(Object)
*/
boolean containsAll(Collection<?> c);
/**
--- 302,318 ----
* @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
! * (<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
! * (<a href="#optional-restrictions">optional</a>),
! * or if the specified collection is {@code null}.
* @see #contains(Object)
*/
boolean containsAll(Collection<?> c);
/**
*** 321,331 ****
* 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
* @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
--- 329,339 ----
* 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 {@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,357 ****
* 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)
* @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
* @see #remove(Object)
* @see #contains(Object)
*/
boolean removeAll(Collection<?> c);
--- 352,368 ----
* 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
! * (<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
! * (<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,378 ****
* @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)
* @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
* @see #remove(Object)
* @see #contains(Object)
*/
boolean retainAll(Collection<?> c);
--- 376,392 ----
* @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
! * (<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
! * (<a href="#optional-restrictions">optional</a>),
! * or if the specified collection is {@code null}
* @see #remove(Object)
* @see #contains(Object)
*/
boolean retainAll(Collection<?> c);