Skip to content

Commit

Permalink
8159527: Collections mutator methods should all be marked as optional…
Browse files Browse the repository at this point in the history 
… operations

Reviewed-by: naoto, bpb
  • Loading branch information
Stuart Marks committed Aug 4, 2023
1 parent 873d117 commit b2add96
Show file tree
Hide file tree
Showing 5 changed files with 62 additions and 53 deletions.
12 changes: 5 additions & 7 deletions src/java.base/share/classes/java/util/Collection.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -537,7 +537,7 @@ default <T> T[] toArray(IntFunction<T[]> generator) {
* @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
Expand All @@ -555,8 +555,8 @@ default <T> T[] toArray(IntFunction<T[]> generator) {

/**
* 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
Expand All @@ -569,10 +569,8 @@ default <T> T[] toArray(IntFunction<T[]> generator) {
* 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<? super E> filter) {
Expand Down
18 changes: 8 additions & 10 deletions src/java.base/share/classes/java/util/List.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -409,8 +409,8 @@ public interface List<E> extends SequencedCollection<E> {

/**
* 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}:
Expand All @@ -426,10 +426,8 @@ public interface List<E> extends SequencedCollection<E> {
* 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
Expand All @@ -446,8 +444,8 @@ default void replaceAll(UnaryOperator<E> operator) {

/**
* Sorts this list according to the order induced by the specified
* {@link Comparator}. The sort is <i>stable</i>: this method must not
* reorder equal elements.
* {@link Comparator} (optional operation). The sort is <i>stable</i>:
* this method must not reorder equal elements.
*
* <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
Expand Down Expand Up @@ -495,8 +493,8 @@ default void replaceAll(UnaryOperator<E> operator) {
* {@linkplain Comparable natural ordering} should be used
* @throws ClassCastException if the list contains elements that are not
* <i>mutually comparable</i> 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
* (<a href="Collection.html#optional-restrictions">optional</a>)
* if the comparator is found to violate the {@link Comparator}
Expand Down
63 changes: 31 additions & 32 deletions src/java.base/share/classes/java/util/Map.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -737,8 +737,8 @@ default void forEach(BiConsumer<? super K, ? super V> action) {
/**
* 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
* <p>The default implementation is equivalent to, for this {@code map}:
Expand All @@ -753,8 +753,9 @@ default void forEach(BiConsumer<? super K, ? super V> action) {
* 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})
Expand Down Expand Up @@ -796,7 +797,7 @@ default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function)
/**
* 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}:
Expand All @@ -821,7 +822,7 @@ default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function)
* (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
Expand All @@ -845,7 +846,7 @@ default V putIfAbsent(K key, V value) {

/**
* 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}:
Expand Down Expand Up @@ -889,7 +890,7 @@ default boolean remove(Object key, Object value) {

/**
* 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}:
Expand All @@ -915,8 +916,9 @@ default boolean remove(Object key, Object value) {
* @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,
Expand All @@ -939,7 +941,7 @@ default boolean replace(K key, V oldValue, V newValue) {

/**
* 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}:
Expand All @@ -963,7 +965,7 @@ default boolean replace(K key, V oldValue, V newValue) {
* (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
Expand All @@ -986,7 +988,7 @@ default V replace(K key, V value) {
/**
* 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).
*
* <p>If the mapping function returns {@code null}, no mapping is recorded.
* If the mapping function itself throws an (unchecked) exception, the
Expand Down Expand Up @@ -1046,9 +1048,8 @@ default V replace(K key, V value) {
* @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})
Expand All @@ -1074,7 +1075,8 @@ default V computeIfAbsent(K key,

/**
* 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.
* If the remapping function itself throws an (unchecked) exception, the
Expand Down Expand Up @@ -1123,9 +1125,8 @@ default V computeIfAbsent(K key,
* @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})
Expand Down Expand Up @@ -1154,9 +1155,9 @@ default V computeIfPresent(K key,

/**
* 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:
*
* <pre> {@code
* map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))}</pre>
Expand Down Expand Up @@ -1209,9 +1210,8 @@ default V computeIfPresent(K key,
* @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})
Expand Down Expand Up @@ -1245,9 +1245,9 @@ default V compute(K key,

/**
* 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:
Expand Down Expand Up @@ -1304,9 +1304,8 @@ default V compute(K key,
* 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})
Expand Down
12 changes: 10 additions & 2 deletions src/java.base/share/classes/java/util/NavigableMap.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -237,19 +237,27 @@ public interface NavigableMap<K,V> extends SortedMap<K,V> {

/**
* 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<K,V> 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<K,V> pollLastEntry();

Expand Down
10 changes: 8 additions & 2 deletions src/java.base/share/classes/java/util/NavigableSet.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,17 +146,23 @@ public interface NavigableSet<E> extends SortedSet<E> {

/**
* 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();

Expand Down

1 comment on commit b2add96

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review

Issues

Please sign in to comment.