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.
@implSpec
The final implementation is equivalent to, for this {@code
map}:
<pre> {@code
V v = map.get(key);
if (v is null)
v = map.put(key, value);
return v;
}</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 to be 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 key or value is of an inappropriate
type for 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
(<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
@throws IllegalArgumentException if some property 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>)
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.
@implSpec The final implementation is equivalent to, for this {@code map}:
<pre> {@code V v = map.get(key); if (v is null) v = map.put(key, value);
return v; }</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 to be 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 key or value is of an inappropriate type for 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 (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>) @throws IllegalArgumentException if some property 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>)