The final implementation does not throw NullPointerException
for maps that do not support null values if oldValue is null unless
newValue is also null.
<p>The final implementation makes no guarantees about synchronization
or atomicity properties of this method. Any implementation providing
atomicity guarantees must override this method and document its
concurrency properties.
@param key key with which the specified value is associated
@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
(<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
@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,
and this map does not permit null keys or values
@throws NullPointerException if oldValue is null and this map does not
permit null values
(<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
@throws IllegalArgumentException if some property of a specified key
or value prevents it from being stored in this map
Replaces the entry for the specified key only if currently mapped to the specified value.
@implSpec The final implementation is equivalent to, for this {@code map}:
<pre> {@code if (map.containsKey(key) && Objects.equals(map.get(key), value)) { map.put(key, newValue); return true; } else return false; }</pre>
The final implementation does not throw NullPointerException for maps that do not support null values if oldValue is null unless newValue is also null.
<p>The final implementation makes no guarantees about synchronization or atomicity properties of this method. Any implementation providing atomicity guarantees must override this method and document its concurrency properties.
@param key key with which the specified value is associated @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 (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) @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, and this map does not permit null keys or values @throws NullPointerException if oldValue is null and this map does not permit null values (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) @throws IllegalArgumentException if some property of a specified key or value prevents it from being stored in this map