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