diff --git a/src/java.base/share/classes/java/util/Collection.java b/src/java.base/share/classes/java/util/Collection.java index 0f63f0b26a4..0253dbc7e1a 100644 --- a/src/java.base/share/classes/java/util/Collection.java +++ b/src/java.base/share/classes/java/util/Collection.java @@ -537,7 +537,7 @@ public interface Collection extends Iterable { * @param c collection containing elements to be removed from this collection * @return {@code true} if this collection changed as a result of the * call - * @throws UnsupportedOperationException if the {@code removeAll} method + * @throws UnsupportedOperationException if the {@code removeAll} 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 @@ -555,8 +555,8 @@ public interface Collection extends Iterable { /** * Removes all of the elements of this collection that satisfy the given - * predicate. Errors or runtime exceptions thrown during iteration or by - * the predicate are relayed to the caller. + * predicate (optional operation). Errors or runtime exceptions thrown during + * iteration or by the predicate are relayed to the caller. * * @implSpec * The default implementation traverses all elements of the collection using @@ -569,10 +569,8 @@ public interface Collection extends Iterable { * removed * @return {@code true} if any elements were removed * @throws NullPointerException if the specified filter is null - * @throws UnsupportedOperationException if elements cannot be removed - * from this collection. Implementations may throw this exception if a - * matching element cannot be removed or if, in general, removal is not - * supported. + * @throws UnsupportedOperationException if the {@code removeIf} operation + * is not supported by this collection * @since 1.8 */ default boolean removeIf(Predicate filter) { diff --git a/src/java.base/share/classes/java/util/List.java b/src/java.base/share/classes/java/util/List.java index 17cf635aa7a..d5565fa7a97 100644 --- a/src/java.base/share/classes/java/util/List.java +++ b/src/java.base/share/classes/java/util/List.java @@ -409,8 +409,8 @@ public interface List extends SequencedCollection { /** * Replaces each element of this list with the result of applying the - * operator to that element. Errors or runtime exceptions thrown by - * the operator are relayed to the caller. + * operator to that element (optional operation). Errors or runtime + * exceptions thrown by the operator are relayed to the caller. * * @implSpec * The default implementation is equivalent to, for this {@code list}: @@ -426,10 +426,8 @@ public interface List extends SequencedCollection { * replacing the first element. * * @param operator the operator to apply to each element - * @throws UnsupportedOperationException if this list is unmodifiable. - * Implementations may throw this exception if an element - * cannot be replaced or if, in general, modification is not - * supported + * @throws UnsupportedOperationException if the {@code replaceAll} operation + * is not supported by this list * @throws NullPointerException if the specified operator is null or * if the operator result is a null value and this list does * not permit null elements @@ -446,8 +444,8 @@ public interface List extends SequencedCollection { /** * Sorts this list according to the order induced by the specified - * {@link Comparator}. The sort is stable: this method must not - * reorder equal elements. + * {@link Comparator} (optional operation). The sort is stable: + * this method must not reorder equal elements. * *

All elements in this list must be mutually comparable using the * specified comparator (that is, {@code c.compare(e1, e2)} must not throw @@ -495,8 +493,8 @@ public interface List extends SequencedCollection { * {@linkplain Comparable natural ordering} should be used * @throws ClassCastException if the list contains elements that are not * mutually comparable using the specified comparator - * @throws UnsupportedOperationException if the list's list-iterator does - * not support the {@code set} operation + * @throws UnsupportedOperationException if the {@code sort} operation + * is not supported by this list * @throws IllegalArgumentException * (optional) * if the comparator is found to violate the {@link Comparator} diff --git a/src/java.base/share/classes/java/util/Map.java b/src/java.base/share/classes/java/util/Map.java index a36b8187106..ea2fd4e1807 100644 --- a/src/java.base/share/classes/java/util/Map.java +++ b/src/java.base/share/classes/java/util/Map.java @@ -737,8 +737,8 @@ public interface Map { /** * Replaces each entry's value with the result of invoking the given * function on that entry until all entries have been processed or the - * function throws an exception. Exceptions thrown by the function are - * relayed to the caller. + * function throws an exception (optional operation). Exceptions thrown + * by the function are relayed to the caller. * * @implSpec *

The default implementation is equivalent to, for this {@code map}: @@ -753,8 +753,9 @@ public interface Map { * concurrency properties. * * @param function the function to apply to each entry - * @throws UnsupportedOperationException if the {@code set} operation - * is not supported by this map's entry set iterator. + * @throws UnsupportedOperationException if the {@code replaceAll} operation + * is not supported by this map + * ({@linkplain Collection##optional-restrictions optional}) * @throws ClassCastException if the class of a replacement value * prevents it from being stored in this map * ({@linkplain Collection##optional-restrictions optional}) @@ -796,7 +797,7 @@ public interface Map { /** * If the specified key is not already associated with a value (or is mapped * to {@code null}) associates it with the given value and returns - * {@code null}, else returns the current value. + * {@code null}, else returns the current value (optional operation). * * @implSpec * The default implementation is equivalent to, for this {@code map}: @@ -821,7 +822,7 @@ public interface Map { * (A {@code null} return can also indicate that the map * previously associated {@code null} with the key, * if the implementation supports null values.) - * @throws UnsupportedOperationException if the {@code put} operation + * @throws UnsupportedOperationException if the {@code putIfAbsent} operation * is not supported by this map * ({@linkplain Collection##optional-restrictions optional}) * @throws ClassCastException if the key or value is of an inappropriate @@ -845,7 +846,7 @@ public interface Map { /** * Removes the entry for the specified key only if it is currently - * mapped to the specified value. + * mapped to the specified value (optional operation). * * @implSpec * The default implementation is equivalent to, for this {@code map}: @@ -889,7 +890,7 @@ public interface Map { /** * Replaces the entry for the specified key only if currently - * mapped to the specified value. + * mapped to the specified value (optional operation). * * @implSpec * The default implementation is equivalent to, for this {@code map}: @@ -915,8 +916,9 @@ public interface Map { * @param oldValue value expected to be associated with the specified key * @param newValue value to be associated with the specified key * @return {@code true} if the value was replaced - * @throws UnsupportedOperationException if the {@code put} operation - * is not supported by this map ({@linkplain Collection##optional-restrictions optional}) + * @throws UnsupportedOperationException if the {@code replace} operation + * is not supported by this map + * ({@linkplain Collection##optional-restrictions optional}) * @throws ClassCastException if the class of a specified key or value * prevents it from being stored in this map * @throws NullPointerException if a specified key or newValue is null, @@ -939,7 +941,7 @@ public interface Map { /** * Replaces the entry for the specified key only if it is - * currently mapped to some value. + * currently mapped to some value (optional operation). * * @implSpec * The default implementation is equivalent to, for this {@code map}: @@ -963,7 +965,7 @@ public interface Map { * (A {@code null} return can also indicate that the map * previously associated {@code null} with the key, * if the implementation supports null values.) - * @throws UnsupportedOperationException if the {@code put} operation + * @throws UnsupportedOperationException if the {@code replace} operation * is not supported by this map * ({@linkplain Collection##optional-restrictions optional}) * @throws ClassCastException if the class of the specified key or value @@ -986,7 +988,7 @@ public interface Map { /** * If the specified key is not already associated with a value (or is mapped * to {@code null}), attempts to compute its value using the given mapping - * function and enters it into this map unless {@code null}. + * function and enters it into this map unless {@code null} (optional operation). * *

If the mapping function returns {@code null}, no mapping is recorded. * If the mapping function itself throws an (unchecked) exception, the @@ -1046,9 +1048,8 @@ public interface Map { * @throws NullPointerException if the specified key is null and * this map does not support null keys, or the mappingFunction * is null - * @throws UnsupportedOperationException if the {@code put} operation - * is not supported by this map - * ({@linkplain Collection##optional-restrictions optional}) + * @throws UnsupportedOperationException if the {@code computeIfAbsent} operation is not + * supported by this map ({@linkplain Collection##optional-restrictions optional}) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map * ({@linkplain Collection##optional-restrictions optional}) @@ -1074,7 +1075,8 @@ public interface Map { /** * If the value for the specified key is present and non-null, attempts to - * compute a new mapping given the key and its current mapped value. + * compute a new mapping given the key and its current mapped value + * (optional operation). * *

If the remapping function returns {@code null}, the mapping is removed. * If the remapping function itself throws an (unchecked) exception, the @@ -1123,9 +1125,8 @@ public interface Map { * @throws NullPointerException if the specified key is null and * this map does not support null keys, or the * remappingFunction is null - * @throws UnsupportedOperationException if the {@code put} operation - * is not supported by this map - * ({@linkplain Collection##optional-restrictions optional}) + * @throws UnsupportedOperationException if the {@code computeIfPresent} operation is not + * supported by this map ({@linkplain Collection##optional-restrictions optional}) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map * ({@linkplain Collection##optional-restrictions optional}) @@ -1154,9 +1155,9 @@ public interface Map { /** * Attempts to compute a mapping for the specified key and its current - * mapped value (or {@code null} if there is no current mapping). For - * example, to either create or append a {@code String} msg to a value - * mapping: + * mapped value, or {@code null} if there is no current mapping (optional + * operation). For example, to either create or append a {@code String} + * msg to a value mapping: * * 

 {@code
      * map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))}
@@ -1209,9 +1210,8 @@ public interface Map { * @throws NullPointerException if the specified key is null and * this map does not support null keys, or the * remappingFunction is null - * @throws UnsupportedOperationException if the {@code put} operation - * is not supported by this map - ({@linkplain Collection##optional-restrictions optional}) + * @throws UnsupportedOperationException if the {@code compute} operation is not + * supported by this map ({@linkplain Collection##optional-restrictions optional}) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map * ({@linkplain Collection##optional-restrictions optional}) @@ -1245,9 +1245,9 @@ public interface Map { /** * If the specified key is not already associated with a value or is - * associated with null, associates it with the given non-null value. - * Otherwise, replaces the associated value with the results of the given - * remapping function, or removes if the result is {@code null}. This + * associated with null, associates it with the given non-null value (optional + * operation). Otherwise, replaces the associated value with the results of + * the given remapping function, or removes if the result is {@code null}. This * method may be of use when combining multiple mapped values for a key. * For example, to either create or append a {@code String msg} to a * value mapping: @@ -1304,9 +1304,8 @@ public interface Map { * present * @return the new value associated with the specified key, or null if no * value is associated with the key - * @throws UnsupportedOperationException if the {@code put} operation - * is not supported by this map - * ({@linkplain Collection##optional-restrictions optional}) + * @throws UnsupportedOperationException if the {@code merge} operation is not + * supported by this map ({@linkplain Collection##optional-restrictions optional}) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map * ({@linkplain Collection##optional-restrictions optional}) diff --git a/src/java.base/share/classes/java/util/NavigableMap.java b/src/java.base/share/classes/java/util/NavigableMap.java index 92abc278dd8..fdd5d3b1245 100644 --- a/src/java.base/share/classes/java/util/NavigableMap.java +++ b/src/java.base/share/classes/java/util/NavigableMap.java @@ -237,19 +237,27 @@ public interface NavigableMap extends SortedMap { /** * Removes and returns a key-value mapping associated with - * the least key in this map, or {@code null} if the map is empty. + * the least key in this map, or {@code null} if the map is empty + * (optional operation). * * @return the removed first entry of this map, * or {@code null} if this map is empty + * + * @throws UnsupportedOperationException if the {@code pollFirstEntry} + * operation is not supported by this map */ Map.Entry pollFirstEntry(); /** * Removes and returns a key-value mapping associated with - * the greatest key in this map, or {@code null} if the map is empty. + * the greatest key in this map, or {@code null} if the map is empty + * (optional operation). * * @return the removed last entry of this map, * or {@code null} if this map is empty + * + * @throws UnsupportedOperationException if the {@code pollLastEntry} + * operation is not supported by this map */ Map.Entry pollLastEntry(); diff --git a/src/java.base/share/classes/java/util/NavigableSet.java b/src/java.base/share/classes/java/util/NavigableSet.java index 8d7da4eddd3..16124acbeff 100644 --- a/src/java.base/share/classes/java/util/NavigableSet.java +++ b/src/java.base/share/classes/java/util/NavigableSet.java @@ -146,17 +146,23 @@ public interface NavigableSet extends SortedSet { /** * Retrieves and removes the first (lowest) element, - * or returns {@code null} if this set is empty. + * or returns {@code null} if this set is empty (optional operation). * * @return the first element, or {@code null} if this set is empty + * + * @throws UnsupportedOperationException if the {@code pollFirst} + * operation is not supported by this collection */ E pollFirst(); /** * Retrieves and removes the last (highest) element, - * or returns {@code null} if this set is empty. + * or returns {@code null} if this set is empty (optional operation). * * @return the last element, or {@code null} if this set is empty + * + * @throws UnsupportedOperationException if the {@code pollLast} + * operation is not supported by this collection */ E pollLast();