1f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project/* 2f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * Written by Doug Lea with assistance from members of JCP JSR-166 3f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * Expert Group and released to the public domain, as explained at 4f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * http://creativecommons.org/licenses/publicdomain 5f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project */ 6f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project 7f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Projectpackage java.util.concurrent; 8f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Projectimport java.util.Map; 9f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project 10f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project// BEGIN android-note 11f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project// removed link to collections framework docs 12f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project// END android-note 13f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project 14f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project/** 15f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * A {@link java.util.Map} providing additional atomic 16f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * <tt>putIfAbsent</tt>, <tt>remove</tt>, and <tt>replace</tt> methods. 17f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * 188210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * <p>Memory consistency effects: As with other concurrent 198210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * collections, actions in a thread prior to placing an object into a 208210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * {@code ConcurrentMap} as a key or value 218210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 228210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * actions subsequent to the access or removal of that object from 238210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * the {@code ConcurrentMap} in another thread. 248210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * 25f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * @since 1.5 26f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * @author Doug Lea 27f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * @param <K> the type of keys maintained by this map 288210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param <V> the type of mapped values 29f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project */ 30f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Projectpublic interface ConcurrentMap<K, V> extends Map<K, V> { 31f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project /** 32f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * If the specified key is not already associated 33f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * with a value, associate it with the given value. 34f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * This is equivalent to 35f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * <pre> 368210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * if (!map.containsKey(key)) 378210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * return map.put(key, value); 38f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * else 398210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * return map.get(key);</pre> 408210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * except that the action is performed atomically. 41f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * 428210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param key key with which the specified value is to be associated 438210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param value value to be associated with the specified key 448210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @return the previous value associated with the specified key, or 458210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * <tt>null</tt> if there was no mapping for the key. 468210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * (A <tt>null</tt> return can also indicate that the map 478210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * previously associated <tt>null</tt> with the key, 488210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * if the implementation supports null values.) 498210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws UnsupportedOperationException if the <tt>put</tt> operation 508210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * is not supported by this map 51f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * @throws ClassCastException if the class of the specified key or value 528210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * prevents it from being stored in this map 538210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws NullPointerException if the specified key or value is null, 548210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * and this map does not permit null keys or values 558210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws IllegalArgumentException if some property of the specified key 568210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * or value prevents it from being stored in this map 57f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * 58f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project */ 59f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project V putIfAbsent(K key, V value); 60f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project 61f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project /** 628210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * Removes the entry for a key only if currently mapped to a given value. 638210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * This is equivalent to 648210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * <pre> 658210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * if (map.containsKey(key) && map.get(key).equals(value)) { 668210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * map.remove(key); 678210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * return true; 688210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * } else return false;</pre> 69f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * except that the action is performed atomically. 708210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * 718210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param key key with which the specified value is associated 728210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param value value expected to be associated with the specified key 738210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @return <tt>true</tt> if the value was removed 748210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws UnsupportedOperationException if the <tt>remove</tt> operation 758210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * is not supported by this map 768210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws ClassCastException if the key or value is of an inappropriate 778210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * type for this map (optional) 788210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws NullPointerException if the specified key or value is null, 798210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * and this map does not permit null keys or values (optional) 80f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project */ 81f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project boolean remove(Object key, Object value); 82f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project 83f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project /** 848210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * Replaces the entry for a key only if currently mapped to a given value. 858210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * This is equivalent to 868210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * <pre> 878210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * if (map.containsKey(key) && map.get(key).equals(oldValue)) { 888210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * map.put(key, newValue); 898210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * return true; 908210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * } else return false;</pre> 91f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * except that the action is performed atomically. 928210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * 938210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param key key with which the specified value is associated 948210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param oldValue value expected to be associated with the specified key 958210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param newValue value to be associated with the specified key 968210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @return <tt>true</tt> if the value was replaced 978210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws UnsupportedOperationException if the <tt>put</tt> operation 988210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * is not supported by this map 998210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws ClassCastException if the class of a specified key or value 1008210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * prevents it from being stored in this map 1018210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws NullPointerException if a specified key or value is null, 1028210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * and this map does not permit null keys or values 1038210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws IllegalArgumentException if some property of a specified key 1048210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * or value prevents it from being stored in this map 105f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project */ 106f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project boolean replace(K key, V oldValue, V newValue); 107f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project 108f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project /** 1098210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * Replaces the entry for a key only if currently mapped to some value. 1108210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * This is equivalent to 1118210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * <pre> 1128210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * if (map.containsKey(key)) { 1138210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * return map.put(key, value); 1148210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * } else return null;</pre> 115f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project * except that the action is performed atomically. 1168210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * 1178210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param key key with which the specified value is associated 1188210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @param value value to be associated with the specified key 1198210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @return the previous value associated with the specified key, or 1208210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * <tt>null</tt> if there was no mapping for the key. 1218210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * (A <tt>null</tt> return can also indicate that the map 1228210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * previously associated <tt>null</tt> with the key, 1238210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * if the implementation supports null values.) 1248210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws UnsupportedOperationException if the <tt>put</tt> operation 1258210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * is not supported by this map 1268210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws ClassCastException if the class of the specified key or value 1278210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * prevents it from being stored in this map 1288210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws NullPointerException if the specified key or value is null, 1298210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * and this map does not permit null keys or values 1308210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * @throws IllegalArgumentException if some property of the specified key 1318210fadf25ece2a0db4cd0428d7f27d7166310b9Jesse Wilson * or value prevents it from being stored in this map 132f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project */ 133f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project V replace(K key, V value); 134f6c387128427e121477c1b32ad35cdcaa5101ba3The Android Open Source Project} 135