ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.39
Committed: Fri Feb 15 22:20:46 2013 UTC (11 years, 3 months ago) by jsr166
Branch: MAIN
Changes since 1.38: +1 -1 lines
Log Message: 
whitespace

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.11 * A {@link java.util.Map} providing additional atomic
12 jsr166 1.38 * {@code putIfAbsent}, {@code remove}, and {@code replace} methods.
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 tim 1.1 /**
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 jsr166 1.36 * <pre> {@code
36     * if (!map.containsKey(key))
37     * return map.put(key, value);
38     * else
39     * return map.get(key);}</pre>
40     *
41 jsr166 1.21 * except that the action is performed atomically.
42     *
43 jsr166 1.24 * @param key key with which the specified value is to be associated
44     * @param value value to be associated with the specified key
45 jsr166 1.25 * @return the previous value associated with the specified key, or
46 jsr166 1.38 * {@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 jsr166 1.25 * if the implementation supports null values.)
50 jsr166 1.38 * @throws UnsupportedOperationException if the {@code put} operation
51 jsr166 1.24 * is not supported by this map
52 tim 1.1 * @throws ClassCastException if the class of the specified key or value
53 jsr166 1.24 * 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 dl 1.18 */
59 dl 1.4 V putIfAbsent(K key, V value);
60 dl 1.6
61     /**
62 jsr166 1.21 * Removes the entry for a key only if currently mapped to a given value.
63     * This is equivalent to
64 jsr166 1.36 * <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 dl 1.6 * except that the action is performed atomically.
72 jsr166 1.21 *
73 jsr166 1.24 * @param key key with which the specified value is associated
74 jsr166 1.25 * @param value value expected to be associated with the specified key
75 jsr166 1.38 * @return {@code true} if the value was removed
76     * @throws UnsupportedOperationException if the {@code remove} operation
77 jsr166 1.24 * is not supported by this map
78 jsr166 1.25 * @throws ClassCastException if the key or value is of an inappropriate
79 jsr166 1.35 * type for this map
80 dl 1.33 * (<a href="../Collection.html#optional-restrictions">optional</a>)
81 jsr166 1.24 * @throws NullPointerException if the specified key or value is null,
82 dl 1.32 * and this map does not permit null keys or values
83 dl 1.33 * (<a href="../Collection.html#optional-restrictions">optional</a>)
84 dl 1.6 */
85 dl 1.7 boolean remove(Object key, Object value);
86 dl 1.14
87     /**
88 jsr166 1.21 * Replaces the entry for a key only if currently mapped to a given value.
89     * This is equivalent to
90 jsr166 1.36 * <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 dl 1.14 * except that the action is performed atomically.
98 jsr166 1.21 *
99 jsr166 1.24 * @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 jsr166 1.38 * @return {@code true} if the value was replaced
103     * @throws UnsupportedOperationException if the {@code put} operation
104 jsr166 1.24 * is not supported by this map
105 jsr166 1.25 * @throws ClassCastException if the class of a specified key or value
106     * prevents it from being stored in this map
107 jsr166 1.24 * @throws NullPointerException if a specified key or value is null,
108     * and this map does not permit null keys or values
109 jsr166 1.25 * @throws IllegalArgumentException if some property of a specified key
110     * or value prevents it from being stored in this map
111 dl 1.14 */
112     boolean replace(K key, V oldValue, V newValue);
113 dl 1.6
114 dl 1.15 /**
115 jsr166 1.21 * Replaces the entry for a key only if currently mapped to some value.
116     * This is equivalent to
117 jsr166 1.36 * <pre> {@code
118     * if (map.containsKey(key)) {
119     * return map.put(key, value);
120     * } else
121     * return null;}</pre>
122     *
123 dl 1.15 * except that the action is performed atomically.
124 jsr166 1.21 *
125 jsr166 1.24 * @param key key with which the specified value is associated
126     * @param value value to be associated with the specified key
127 jsr166 1.25 * @return the previous value associated with the specified key, or
128 jsr166 1.38 * {@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 jsr166 1.25 * if the implementation supports null values.)
132 jsr166 1.38 * @throws UnsupportedOperationException if the {@code put} operation
133 jsr166 1.24 * is not supported by this map
134 jsr166 1.25 * @throws ClassCastException if the class of the specified key or value
135     * prevents it from being stored in this map
136 jsr166 1.24 * @throws NullPointerException if the specified key or value is null,
137     * and this map does not permit null keys or values
138 jsr166 1.25 * @throws IllegalArgumentException if some property of the specified key
139     * or value prevents it from being stored in this map
140 dl 1.15 */
141 dl 1.16 V replace(K key, V value);
142 tim 1.1 }