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 * <tt>putIfAbsent</tt>, <tt>remove</tt>, and <tt>replace</tt> 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 * If the specified key is not already associated
62 * with a value, associate it with the given value.
63 * This is equivalent to
64 * <pre> {@code
65 * if (!map.containsKey(key))
66 * return map.put(key, value);
67 * else
68 * return map.get(key);}</pre>
69 *
70 * except that the action is performed atomically.
71 *
72 * @param key key with which the specified value is to be associated
73 * @param value value to be associated with the specified key
74 * @return the previous value associated with the specified key, or
75 * <tt>null</tt> if there was no mapping for the key.
76 * (A <tt>null</tt> return can also indicate that the map
77 * previously associated <tt>null</tt> with the key,
78 * if the implementation supports null values.)
79 * @throws UnsupportedOperationException if the <tt>put</tt> operation
80 * is not supported by this map
81 * @throws ClassCastException if the class of the specified key or value
82 * prevents it from being stored in this map
83 * @throws NullPointerException if the specified key or value is null,
84 * and this map does not permit null keys or values
85 * @throws IllegalArgumentException if some property of the specified key
86 * or value prevents it from being stored in this map
87 */
88 V putIfAbsent(K key, V value);
89
90 /**
91 * Removes the entry for a key only if currently mapped to a given value.
92 * This is equivalent to
93 * <pre> {@code
94 * if (map.containsKey(key) && map.get(key).equals(value)) {
95 * map.remove(key);
96 * return true;
97 * } else
98 * return false;}</pre>
99 *
100 * except that the action is performed atomically.
101 *
102 * @param key key with which the specified value is associated
103 * @param value value expected to be associated with the specified key
104 * @return <tt>true</tt> if the value was removed
105 * @throws UnsupportedOperationException if the <tt>remove</tt> operation
106 * is not supported by this map
107 * @throws ClassCastException if the key or value is of an inappropriate
108 * type for this map
109 * (<a href="../Collection.html#optional-restrictions">optional</a>)
110 * @throws NullPointerException if the specified key or value is null,
111 * and this map does not permit null keys or values
112 * (<a href="../Collection.html#optional-restrictions">optional</a>)
113 */
114 boolean remove(Object key, Object value);
115
116 /**
117 * Replaces the entry for a key only if currently mapped to a given value.
118 * This is equivalent to
119 * <pre> {@code
120 * if (map.containsKey(key) && map.get(key).equals(oldValue)) {
121 * map.put(key, newValue);
122 * return true;
123 * } else
124 * return false;}</pre>
125 *
126 * except that the action is performed atomically.
127 *
128 * @param key key with which the specified value is associated
129 * @param oldValue value expected to be associated with the specified key
130 * @param newValue value to be associated with the specified key
131 * @return <tt>true</tt> if the value was replaced
132 * @throws UnsupportedOperationException if the <tt>put</tt> operation
133 * is not supported by this map
134 * @throws ClassCastException if the class of a specified key or value
135 * prevents it from being stored in this map
136 * @throws NullPointerException if a specified key or value is null,
137 * and this map does not permit null keys or values
138 * @throws IllegalArgumentException if some property of a specified key
139 * or value prevents it from being stored in this map
140 */
141 boolean replace(K key, V oldValue, V newValue);
142
143 /**
144 * Replaces the entry for a key only if currently mapped to some value.
145 * This is equivalent to
146 * <pre> {@code
147 * if (map.containsKey(key)) {
148 * return map.put(key, value);
149 * } else
150 * return null;}</pre>
151 *
152 * except that the action is performed atomically.
153 *
154 * @param key key with which the specified value is associated
155 * @param value value to be associated with the specified key
156 * @return the previous value associated with the specified key, or
157 * <tt>null</tt> if there was no mapping for the key.
158 * (A <tt>null</tt> return can also indicate that the map
159 * previously associated <tt>null</tt> with the key,
160 * if the implementation supports null values.)
161 * @throws UnsupportedOperationException if the <tt>put</tt> operation
162 * is not supported by this map
163 * @throws ClassCastException if the class of the specified key or value
164 * prevents it from being stored in this map
165 * @throws NullPointerException if the specified key or value is null,
166 * and this map does not permit null keys or values
167 * @throws IllegalArgumentException if some property of the specified key
168 * or value prevents it from being stored in this map
169 */
170 V replace(K key, V value);
171 }
|
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 }
|