1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * This file is available under and governed by the GNU General Public 27 * License version 2 only, as published by the Free Software Foundation. 28 * However, the following notice accompanied the original version of this 29 * file: 30 * 31 * Written by Doug Lea with assistance from members of JCP JSR-166 32 * Expert Group and released to the public domain, as explained at 33 * http://creativecommons.org/publicdomain/zero/1.0/ 34 */ 35 36 package java.util.concurrent; 37 import java.util.Map; 38 39 /** 40 * A {@link java.util.Map} providing additional atomic 41 * {@code putIfAbsent}, {@code remove}, and {@code replace} methods. 42 * 43 * <p>Memory consistency effects: As with other concurrent 44 * collections, actions in a thread prior to placing an object into a 45 * {@code ConcurrentMap} as a key or value 46 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 47 * actions subsequent to the access or removal of that object from 48 * the {@code ConcurrentMap} in another thread. 49 * 50 * <p>This interface is a member of the 51 * <a href="{@docRoot}/../technotes/guides/collections/index.html"> 52 * Java Collections Framework</a>. 53 * 54 * @since 1.5 55 * @author Doug Lea 56 * @param <K> the type of keys maintained by this map 57 * @param <V> the type of mapped values 58 */ 59 public interface ConcurrentMap<K, V> extends Map<K, V> { 60 61 /** 62 * {@inheritDoc} 63 * 64 * @implNote This implementation assumes that the ConcurrentMap cannot 65 * contain null values and get() returning null unambiguously means the key 66 * is absent. Implementations which support null values must override this 67 * default implementation. 68 */ 69 @Override 70 default V getOrDefault(Object key, V defaultValue) { 71 V v; 72 return ((v = get(key)) != null) ? v : defaultValue; 73 } 74 75 /** 76 * If the specified key is not already associated 77 * with a value, associate it with the given value. 78 * This is equivalent to 79 * <pre> {@code 80 * if (!map.containsKey(key)) 81 * return map.put(key, value); 82 * else 83 * return map.get(key);}</pre> 84 * 85 * except that the action is performed atomically. 86 * 87 * @param key key with which the specified value is to be associated 88 * @param value value to be associated with the specified key 89 * @return the previous value associated with the specified key, or 90 * <tt>null</tt> if there was no mapping for the key. 91 * (A <tt>null</tt> return can also indicate that the map 92 * previously associated <tt>null</tt> with the key, 93 * if the implementation supports null values.) 94 * @throws UnsupportedOperationException if the <tt>put</tt> operation 95 * is not supported by this map 96 * @throws ClassCastException if the class of the specified key or value 97 * prevents it from being stored in this map 98 * @throws NullPointerException if the specified key or value is null, 99 * and this map does not permit null keys or values 100 * @throws IllegalArgumentException if some property of the specified key 101 * or value prevents it from being stored in this map 102 */ 103 V putIfAbsent(K key, V value); 104 105 /** 106 * Removes the entry for a key only if currently mapped to a given value. 107 * This is equivalent to 108 * <pre> {@code 109 * if (map.containsKey(key) && Objects.equals(map.get(key), value)) { 110 * map.remove(key); 111 * return true; 112 * } else 113 * return false;}</pre> 114 * 115 * except that the action is performed atomically. 116 * 117 * @param key key with which the specified value is associated 118 * @param value value expected to be associated with the specified key 119 * @return {@code true} if the value was removed 120 * @throws UnsupportedOperationException if the {@code remove} operation 121 * is not supported by this map 122 * @throws ClassCastException if the key or value is of an inappropriate 123 * type for this map 124 * (<a href="../Collection.html#optional-restrictions">optional</a>) 125 * @throws NullPointerException if the specified key or value is null, 126 * and this map does not permit null keys or values 127 * (<a href="../Collection.html#optional-restrictions">optional</a>) 128 */ 129 boolean remove(Object key, Object value); 130 131 /** 132 * Replaces the entry for a key only if currently mapped to a given value. 133 * This is equivalent to 134 * <pre> {@code 135 * if (map.containsKey(key) && Objects.equals(map.get(key), oldValue)) { 136 * map.put(key, newValue); 137 * return true; 138 * } else 139 * return false;}</pre> 140 * 141 * except that the action is performed atomically. 142 * 143 * @param key key with which the specified value is associated 144 * @param oldValue value expected to be associated with the specified key 145 * @param newValue value to be associated with the specified key 146 * @return {@code true} if the value was replaced 147 * @throws UnsupportedOperationException if the {@code put} operation 148 * is not supported by this map 149 * @throws ClassCastException if the class of a specified key or value 150 * prevents it from being stored in this map 151 * @throws NullPointerException if a specified key or value is null, 152 * and this map does not permit null keys or values 153 * @throws IllegalArgumentException if some property of a specified key 154 * or value prevents it from being stored in this map 155 */ 156 boolean replace(K key, V oldValue, V newValue); 157 158 /** 159 * Replaces the entry for a key only if currently mapped to some value. 160 * This is equivalent to 161 * <pre> {@code 162 * if (map.containsKey(key)) { 163 * return map.put(key, value); 164 * } else 165 * return null;}</pre> 166 * 167 * except that the action is performed atomically. 168 * 169 * @param key key with which the specified value is associated 170 * @param value value to be associated with the specified key 171 * @return the previous value associated with the specified key, or 172 * {@code null} if there was no mapping for the key. 173 * (A {@code null} return can also indicate that the map 174 * previously associated {@code null} with the key, 175 * if the implementation supports null values.) 176 * @throws UnsupportedOperationException if the {@code put} operation 177 * is not supported by this map 178 * @throws ClassCastException if the class of the specified key or value 179 * prevents it from being stored in this map 180 * @throws NullPointerException if the specified key or value is null, 181 * and this map does not permit null keys or values 182 * @throws IllegalArgumentException if some property of the specified key 183 * or value prevents it from being stored in this map 184 */ 185 V replace(K key, V value); 186 }