Source for java.util.concurrent.ConcurrentMap

   1: /*
   2:  * Written by Doug Lea with assistance from members of JCP JSR-166
   3:  * Expert Group and released to the public domain, as explained at
   4:  * http://creativecommons.org/licenses/publicdomain
   5:  */
   6: 
   7: package java.util.concurrent;
   8: import java.util.Map;
   9: 
  10: /**
  11:  * A {@link java.util.Map} providing additional atomic
  12:  * <tt>putIfAbsent</tt>, <tt>remove</tt>, and <tt>replace</tt> methods.
  13:  *
  14:  * <p>Memory consistency effects: As with other concurrent
  15:  * collections, actions in a thread prior to placing an object into a
  16:  * {@code ConcurrentMap} as a key or value
  17:  * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
  18:  * actions subsequent to the access or removal of that object from
  19:  * the {@code ConcurrentMap} in another thread.
  20:  *
  21:  * <p>This interface is a member of the
  22:  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  23:  * Java Collections Framework</a>.
  24:  *
  25:  * @since 1.5
  26:  * @author Doug Lea
  27:  * @param <K> the type of keys maintained by this map
  28:  * @param <V> the type of mapped values
  29:  */
  30: public interface ConcurrentMap<K, V> extends Map<K, V> {
  31:     /**
  32:      * If the specified key is not already associated
  33:      * with a value, associate it with the given value.
  34:      * This is equivalent to
  35:      * <pre>
  36:      *   if (!map.containsKey(key))
  37:      *       return map.put(key, value);
  38:      *   else
  39:      *       return map.get(key);</pre>
  40:      * except that the action is performed atomically.
  41:      *
  42:      * @param key key with which the specified value is to be associated
  43:      * @param value value to be associated with the specified key
  44:      * @return the previous value associated with the specified key, or
  45:      *         <tt>null</tt> if there was no mapping for the key.
  46:      *         (A <tt>null</tt> return can also indicate that the map
  47:      *         previously associated <tt>null</tt> with the key,
  48:      *         if the implementation supports null values.)
  49:      * @throws UnsupportedOperationException if the <tt>put</tt> operation
  50:      *         is not supported by this map
  51:      * @throws ClassCastException if the class of the specified key or value
  52:      *         prevents it from being stored in this map
  53:      * @throws NullPointerException if the specified key or value is null,
  54:      *         and this map does not permit null keys or values
  55:      * @throws IllegalArgumentException if some property of the specified key
  56:      *         or value prevents it from being stored in this map
  57:      *
  58:      */
  59:     V putIfAbsent(K key, V value);
  60: 
  61:     /**
  62:      * Removes the entry for a key only if currently mapped to a given value.
  63:      * This is equivalent to
  64:      * <pre>
  65:      *   if (map.containsKey(key) &amp;&amp; map.get(key).equals(value)) {
  66:      *       map.remove(key);
  67:      *       return true;
  68:      *   } else return false;</pre>
  69:      * except that the action is performed atomically.
  70:      *
  71:      * @param key key with which the specified value is associated
  72:      * @param value value expected to be associated with the specified key
  73:      * @return <tt>true</tt> if the value was removed
  74:      * @throws UnsupportedOperationException if the <tt>remove</tt> operation
  75:      *         is not supported by this map
  76:      * @throws ClassCastException if the key or value is of an inappropriate
  77:      *         type for this map (optional)
  78:      * @throws NullPointerException if the specified key or value is null,
  79:      *         and this map does not permit null keys or values (optional)
  80:      */
  81:     boolean remove(Object key, Object value);
  82: 
  83:     /**
  84:      * Replaces the entry for a key only if currently mapped to a given value.
  85:      * This is equivalent to
  86:      * <pre>
  87:      *   if (map.containsKey(key) &amp;&amp; map.get(key).equals(oldValue)) {
  88:      *       map.put(key, newValue);
  89:      *       return true;
  90:      *   } else return false;</pre>
  91:      * except that the action is performed atomically.
  92:      *
  93:      * @param key key with which the specified value is associated
  94:      * @param oldValue value expected to be associated with the specified key
  95:      * @param newValue value to be associated with the specified key
  96:      * @return <tt>true</tt> if the value was replaced
  97:      * @throws UnsupportedOperationException if the <tt>put</tt> operation
  98:      *         is not supported by this map
  99:      * @throws ClassCastException if the class of a specified key or value
 100:      *         prevents it from being stored in this map
 101:      * @throws NullPointerException if a specified key or value is null,
 102:      *         and this map does not permit null keys or values
 103:      * @throws IllegalArgumentException if some property of a specified key
 104:      *         or value prevents it from being stored in this map
 105:      */
 106:     boolean replace(K key, V oldValue, V newValue);
 107: 
 108:     /**
 109:      * Replaces the entry for a key only if currently mapped to some value.
 110:      * This is equivalent to
 111:      * <pre>
 112:      *   if (map.containsKey(key)) {
 113:      *       return map.put(key, value);
 114:      *   } else return null;</pre>
 115:      * except that the action is performed atomically.
 116:      *
 117:      * @param key key with which the specified value is associated
 118:      * @param value value to be associated with the specified key
 119:      * @return the previous value associated with the specified key, or
 120:      *         <tt>null</tt> if there was no mapping for the key.
 121:      *         (A <tt>null</tt> return can also indicate that the map
 122:      *         previously associated <tt>null</tt> with the key,
 123:      *         if the implementation supports null values.)
 124:      * @throws UnsupportedOperationException if the <tt>put</tt> operation
 125:      *         is not supported by this map
 126:      * @throws ClassCastException if the class of the specified key or value
 127:      *         prevents it from being stored in this map
 128:      * @throws NullPointerException if the specified key or value is null,
 129:      *         and this map does not permit null keys or values
 130:      * @throws IllegalArgumentException if some property of the specified key
 131:      *         or value prevents it from being stored in this map
 132:      */
 133:     V replace(K key, V value);
 134: }