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/publicdomain/zero/1.0/ 5 */ 6 7package java.util.concurrent; 8import java.util.Map; 9 10// BEGIN android-note 11// removed link to collections framework docs 12// END android-note 13 14/** 15 * A {@link java.util.Map} providing additional atomic 16 * {@code putIfAbsent}, {@code remove}, and {@code replace} methods. 17 * 18 * <p>Memory consistency effects: As with other concurrent 19 * collections, actions in a thread prior to placing an object into a 20 * {@code ConcurrentMap} as a key or value 21 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 22 * actions subsequent to the access or removal of that object from 23 * the {@code ConcurrentMap} in another thread. 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 */ 30public 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> {@code 36 * if (!map.containsKey(key)) 37 * return map.put(key, value); 38 * else 39 * return map.get(key);}</pre> 40 * 41 * except that the action is performed atomically. 42 * 43 * @param key key with which the specified value is to be associated 44 * @param value value to be associated with the specified key 45 * @return the previous value associated with the specified key, or 46 * {@code null} if there was no mapping for the key. 47 * (A {@code null} return can also indicate that the map 48 * previously associated {@code null} with the key, 49 * if the implementation supports null values.) 50 * @throws UnsupportedOperationException if the {@code put} operation 51 * is not supported by this map 52 * @throws ClassCastException if the class of the specified key or value 53 * prevents it from being stored in this map 54 * @throws NullPointerException if the specified key or value is null, 55 * and this map does not permit null keys or values 56 * @throws IllegalArgumentException if some property of the specified key 57 * or value prevents it from being stored in this map 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> {@code 65 * if (map.containsKey(key) && map.get(key).equals(value)) { 66 * map.remove(key); 67 * return true; 68 * } else 69 * return false;}</pre> 70 * 71 * except that the action is performed atomically. 72 * 73 * @param key key with which the specified value is associated 74 * @param value value expected to be associated with the specified key 75 * @return {@code true} if the value was removed 76 * @throws UnsupportedOperationException if the {@code remove} operation 77 * is not supported by this map 78 * @throws ClassCastException if the key or value is of an inappropriate 79 * type for this map 80 * (<a href="../Collection.html#optional-restrictions">optional</a>) 81 * @throws NullPointerException if the specified key or value is null, 82 * and this map does not permit null keys or values 83 * (<a href="../Collection.html#optional-restrictions">optional</a>) 84 */ 85 boolean remove(Object key, Object value); 86 87 /** 88 * Replaces the entry for a key only if currently mapped to a given value. 89 * This is equivalent to 90 * <pre> {@code 91 * if (map.containsKey(key) && map.get(key).equals(oldValue)) { 92 * map.put(key, newValue); 93 * return true; 94 * } else 95 * return false;}</pre> 96 * 97 * except that the action is performed atomically. 98 * 99 * @param key key with which the specified value is associated 100 * @param oldValue value expected to be associated with the specified key 101 * @param newValue value to be associated with the specified key 102 * @return {@code true} if the value was replaced 103 * @throws UnsupportedOperationException if the {@code put} operation 104 * is not supported by this map 105 * @throws ClassCastException if the class of a specified key or value 106 * prevents it from being stored in this map 107 * @throws NullPointerException if a specified key or value is null, 108 * and this map does not permit null keys or values 109 * @throws IllegalArgumentException if some property of a specified key 110 * or value prevents it from being stored in this map 111 */ 112 boolean replace(K key, V oldValue, V newValue); 113 114 /** 115 * Replaces the entry for a key only if currently mapped to some value. 116 * This is equivalent to 117 * <pre> {@code 118 * if (map.containsKey(key)) { 119 * return map.put(key, value); 120 * } else 121 * return null;}</pre> 122 * 123 * except that the action is performed atomically. 124 * 125 * @param key key with which the specified value is associated 126 * @param value value to be associated with the specified key 127 * @return the previous value associated with the specified key, or 128 * {@code null} if there was no mapping for the key. 129 * (A {@code null} return can also indicate that the map 130 * previously associated {@code null} with the key, 131 * if the implementation supports null values.) 132 * @throws UnsupportedOperationException if the {@code put} operation 133 * is not supported by this map 134 * @throws ClassCastException if the class of the specified key or value 135 * prevents it from being stored in this map 136 * @throws NullPointerException if the specified key or value is null, 137 * and this map does not permit null keys or values 138 * @throws IllegalArgumentException if some property of the specified key 139 * or value prevents it from being stored in this map 140 */ 141 V replace(K key, V value); 142} 143