<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 value value to be associated with the specified key
@return the previous value associated with the specified key, or
{@code null} if there was no mapping for the key.
(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
is not supported by this map
(<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
@throws ClassCastException if the class of the specified key or value
prevents it from being stored in this map
(<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
@throws NullPointerException if the specified key or value is null,
and this map does not permit null keys or values
@throws IllegalArgumentException if some property of the specified key
or value prevents it from being stored in this map
Replaces the entry for the specified key only if it is currently mapped to some value.
@implSpec The final implementation is equivalent to, for this {@code map}:
<pre> {@code if (map.containsKey(key)) { return map.put(key, value); } else return null; }</pre>
<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 value value to be associated with the specified key @return the previous value associated with the specified key, or {@code null} if there was no mapping for the key. (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 is not supported by this map (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) @throws ClassCastException if the class of the specified key or value prevents it from being stored in this map (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) @throws NullPointerException if the specified key or value is null, and this map does not permit null keys or values @throws IllegalArgumentException if some property of the specified key or value prevents it from being stored in this map