Mercurial > hg > release > icedtea7-forest-2.0 > jdk
changeset 4277:d5a7ed4e72a4
6546713: link the word (optional) in exception specifications to the text which provides explanation and context.
Reviewed-by: dholmes, dl
| author | mduigou |
|---|---|
| date | Wed, 20 Apr 2011 17:20:00 -0700 |
| parents | 00f3997e6aeb |
| children | 7fd31e477313 f3645b5d6e62 |
| files | src/share/classes/java/util/AbstractSet.java src/share/classes/java/util/ArrayList.java src/share/classes/java/util/Collection.java src/share/classes/java/util/Collections.java src/share/classes/java/util/Deque.java src/share/classes/java/util/List.java src/share/classes/java/util/Map.java src/share/classes/java/util/Set.java src/share/classes/java/util/Vector.java |
| diffstat | 9 files changed, 133 insertions(+), 63 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/util/AbstractSet.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/AbstractSet.java Wed Apr 20 17:20:00 2011 -0700 @@ -156,9 +156,11 @@ * @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)
--- a/src/share/classes/java/util/ArrayList.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/ArrayList.java Wed Apr 20 17:20:00 2011 -0700 @@ -628,9 +628,11 @@ * @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 @@ * @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) */
--- a/src/share/classes/java/util/Collection.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/Collection.java Wed Apr 20 17:20:00 2011 -0700 @@ -60,7 +60,8 @@ * 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 @@ * @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 @@ * @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 @@ * 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 @@ * 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 @@ * 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) */
--- a/src/share/classes/java/util/Collections.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/Collections.java Wed Apr 20 17:20:00 2011 -0700 @@ -3746,9 +3746,10 @@ * @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) {
--- a/src/share/classes/java/util/Deque.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/Deque.java Wed Apr 20 17:20:00 2011 -0700 @@ -351,9 +351,11 @@ * @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 @@ * @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 @@ * @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 @@ * @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);
--- a/src/share/classes/java/util/List.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/List.java Wed Apr 20 17:20:00 2011 -0700 @@ -134,9 +134,11 @@ * @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 @@ * @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 @@ * 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 @@ * @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 @@ * @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 @@ * @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 @@ * @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);
--- a/src/share/classes/java/util/Map.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/Map.java Wed Apr 20 17:20:00 2011 -0700 @@ -144,9 +144,11 @@ * @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 @@ * @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 @@ * @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 @@ * @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 @@ * @see #equals(Object) */ int hashCode(); + }
--- a/src/share/classes/java/util/Set.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/Set.java Wed Apr 20 17:20:00 2011 -0700 @@ -110,9 +110,11 @@ * @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 @@ * @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 @@ * 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 @@ * @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 @@ * @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)
--- a/src/share/classes/java/util/Vector.java Wed Apr 20 16:30:38 2011 -0700 +++ b/src/share/classes/java/util/Vector.java Wed Apr 20 17:20:00 2011 -0700 @@ -893,10 +893,13 @@ * @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 @@ * @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) {