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 }