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