6546713: link the word (optional) in exception specifications to the text which provides explanation and context

Reviewed-by: dholmes, dl

jdk/src/share/classes/java/util/AbstractSet.java

@@ -156,9 +156,11 @@ public abstract class AbstractSet<E> extends AbstractCollection<E> implements Se
      * @throws UnsupportedOperationException if the <tt>removeAll</tt> operation
      *         is not supported by this set
      * @throws ClassCastException if the class of an element of this set
-     *         is incompatible with the specified collection (optional)
+     *         is incompatible with the specified collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this set contains a null element and the
-     *         specified collection does not permit null elements (optional),
+     *         specified collection does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>),
      *         or if the specified collection is null
      * @see #remove(Object)
      * @see #contains(Object)

jdk/src/share/classes/java/util/ArrayList.java

@@ -628,9 +628,11 @@ public class ArrayList<E> extends AbstractList<E>
      * @param c collection containing elements to be removed from this list
      * @return {@code true} if this list changed as a result of the call
      * @throws ClassCastException if the class of an element of this list
-     *         is incompatible with the specified collection (optional)
+     *         is incompatible with the specified collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this list contains a null element and the
-     *         specified collection does not permit null elements (optional),
+     *         specified collection does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>),
      *         or if the specified collection is null
      * @see Collection#contains(Object)
      */
@@ -646,9 +648,11 @@ public class ArrayList<E> extends AbstractList<E>
      * @param c collection containing elements to be retained in this list
      * @return {@code true} if this list changed as a result of the call
      * @throws ClassCastException if the class of an element of this list
-     *         is incompatible with the specified collection (optional)
+     *         is incompatible with the specified collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this list contains a null element and the
-     *         specified collection does not permit null elements (optional),
+     *         specified collection does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>),
      *         or if the specified collection is null
      * @see Collection#contains(Object)
      */

jdk/src/share/classes/java/util/Collection.java

@@ -60,7 +60,8 @@ package java.util;
  * 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
@@ -152,9 +153,11 @@ public interface Collection<E> extends Iterable<E> {
      * @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);
 
@@ -279,9 +282,11 @@ public interface Collection<E> extends Iterable<E> {
      * @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
      */
@@ -299,10 +304,13 @@ public interface Collection<E> extends Iterable<E> {
      *         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 null.
      * @see    #contains(Object)
      */
     boolean containsAll(Collection<?> c);
@@ -346,10 +354,13 @@ public interface Collection<E> extends Iterable<E> {
      *         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 null
      * @see #remove(Object)
      * @see #contains(Object)
      */
@@ -367,10 +378,13 @@ public interface Collection<E> extends Iterable<E> {
      *         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 null
      * @see #remove(Object)
      * @see #contains(Object)
      */

jdk/src/share/classes/java/util/Collections.java

@@ -3746,9 +3746,10 @@ public class Collections {
      * @throws NullPointerException if either collection is {@code null}.
      * @throws NullPointerException if one collection contains a {@code null}
      * element and {@code null} is not an eligible element for the other collection.
-     * (optional)
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws ClassCastException if one collection contains an element that is
-     * of a type which is ineligible for the other collection. (optional)
+     * of a type which is ineligible for the other collection.
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @since 1.5
      */
     public static boolean disjoint(Collection<?> c1, Collection<?> c2) {

jdk/src/share/classes/java/util/Deque.java

@@ -351,9 +351,11 @@ public interface Deque<E> extends Queue<E> {
      * @param o element to be removed from this deque, if present
      * @return <tt>true</tt> if an element was removed as a result of this call
      * @throws ClassCastException if the class of the specified element
-     *         is incompatible with this deque (optional)
+     *         is incompatible with this deque
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements (optional)
+     *         deque does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     boolean removeFirstOccurrence(Object o);
 
@@ -369,9 +371,11 @@ public interface Deque<E> extends Queue<E> {
      * @param o element to be removed from this deque, if present
      * @return <tt>true</tt> if an element was removed as a result of this call
      * @throws ClassCastException if the class of the specified element
-     *         is incompatible with this deque (optional)
+     *         is incompatible with this deque
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements (optional)
+     *         deque does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     boolean removeLastOccurrence(Object o);
 
@@ -527,9 +531,11 @@ public interface Deque<E> extends Queue<E> {
      * @param o element to be removed from this deque, if present
      * @return <tt>true</tt> if an element was removed as a result of this call
      * @throws ClassCastException if the class of the specified element
-     *         is incompatible with this deque (optional)
+     *         is incompatible with this deque
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements (optional)
+     *         deque does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     boolean remove(Object o);
 
@@ -542,9 +548,11 @@ public interface Deque<E> extends Queue<E> {
      * @param o element whose presence in this deque is to be tested
      * @return <tt>true</tt> if this deque contains the specified element
      * @throws ClassCastException if the type of the specified element
-     *         is incompatible with this deque (optional)
+     *         is incompatible with this deque
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements (optional)
+     *         deque does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     boolean contains(Object o);
 

jdk/src/share/classes/java/util/List.java

@@ -134,9 +134,11 @@ public interface List<E> extends Collection<E> {
      * @param o element whose presence in this list is to be tested
      * @return <tt>true</tt> if this list contains the specified element
      * @throws ClassCastException if the type of the specified element
-     *         is incompatible with this list (optional)
+     *         is incompatible with this list
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         list does not permit null elements (optional)
+     *         list does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     boolean contains(Object o);
 
@@ -245,9 +247,11 @@ public interface List<E> extends Collection<E> {
      * @param o element to be removed from this list, if present
      * @return <tt>true</tt> if this list contained the specified element
      * @throws ClassCastException if the type of the specified element
-     *         is incompatible with this list (optional)
+     *         is incompatible with this list
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         list does not permit null elements (optional)
+     *         list does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws UnsupportedOperationException if the <tt>remove</tt> operation
      *         is not supported by this list
      */
@@ -265,10 +269,13 @@ public interface List<E> extends Collection<E> {
      *         specified collection
      * @throws ClassCastException if the types of one or more elements
      *         in the specified collection are incompatible with this
-     *         list (optional)
+     *         list
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified collection contains one
      *         or more null elements and this list does not permit null
-     *         elements (optional), or if the specified collection is null
+     *         elements
+     *         (<a href="Collection.html#optional-restrictions">optional</a>),
+     *         or if the specified collection is null
      * @see #contains(Object)
      */
     boolean containsAll(Collection<?> c);
@@ -334,9 +341,11 @@ public interface List<E> extends Collection<E> {
      * @throws UnsupportedOperationException if the <tt>removeAll</tt> operation
      *         is not supported by this list
      * @throws ClassCastException if the class of an element of this list
-     *         is incompatible with the specified collection (optional)
+     *         is incompatible with the specified collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this list contains a null element and the
-     *         specified collection does not permit null elements (optional),
+     *         specified collection does not permit null elements
+     *         (<a href="Collection.html#optional-restrictions">optional</a>),
      *         or if the specified collection is null
      * @see #remove(Object)
      * @see #contains(Object)
@@ -354,9 +363,11 @@ public interface List<E> extends Collection<E> {
      * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
      *         is not supported by this list
      * @throws ClassCastException if the class of an element of this list
-     *         is incompatible with the specified collection (optional)
+     *         is incompatible with the specified collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this list contains a null element and the
-     *         specified collection does not permit null elements (optional),
+     *         specified collection does not permit null elements
+     *         (<a href="Collection.html#optional-restrictions">optional</a>),
      *         or if the specified collection is null
      * @see #remove(Object)
      * @see #contains(Object)
@@ -493,9 +504,11 @@ public interface List<E> extends Collection<E> {
      * @return the index of the first occurrence of the specified element in
      *         this list, or -1 if this list does not contain the element
      * @throws ClassCastException if the type of the specified element
-     *         is incompatible with this list (optional)
+     *         is incompatible with this list
+     *         (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         list does not permit null elements (optional)
+     *         list does not permit null elements
+     *         (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     int indexOf(Object o);
 
@@ -510,9 +523,11 @@ public interface List<E> extends Collection<E> {
      * @return the index of the last occurrence of the specified element in
      *         this list, or -1 if this list does not contain the element
      * @throws ClassCastException if the type of the specified element
-     *         is incompatible with this list (optional)
+     *         is incompatible with this list
+     *         (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         list does not permit null elements (optional)
+     *         list does not permit null elements
+     *         (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     int lastIndexOf(Object o);
 

jdk/src/share/classes/java/util/Map.java

@@ -144,9 +144,11 @@ public interface Map<K,V> {
      * @return <tt>true</tt> if this map contains a mapping for the specified
      *         key
      * @throws ClassCastException if the key is of an inappropriate type for
-     *         this map (optional)
+     *         this map
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified key is null and this map
-     *         does not permit null keys (optional)
+     *         does not permit null keys
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     boolean containsKey(Object key);
 
@@ -162,9 +164,11 @@ public interface Map<K,V> {
      * @return <tt>true</tt> if this map maps one or more keys to the
      *         specified value
      * @throws ClassCastException if the value is of an inappropriate type for
-     *         this map (optional)
+     *         this map
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified value is null and this
-     *         map does not permit null values (optional)
+     *         map does not permit null values
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     boolean containsValue(Object value);
 
@@ -187,9 +191,11 @@ public interface Map<K,V> {
      * @return the value to which the specified key is mapped, or
      *         {@code null} if this map contains no mapping for the key
      * @throws ClassCastException if the key is of an inappropriate type for
-     *         this map (optional)
+     *         this map
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified key is null and this map
-     *         does not permit null keys (optional)
+     *         does not permit null keys
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     V get(Object key);
 
@@ -245,9 +251,11 @@ public interface Map<K,V> {
      * @throws UnsupportedOperationException if the <tt>remove</tt> operation
      *         is not supported by this map
      * @throws ClassCastException if the key is of an inappropriate type for
-     *         this map (optional)
+     *         this map
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified key is null and this
-     *         map does not permit null keys (optional)
+     *         map does not permit null keys
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     V remove(Object key);
 
@@ -466,4 +474,5 @@ public interface Map<K,V> {
      * @see #equals(Object)
      */
     int hashCode();
+
 }

jdk/src/share/classes/java/util/Set.java

@@ -110,9 +110,11 @@ public interface Set<E> extends Collection<E> {
      * @param o element whose presence in this set is to be tested
      * @return <tt>true</tt> if this set contains the specified element
      * @throws ClassCastException if the type of the specified element
-     *         is incompatible with this set (optional)
+     *         is incompatible with this set
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         set does not permit null elements (optional)
+     *         set does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      */
     boolean contains(Object o);
 
@@ -236,9 +238,11 @@ public interface Set<E> extends Collection<E> {
      * @param o object to be removed from this set, if present
      * @return <tt>true</tt> if this set contained the specified element
      * @throws ClassCastException if the type of the specified element
-     *         is incompatible with this set (optional)
+     *         is incompatible with this set
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified element is null and this
-     *         set does not permit null elements (optional)
+     *         set does not permit null elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws UnsupportedOperationException if the <tt>remove</tt> operation
      *         is not supported by this set
      */
@@ -257,10 +261,13 @@ public interface Set<E> extends Collection<E> {
      *         specified collection
      * @throws ClassCastException if the types of one or more elements
      *         in the specified collection are incompatible with this
-     *         set (optional)
+     *         set
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if the specified collection contains one
      *         or more null elements and this set does not permit null
-     *         elements (optional), or if the specified collection is null
+     *         elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>),
+     *         or if the specified collection is null
      * @see    #contains(Object)
      */
     boolean containsAll(Collection<?> c);
@@ -302,9 +309,11 @@ public interface Set<E> extends Collection<E> {
      * @throws UnsupportedOperationException if the <tt>retainAll</tt> operation
      *         is not supported by this set
      * @throws ClassCastException if the class of an element of this set
-     *         is incompatible with the specified collection (optional)
+     *         is incompatible with the specified collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this set contains a null element and the
-     *         specified collection does not permit null elements (optional),
+     *         specified collection does not permit null elements
+     *         (<a href="Collection.html#optional-restrictions">optional</a>),
      *         or if the specified collection is null
      * @see #remove(Object)
      */
@@ -322,9 +331,11 @@ public interface Set<E> extends Collection<E> {
      * @throws UnsupportedOperationException if the <tt>removeAll</tt> operation
      *         is not supported by this set
      * @throws ClassCastException if the class of an element of this set
-     *         is incompatible with the specified collection (optional)
+     *         is incompatible with the specified collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this set contains a null element and the
-     *         specified collection does not permit null elements (optional),
+     *         specified collection does not permit null elements
+     *         (<a href="Collection.html#optional-restrictions">optional</a>),
      *         or if the specified collection is null
      * @see #remove(Object)
      * @see #contains(Object)

jdk/src/share/classes/java/util/Vector.java

@@ -893,10 +893,13 @@ public class Vector<E>
      * @return true if this Vector changed as a result of the call
      * @throws ClassCastException if the types of one or more elements
      *         in this vector are incompatible with the specified
-     *         collection (optional)
+     *         collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this vector contains one or more null
      *         elements and the specified collection does not support null
-     *         elements (optional), or if the specified collection is null
+     *         elements
+     * (<a href="Collection.html#optional-restrictions">optional</a>),
+     *         or if the specified collection is null
      * @since 1.2
      */
     public synchronized boolean removeAll(Collection<?> c) {
@@ -913,10 +916,13 @@ public class Vector<E>
      * @return true if this Vector changed as a result of the call
      * @throws ClassCastException if the types of one or more elements
      *         in this vector are incompatible with the specified
-     *         collection (optional)
+     *         collection
+     * (<a href="Collection.html#optional-restrictions">optional</a>)
      * @throws NullPointerException if this vector contains one or more null
      *         elements and the specified collection does not support null
-     *         elements (optional), or if the specified collection is null
+     *         elements
+     *         (<a href="Collection.html#optional-restrictions">optional</a>),
+     *         or if the specified collection is null
      * @since 1.2
      */
     public synchronized boolean retainAll(Collection<?> c) {