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);