ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.31
Committed: Tue Mar 15 19:47:03 2011 UTC (13 years, 2 months ago) by jsr166
Branch: MAIN
Changes since 1.30: +1 -1 lines
Log Message: 
Update Creative Commons license URL in legal notices

File Contents

# Content
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
7 package java.util.concurrent;
8 import java.util.Map;
9
10 /**
11 * A {@link java.util.Map} providing additional atomic
12 * <tt>putIfAbsent</tt>, <tt>remove</tt>, and <tt>replace</tt> methods.
13 *
14 * <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 * <p>This interface is a member of the
22 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
23 * Java Collections Framework</a>.
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 */
30 public 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>
36 * if (!map.containsKey(key))
37 * return map.put(key, value);
38 * else
39 * return map.get(key);</pre>
40 * except that the action is performed atomically.
41 *
42 * @param key key with which the specified value is to be associated
43 * @param value value to be associated with the specified key
44 * @return the previous value associated with the specified key, or
45 * <tt>null</tt> if there was no mapping for the key.
46 * (A <tt>null</tt> return can also indicate that the map
47 * previously associated <tt>null</tt> with the key,
48 * if the implementation supports null values.)
49 * @throws UnsupportedOperationException if the <tt>put</tt> operation
50 * is not supported by this map
51 * @throws ClassCastException if the class of the specified key or value
52 * prevents it from being stored in this map
53 * @throws NullPointerException if the specified key or value is null,
54 * and this map does not permit null keys or values
55 * @throws IllegalArgumentException if some property of the specified key
56 * or value prevents it from being stored in this map
57 *
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>
65 * if (map.containsKey(key) &amp;&amp; map.get(key).equals(value)) {
66 * map.remove(key);
67 * return true;
68 * } else return false;</pre>
69 * except that the action is performed atomically.
70 *
71 * @param key key with which the specified value is associated
72 * @param value value expected to be associated with the specified key
73 * @return <tt>true</tt> if the value was removed
74 * @throws UnsupportedOperationException if the <tt>remove</tt> operation
75 * is not supported by this map
76 * @throws ClassCastException if the key or value is of an inappropriate
77 * type for this map (optional)
78 * @throws NullPointerException if the specified key or value is null,
79 * and this map does not permit null keys or values (optional)
80 */
81 boolean remove(Object key, Object value);
82
83 /**
84 * Replaces the entry for a key only if currently mapped to a given value.
85 * This is equivalent to
86 * <pre>
87 * if (map.containsKey(key) &amp;&amp; map.get(key).equals(oldValue)) {
88 * map.put(key, newValue);
89 * return true;
90 * } else return false;</pre>
91 * except that the action is performed atomically.
92 *
93 * @param key key with which the specified value is associated
94 * @param oldValue value expected to be associated with the specified key
95 * @param newValue value to be associated with the specified key
96 * @return <tt>true</tt> if the value was replaced
97 * @throws UnsupportedOperationException if the <tt>put</tt> operation
98 * is not supported by this map
99 * @throws ClassCastException if the class of a specified key or value
100 * prevents it from being stored in this map
101 * @throws NullPointerException if a specified key or value is null,
102 * and this map does not permit null keys or values
103 * @throws IllegalArgumentException if some property of a specified key
104 * or value prevents it from being stored in this map
105 */
106 boolean replace(K key, V oldValue, V newValue);
107
108 /**
109 * Replaces the entry for a key only if currently mapped to some value.
110 * This is equivalent to
111 * <pre>
112 * if (map.containsKey(key)) {
113 * return map.put(key, value);
114 * } else return null;</pre>
115 * except that the action is performed atomically.
116 *
117 * @param key key with which the specified value is associated
118 * @param value value to be associated with the specified key
119 * @return the previous value associated with the specified key, or
120 * <tt>null</tt> if there was no mapping for the key.
121 * (A <tt>null</tt> return can also indicate that the map
122 * previously associated <tt>null</tt> with the key,
123 * if the implementation supports null values.)
124 * @throws UnsupportedOperationException if the <tt>put</tt> operation
125 * is not supported by this map
126 * @throws ClassCastException if the class of the specified key or value
127 * prevents it from being stored in this map
128 * @throws NullPointerException if the specified key or value is null,
129 * and this map does not permit null keys or values
130 * @throws IllegalArgumentException if some property of the specified key
131 * or value prevents it from being stored in this map
132 */
133 V replace(K key, V value);
134 }