lib/classpath/external/jsr166/java/util/concurrent/ConcurrentMap.java

   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 }