001: /*
002: * Written by Doug Lea with assistance from members of JCP JSR-166
003: * Expert Group and released to the public domain, as explained at
004: * http://creativecommons.org/licenses/publicdomain
005: */
006:
007: package java.util.concurrent;
008:
009: import java.util.Map;
010:
011: /**
012: * A {@link java.util.Map} providing additional atomic
013: * <tt>putIfAbsent</tt>, <tt>remove</tt>, and <tt>replace</tt> methods.
014: *
015: * <p>This interface is a member of the
016: * <a href="{@docRoot}/../guide/collections/index.html">
017: * Java Collections Framework</a>.
018: *
019: * @since 1.5
020: * @author Doug Lea
021: * @param <K> the type of keys maintained by this map
022: * @param <V> the type of mapped values
023: */
024: public interface ConcurrentMap<K, V> extends Map<K, V> {
025: /**
026: * If the specified key is not already associated
027: * with a value, associate it with the given value.
028: * This is equivalent to
029: * <pre>
030: * if (!map.containsKey(key))
031: * return map.put(key, value);
032: * else
033: * return map.get(key);
034: * </pre>
035: * Except that the action is performed atomically.
036: * @param key key with which the specified value is to be associated.
037: * @param value value to be associated with the specified key.
038: * @return previous value associated with specified key, or <tt>null</tt>
039: * if there was no mapping for key. A <tt>null</tt> return can
040: * also indicate that the map previously associated <tt>null</tt>
041: * with the specified key, if the implementation supports
042: * <tt>null</tt> values.
043: *
044: * @throws UnsupportedOperationException if the <tt>put</tt> operation is
045: * not supported by this map.
046: * @throws ClassCastException if the class of the specified key or value
047: * prevents it from being stored in this map.
048: * @throws IllegalArgumentException if some aspect of this key or value
049: * prevents it from being stored in this map.
050: * @throws NullPointerException if this map does not permit <tt>null</tt>
051: * keys or values, and the specified key or value is
052: * <tt>null</tt>.
053: *
054: */
055: V putIfAbsent(K key, V value);
056:
057: /**
058: * Remove entry for key only if currently mapped to given value.
059: * Acts as
060: * <pre>
061: * if ((map.containsKey(key) && map.get(key).equals(value)) {
062: * map.remove(key);
063: * return true;
064: * } else return false;
065: * </pre>
066: * except that the action is performed atomically.
067: * @param key key with which the specified value is associated.
068: * @param value value associated with the specified key.
069: * @return true if the value was removed, false otherwise
070: * @throws NullPointerException if this map does not permit <tt>null</tt>
071: * keys or values, and the specified key or value is
072: * <tt>null</tt>.
073: */
074: boolean remove(Object key, Object value);
075:
076: /**
077: * Replace entry for key only if currently mapped to given value.
078: * Acts as
079: * <pre>
080: * if ((map.containsKey(key) && map.get(key).equals(oldValue)) {
081: * map.put(key, newValue);
082: * return true;
083: * } else return false;
084: * </pre>
085: * except that the action is performed atomically.
086: * @param key key with which the specified value is associated.
087: * @param oldValue value expected to be associated with the specified key.
088: * @param newValue value to be associated with the specified key.
089: * @return true if the value was replaced
090: * @throws NullPointerException if this map does not permit <tt>null</tt>
091: * keys or values, and the specified key or value is
092: * <tt>null</tt>.
093: */
094: boolean replace(K key, V oldValue, V newValue);
095:
096: /**
097: * Replace entry for key only if currently mapped to some value.
098: * Acts as
099: * <pre>
100: * if ((map.containsKey(key)) {
101: * return map.put(key, value);
102: * } else return null;
103: * </pre>
104: * except that the action is performed atomically.
105: * @param key key with which the specified value is associated.
106: * @param value value to be associated with the specified key.
107: * @return previous value associated with specified key, or <tt>null</tt>
108: * if there was no mapping for key. A <tt>null</tt> return can
109: * also indicate that the map previously associated <tt>null</tt>
110: * with the specified key, if the implementation supports
111: * <tt>null</tt> values.
112: * @throws NullPointerException if this map does not permit <tt>null</tt>
113: * keys or values, and the specified key or value is
114: * <tt>null</tt>.
115: */
116: V replace(K key, V value);
117:
118: }
|