stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8159527: Collections mutator methods should all be marked as optional operations

Browse Source 
Reviewed-by: naoto, bpb
This commit is contained in:
Stuart Marks 2023-08-04 19:27:56 +00:00
parent 873d117932
commit b2add96c35
5 changed files with 62 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/java.base/share/classes/java/util/Collection.java
View File

@ -537,7 +537,7 @@ public interface Collection<E> extends Iterable<E> {
* @param c collection containing elements to be removed from this collection * @param c collection containing elements to be removed from this collection
* @return {@code true} if this collection changed as a result of the * @return {@code true} if this collection changed as a result of the
* call * call
* @throws UnsupportedOperationException if the {@code removeAll} method * @throws UnsupportedOperationException if the {@code removeAll} operation
* is not supported by this collection * is not supported by this collection
* @throws ClassCastException if the types of one or more elements * @throws ClassCastException if the types of one or more elements
* in this collection are incompatible with the specified * in this collection are incompatible with the specified
@ -555,8 +555,8 @@ public interface Collection<E> extends Iterable<E> {
/** /**
* Removes all of the elements of this collection that satisfy the given * Removes all of the elements of this collection that satisfy the given
* predicate. Errors or runtime exceptions thrown during iteration or by * predicate (optional operation). Errors or runtime exceptions thrown during
* the predicate are relayed to the caller. * iteration or by the predicate are relayed to the caller.
* *
* @implSpec * @implSpec
* The default implementation traverses all elements of the collection using * The default implementation traverses all elements of the collection using
@ -569,10 +569,8 @@ public interface Collection<E> extends Iterable<E> {
* removed * removed
* @return {@code true} if any elements were removed * @return {@code true} if any elements were removed
* @throws NullPointerException if the specified filter is null * @throws NullPointerException if the specified filter is null
* @throws UnsupportedOperationException if elements cannot be removed * @throws UnsupportedOperationException if the {@code removeIf} operation
* from this collection. Implementations may throw this exception if a * is not supported by this collection
* matching element cannot be removed or if, in general, removal is not
* supported.
* @since 1.8 * @since 1.8
*/ */
default boolean removeIf(Predicate<? super E> filter) { default boolean removeIf(Predicate<? super E> filter) {

18
src/java.base/share/classes/java/util/List.java
View File

@ -409,8 +409,8 @@ public interface List<E> extends SequencedCollection<E> {
/** /**
* Replaces each element of this list with the result of applying the * Replaces each element of this list with the result of applying the
* operator to that element. Errors or runtime exceptions thrown by * operator to that element (optional operation). Errors or runtime
* the operator are relayed to the caller. * exceptions thrown by the operator are relayed to the caller.
* *
* @implSpec * @implSpec
* The default implementation is equivalent to, for this {@code list}: * The default implementation is equivalent to, for this {@code list}:
@ -426,10 +426,8 @@ public interface List<E> extends SequencedCollection<E> {
* replacing the first element. * replacing the first element.
* *
* @param operator the operator to apply to each element * @param operator the operator to apply to each element
* @throws UnsupportedOperationException if this list is unmodifiable. * @throws UnsupportedOperationException if the {@code replaceAll} operation
* Implementations may throw this exception if an element * is not supported by this list
* cannot be replaced or if, in general, modification is not
* supported
* @throws NullPointerException if the specified operator is null or * @throws NullPointerException if the specified operator is null or
* if the operator result is a null value and this list does * if the operator result is a null value and this list does
* not permit null elements * not permit null elements
@ -446,8 +444,8 @@ public interface List<E> extends SequencedCollection<E> {
/** /**
* Sorts this list according to the order induced by the specified * Sorts this list according to the order induced by the specified
* {@link Comparator}. The sort is <i>stable</i>: this method must not * {@link Comparator} (optional operation). The sort is <i>stable</i>:
* reorder equal elements. * this method must not reorder equal elements.
* *
* <p>All elements in this list must be <i>mutually comparable</i> using the * <p>All elements in this list must be <i>mutually comparable</i> using the
* specified comparator (that is, {@code c.compare(e1, e2)} must not throw * specified comparator (that is, {@code c.compare(e1, e2)} must not throw
@ -495,8 +493,8 @@ public interface List<E> extends SequencedCollection<E> {
* {@linkplain Comparable natural ordering} should be used * {@linkplain Comparable natural ordering} should be used
* @throws ClassCastException if the list contains elements that are not * @throws ClassCastException if the list contains elements that are not
* <i>mutually comparable</i> using the specified comparator * <i>mutually comparable</i> using the specified comparator
* @throws UnsupportedOperationException if the list's list-iterator does * @throws UnsupportedOperationException if the {@code sort} operation
* not support the {@code set} operation * is not supported by this list
* @throws IllegalArgumentException * @throws IllegalArgumentException
* (<a href="Collection.html#optional-restrictions">optional</a>) * (<a href="Collection.html#optional-restrictions">optional</a>)
* if the comparator is found to violate the {@link Comparator} * if the comparator is found to violate the {@link Comparator}

63
src/java.base/share/classes/java/util/Map.java
View File

@ -737,8 +737,8 @@ public interface Map<K, V> {
/** /**
* Replaces each entry's value with the result of invoking the given * 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 on that entry until all entries have been processed or the
* function throws an exception. Exceptions thrown by the function are * function throws an exception (optional operation). Exceptions thrown
* relayed to the caller. * by the function are relayed to the caller.
* *
* @implSpec * @implSpec
* <p>The default implementation is equivalent to, for this {@code map}: * <p>The default implementation is equivalent to, for this {@code map}:
@ -753,8 +753,9 @@ public interface Map<K, V> {
* concurrency properties. * concurrency properties.
* *
* @param function the function to apply to each entry * @param function the function to apply to each entry
* @throws UnsupportedOperationException if the {@code set} operation * @throws UnsupportedOperationException if the {@code replaceAll} operation
* is not supported by this map's entry set iterator. * is not supported by this map
* ({@linkplain Collection##optional-restrictions optional})
* @throws ClassCastException if the class of a replacement value * @throws ClassCastException if the class of a replacement value
* prevents it from being stored in this map * prevents it from being stored in this map
* ({@linkplain Collection##optional-restrictions optional}) * ({@linkplain Collection##optional-restrictions optional})
@ -796,7 +797,7 @@ public interface Map<K, V> {
/** /**
* If the specified key is not already associated with a value (or is mapped * 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 * 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 * @implSpec
* The default implementation is equivalent to, for this {@code map}: * The default implementation is equivalent to, for this {@code map}:
@ -821,7 +822,7 @@ public interface Map<K, V> {
* (A {@code null} return can also indicate that the map * (A {@code null} return can also indicate that the map
* previously associated {@code null} with the key, * previously associated {@code null} with the key,
* if the implementation supports null values.) * 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 * is not supported by this map
* ({@linkplain Collection##optional-restrictions optional}) * ({@linkplain Collection##optional-restrictions optional})
* @throws ClassCastException if the key or value is of an inappropriate * @throws ClassCastException if the key or value is of an inappropriate
@ -845,7 +846,7 @@ public interface Map<K, V> {
/** /**
* Removes the entry for the specified key only if it is currently * 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 * @implSpec
* The default implementation is equivalent to, for this {@code map}: * The default implementation is equivalent to, for this {@code map}:
@ -889,7 +890,7 @@ public interface Map<K, V> {
/** /**
* Replaces the entry for the specified key only if currently * Replaces the entry for the specified key only if currently
* mapped to the specified value. * mapped to the specified value (optional operation).
* *
* @implSpec * @implSpec
* The default implementation is equivalent to, for this {@code map}: * The default implementation is equivalent to, for this {@code map}:
@ -915,8 +916,9 @@ public interface Map<K, V> {
* @param oldValue value expected to be associated with the specified key * @param oldValue value expected to be associated with the specified key
* @param newValue value 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 * @return {@code true} if the value was replaced
* @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}) * is not supported by this map
* ({@linkplain Collection##optional-restrictions optional})
* @throws ClassCastException if the class of a specified key or value * @throws ClassCastException if the class of a specified key or value
* prevents it from being stored in this map * prevents it from being stored in this map
* @throws NullPointerException if a specified key or newValue is null, * @throws NullPointerException if a specified key or newValue is null,
@ -939,7 +941,7 @@ public interface Map<K, V> {
/** /**
* Replaces the entry for the specified key only if it is * Replaces the entry for the specified key only if it is
* currently mapped to some value. * currently mapped to some value (optional operation).
* *
* @implSpec * @implSpec
* The default implementation is equivalent to, for this {@code map}: * The default implementation is equivalent to, for this {@code map}:
@ -963,7 +965,7 @@ public interface Map<K, V> {
* (A {@code null} return can also indicate that the map * (A {@code null} return can also indicate that the map
* previously associated {@code null} with the key, * previously associated {@code null} with the key,
* if the implementation supports null values.) * 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 * is not supported by this map
* ({@linkplain Collection##optional-restrictions optional}) * ({@linkplain Collection##optional-restrictions optional})
* @throws ClassCastException if the class of the specified key or value * @throws ClassCastException if the class of the specified key or value
@ -986,7 +988,7 @@ public interface Map<K, V> {
/** /**
* If the specified key is not already associated with a value (or is mapped * 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 * 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).
* *
* <p>If the mapping function returns {@code null}, no mapping is recorded. * <p>If the mapping function returns {@code null}, no mapping is recorded.
* If the mapping function itself throws an (unchecked) exception, the * If the mapping function itself throws an (unchecked) exception, the
@ -1046,9 +1048,8 @@ public interface Map<K, V> {
* @throws NullPointerException if the specified key is null and * @throws NullPointerException if the specified key is null and
* this map does not support null keys, or the mappingFunction * this map does not support null keys, or the mappingFunction
* is null * is null
* @throws UnsupportedOperationException if the {@code put} operation * @throws UnsupportedOperationException if the {@code computeIfAbsent} operation is not
* is not supported by this map * supported by this map ({@linkplain Collection##optional-restrictions optional})
* ({@linkplain Collection##optional-restrictions optional})
* @throws ClassCastException if the class of the specified key or value * @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map * prevents it from being stored in this map
* ({@linkplain Collection##optional-restrictions optional}) * ({@linkplain Collection##optional-restrictions optional})
@ -1074,7 +1075,8 @@ public interface Map<K, V> {
/** /**
* If the value for the specified key is present and non-null, attempts to * 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).
* *
* <p>If the remapping function returns {@code null}, the mapping is removed. * <p>If the remapping function returns {@code null}, the mapping is removed.
* If the remapping function itself throws an (unchecked) exception, the * If the remapping function itself throws an (unchecked) exception, the
@ -1123,9 +1125,8 @@ public interface Map<K, V> {
* @throws NullPointerException if the specified key is null and * @throws NullPointerException if the specified key is null and
* this map does not support null keys, or the * this map does not support null keys, or the
* remappingFunction is null * remappingFunction is null
* @throws UnsupportedOperationException if the {@code put} operation * @throws UnsupportedOperationException if the {@code computeIfPresent} operation is not
* is not supported by this map * supported by this map ({@linkplain Collection##optional-restrictions optional})
* ({@linkplain Collection##optional-restrictions optional})
* @throws ClassCastException if the class of the specified key or value * @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map * prevents it from being stored in this map
* ({@linkplain Collection##optional-restrictions optional}) * ({@linkplain Collection##optional-restrictions optional})
@ -1154,9 +1155,9 @@ public interface Map<K, V> {
/** /**
* Attempts to compute a mapping for the specified key and its current * Attempts to compute a mapping for the specified key and its current
* mapped value (or {@code null} if there is no current mapping). For * mapped value, or {@code null} if there is no current mapping (optional
* example, to either create or append a {@code String} msg to a value * operation). For example, to either create or append a {@code String}
* mapping: * msg to a value mapping:
* *
* <pre> {@code * <pre> {@code
* map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))}</pre> * map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))}</pre>
@ -1209,9 +1210,8 @@ public interface Map<K, V> {
* @throws NullPointerException if the specified key is null and * @throws NullPointerException if the specified key is null and
* this map does not support null keys, or the * this map does not support null keys, or the
* remappingFunction is null * remappingFunction is null
* @throws UnsupportedOperationException if the {@code put} operation * @throws UnsupportedOperationException if the {@code compute} operation is not
* is not supported by this map * supported by this map ({@linkplain Collection##optional-restrictions optional})
({@linkplain Collection##optional-restrictions optional})
* @throws ClassCastException if the class of the specified key or value * @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map * prevents it from being stored in this map
* ({@linkplain Collection##optional-restrictions optional}) * ({@linkplain Collection##optional-restrictions optional})
@ -1245,9 +1245,9 @@ public interface Map<K, V> {
/** /**
* If the specified key is not already associated with a value or is * If the specified key is not already associated with a value or is
* associated with null, associates it with the given non-null value. * associated with null, associates it with the given non-null value (optional
* Otherwise, replaces the associated value with the results of the given * operation). Otherwise, replaces the associated value with the results of
* remapping function, or removes if the result is {@code null}. This * 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. * 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 * For example, to either create or append a {@code String msg} to a
* value mapping: * value mapping:
@ -1304,9 +1304,8 @@ public interface Map<K, V> {
* present * present
* @return the new value associated with the specified key, or null if no * @return the new value associated with the specified key, or null if no
* value is associated with the key * value is associated with the key
* @throws UnsupportedOperationException if the {@code put} operation * @throws UnsupportedOperationException if the {@code merge} operation is not
* is not supported by this map * supported by this map ({@linkplain Collection##optional-restrictions optional})
* ({@linkplain Collection##optional-restrictions optional})
* @throws ClassCastException if the class of the specified key or value * @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map * prevents it from being stored in this map
* ({@linkplain Collection##optional-restrictions optional}) * ({@linkplain Collection##optional-restrictions optional})

12
src/java.base/share/classes/java/util/NavigableMap.java
View File

@ -237,19 +237,27 @@ public interface NavigableMap<K,V> extends SortedMap<K,V> {
/** /**
* Removes and returns a key-value mapping associated with * 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, * @return the removed first entry of this map,
* or {@code null} if this map is empty * or {@code null} if this map is empty
*
* @throws UnsupportedOperationException if the {@code pollFirstEntry}
* operation is not supported by this map
*/ */
Map.Entry<K,V> pollFirstEntry(); Map.Entry<K,V> pollFirstEntry();
/** /**
* Removes and returns a key-value mapping associated with * 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, * @return the removed last entry of this map,
* or {@code null} if this map is empty * or {@code null} if this map is empty
*
* @throws UnsupportedOperationException if the {@code pollLastEntry}
* operation is not supported by this map
*/ */
Map.Entry<K,V> pollLastEntry(); Map.Entry<K,V> pollLastEntry();

10
src/java.base/share/classes/java/util/NavigableSet.java
View File

@ -146,17 +146,23 @@ public interface NavigableSet<E> extends SortedSet<E> {
/** /**
* Retrieves and removes the first (lowest) element, * 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 * @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(); E pollFirst();
/** /**
* Retrieves and removes the last (highest) element, * 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 * @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(); E pollLast();