ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.42
Committed: Fri Jun 7 23:56:37 2013 UTC (11 years ago) by dl
Branch: MAIN
Changes since 1.41: +2 -2 lines
Log Message: 
Sync with lambda

File Contents

# User Rev Content
1 dl 1.2 /*
2     * Written by Doug Lea with assistance from members of JCP JSR-166
3 dl 1.17 * Expert Group and released to the public domain, as explained at
4 jsr166 1.31 * http://creativecommons.org/publicdomain/zero/1.0/
5 dl 1.2 */
6    
7 tim 1.1 package java.util.concurrent;
8     import java.util.Map;
9    
10     /**
11 dl 1.42 * A {@link java.util.Map} providing thread safety and atomicity
12     * guarantees.
13 dl 1.19 *
14 jsr166 1.29 * <p>Memory consistency effects: As with other concurrent
15     * collections, actions in a thread prior to placing an object into a
16     * {@code ConcurrentMap} as a key or value
17     * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
18     * actions subsequent to the access or removal of that object from
19     * the {@code ConcurrentMap} in another thread.
20     *
21 dl 1.19 * <p>This interface is a member of the
22 jsr166 1.30 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
23 dl 1.19 * Java Collections Framework</a>.
24 jsr166 1.21 *
25 dl 1.4 * @since 1.5
26     * @author Doug Lea
27 dl 1.13 * @param <K> the type of keys maintained by this map
28 jsr166 1.21 * @param <V> the type of mapped values
29 dl 1.4 */
30 jsr166 1.39 public interface ConcurrentMap<K,V> extends Map<K,V> {
31 dl 1.41
32     /**
33     * {@inheritDoc}
34     *
35     * @implNote This implementation assumes that the ConcurrentMap cannot
36     * contain null values and get() returning null unambiguously means the key
37     * is absent. Implementations which support null values must override this
38     * default implementation.
39     */
40     @Override
41     default V getOrDefault(Object key, V defaultValue) {
42     V v;
43     return ((v = get(key)) != null) ? v : defaultValue;
44     }
45    
46 tim 1.1 /**
47     * If the specified key is not already associated
48     * with a value, associate it with the given value.
49     * This is equivalent to
50 jsr166 1.36 * <pre> {@code
51     * if (!map.containsKey(key))
52     * return map.put(key, value);
53     * else
54     * return map.get(key);}</pre>
55     *
56 jsr166 1.21 * except that the action is performed atomically.
57     *
58 jsr166 1.24 * @param key key with which the specified value is to be associated
59     * @param value value to be associated with the specified key
60 jsr166 1.25 * @return the previous value associated with the specified key, or
61 jsr166 1.38 * {@code null} if there was no mapping for the key.
62     * (A {@code null} return can also indicate that the map
63     * previously associated {@code null} with the key,
64 jsr166 1.25 * if the implementation supports null values.)
65 jsr166 1.38 * @throws UnsupportedOperationException if the {@code put} operation
66 jsr166 1.24 * is not supported by this map
67 tim 1.1 * @throws ClassCastException if the class of the specified key or value
68 jsr166 1.24 * prevents it from being stored in this map
69     * @throws NullPointerException if the specified key or value is null,
70     * and this map does not permit null keys or values
71     * @throws IllegalArgumentException if some property of the specified key
72     * or value prevents it from being stored in this map
73 dl 1.18 */
74 dl 1.4 V putIfAbsent(K key, V value);
75 dl 1.6
76     /**
77 jsr166 1.21 * Removes the entry for a key only if currently mapped to a given value.
78     * This is equivalent to
79 jsr166 1.36 * <pre> {@code
80 dl 1.40 * if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
81 jsr166 1.36 * map.remove(key);
82     * return true;
83     * } else
84     * return false;}</pre>
85     *
86 dl 1.6 * except that the action is performed atomically.
87 jsr166 1.21 *
88 jsr166 1.24 * @param key key with which the specified value is associated
89 jsr166 1.25 * @param value value expected to be associated with the specified key
90 jsr166 1.38 * @return {@code true} if the value was removed
91     * @throws UnsupportedOperationException if the {@code remove} operation
92 jsr166 1.24 * is not supported by this map
93 jsr166 1.25 * @throws ClassCastException if the key or value is of an inappropriate
94 jsr166 1.35 * type for this map
95 dl 1.33 * (<a href="../Collection.html#optional-restrictions">optional</a>)
96 jsr166 1.24 * @throws NullPointerException if the specified key or value is null,
97 dl 1.32 * and this map does not permit null keys or values
98 dl 1.33 * (<a href="../Collection.html#optional-restrictions">optional</a>)
99 dl 1.6 */
100 dl 1.7 boolean remove(Object key, Object value);
101 dl 1.14
102     /**
103 jsr166 1.21 * Replaces the entry for a key only if currently mapped to a given value.
104     * This is equivalent to
105 jsr166 1.36 * <pre> {@code
106 dl 1.40 * if (map.containsKey(key) && Objects.equals(map.get(key), oldValue)) {
107 jsr166 1.36 * map.put(key, newValue);
108     * return true;
109     * } else
110     * return false;}</pre>
111     *
112 dl 1.14 * except that the action is performed atomically.
113 jsr166 1.21 *
114 jsr166 1.24 * @param key key with which the specified value is associated
115     * @param oldValue value expected to be associated with the specified key
116     * @param newValue value to be associated with the specified key
117 jsr166 1.38 * @return {@code true} if the value was replaced
118     * @throws UnsupportedOperationException if the {@code put} operation
119 jsr166 1.24 * is not supported by this map
120 jsr166 1.25 * @throws ClassCastException if the class of a specified key or value
121     * prevents it from being stored in this map
122 jsr166 1.24 * @throws NullPointerException if a specified key or value is null,
123     * and this map does not permit null keys or values
124 jsr166 1.25 * @throws IllegalArgumentException if some property of a specified key
125     * or value prevents it from being stored in this map
126 dl 1.14 */
127     boolean replace(K key, V oldValue, V newValue);
128 dl 1.6
129 dl 1.15 /**
130 jsr166 1.21 * Replaces the entry for a key only if currently mapped to some value.
131     * This is equivalent to
132 jsr166 1.36 * <pre> {@code
133     * if (map.containsKey(key)) {
134     * return map.put(key, value);
135     * } else
136     * return null;}</pre>
137     *
138 dl 1.15 * except that the action is performed atomically.
139 jsr166 1.21 *
140 jsr166 1.24 * @param key key with which the specified value is associated
141     * @param value value to be associated with the specified key
142 jsr166 1.25 * @return the previous value associated with the specified key, or
143 jsr166 1.38 * {@code null} if there was no mapping for the key.
144     * (A {@code null} return can also indicate that the map
145     * previously associated {@code null} with the key,
146 jsr166 1.25 * if the implementation supports null values.)
147 jsr166 1.38 * @throws UnsupportedOperationException if the {@code put} operation
148 jsr166 1.24 * is not supported by this map
149 jsr166 1.25 * @throws ClassCastException if the class of the specified key or value
150     * prevents it from being stored in this map
151 jsr166 1.24 * @throws NullPointerException if the specified key or value is null,
152     * and this map does not permit null keys or values
153 jsr166 1.25 * @throws IllegalArgumentException if some property of the specified key
154     * or value prevents it from being stored in this map
155 dl 1.15 */
156 dl 1.16 V replace(K key, V value);
157 tim 1.1 }