/* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain, as explained at * http://creativecommons.org/licenses/publicdomain */ package java.util.concurrent; import java.util.Map; /** * A {@link java.util.Map} providing additional atomic * putIfAbsent, remove, and replace methods. * *
This interface is a member of the
*
* Java Collections Framework.
*
* @since 1.5
* @author Doug Lea
* @param
* if (!map.containsKey(key))
* return map.put(key, value);
* else
* return map.get(key);
*
* except that the action is performed atomically.
*
* @param key key with which the specified value is to be associated.
* @param value value to be associated with the specified key.
* @return previous value associated with specified key, or null
* if there was no mapping for key. A null return can
* also indicate that the map previously associated null
* with the specified key, if the implementation supports
* null values.
* @throws UnsupportedOperationException if the put operation is
* not supported by this map.
* @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map.
* @throws IllegalArgumentException if some aspect of this key or value
* prevents it from being stored in this map.
* @throws NullPointerException if this map does not permit null
* keys or values, and the specified key or value is null.
*
*/
V putIfAbsent(K key, V value);
/**
* Removes the entry for a key only if currently mapped to a given value.
* This is equivalent to
*
* if (map.containsKey(key) && map.get(key).equals(value)) {
* map.remove(key);
* return true;
* } else return false;
*
* except that the action is performed atomically.
*
* @param key key with which the specified value is associated.
* @param value value associated with the specified key.
* @return true if the value was removed, false otherwise
* @throws UnsupportedOperationException if the remove operation is
* not supported by this map.
* @throws NullPointerException if this map does not permit null
* keys or values, and the specified key or value is null.
*/
boolean remove(Object key, Object value);
/**
* Replaces the entry for a key only if currently mapped to a given value.
* This is equivalent to
*
* if (map.containsKey(key) && map.get(key).equals(oldValue)) {
* map.put(key, newValue);
* return true;
* } else return false;
*
* except that the action is performed atomically.
*
* @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 true if the value was replaced
* @throws UnsupportedOperationException if the put operation is
* not supported by this map.
* @throws NullPointerException if this map does not permit null
* keys or values, and the specified key or value is null.
*/
boolean replace(K key, V oldValue, V newValue);
/**
* Replaces the entry for a key only if currently mapped to some value.
* This is equivalent to
*
* if (map.containsKey(key)) {
* return map.put(key, value);
* } else return null;
*
* except that the action is performed atomically.
*
* @param key key with which the specified value is associated.
* @param value value to be associated with the specified key.
* @return previous value associated with specified key, or null
* if there was no mapping for key. A null return can
* also indicate that the map previously associated null
* with the specified key, if the implementation supports
* null values.
* @throws UnsupportedOperationException if the put operation is
* not supported by this map.
* @throws NullPointerException if this map does not permit null
* keys or values, and the specified key or value is null.
*/
V replace(K key, V value);
}