ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.27
Committed: Thu Sep 8 00:04:00 2005 UTC (18 years, 8 months ago) by dl
Branch: MAIN
Changes since 1.26: +1 -1 lines
Log Message: 
Edit pass for happens-before descriptions

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/licenses/publicdomain
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>This interface is a member of the
15 * <a href="{@docRoot}/../guide/collections/index.html">
16 * Java Collections Framework</a>.
17 *
18 * <p>
19 * Memory consistency effects: As with other concurrent collections, state
20 * changes to any object made prior to placing it into a <tt>ConcurrentMap</tt> as a key or value
21 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
22 * that element is accessed via or removed from the <tt>ConcurrentMap</tt>.
23 *
24 * @since 1.5
25 * @author Doug Lea
26 * @param <K> the type of keys maintained by this map
27 * @param <V> the type of mapped values
28 */
29 public interface ConcurrentMap<K, V> extends Map<K, V> {
30 /**
31 * If the specified key is not already associated
32 * with a value, associate it with the given value.
33 * This is equivalent to
34 * <pre>
35 * if (!map.containsKey(key))
36 * return map.put(key, value);
37 * else
38 * return map.get(key);</pre>
39 * except that the action is performed atomically.
40 *
41 * @param key key with which the specified value is to be associated
42 * @param value value to be associated with the specified key
43 * @return the previous value associated with the specified key, or
44 * <tt>null</tt> if there was no mapping for the key.
45 * (A <tt>null</tt> return can also indicate that the map
46 * previously associated <tt>null</tt> with the key,
47 * if the implementation supports null values.)
48 * @throws UnsupportedOperationException if the <tt>put</tt> operation
49 * is not supported by this map
50 * @throws ClassCastException if the class of the specified key or value
51 * prevents it from being stored in this map
52 * @throws NullPointerException if the specified key or value is null,
53 * and this map does not permit null keys or values
54 * @throws IllegalArgumentException if some property of the specified key
55 * or value prevents it from being stored in this map
56 *
57 */
58 V putIfAbsent(K key, V value);
59
60 /**
61 * Removes the entry for a key only if currently mapped to a given value.
62 * This is equivalent to
63 * <pre>
64 * if (map.containsKey(key) &amp;&amp; map.get(key).equals(value)) {
65 * map.remove(key);
66 * return true;
67 * } else return false;</pre>
68 * except that the action is performed atomically.
69 *
70 * @param key key with which the specified value is associated
71 * @param value value expected to be associated with the specified key
72 * @return <tt>true</tt> if the value was removed
73 * @throws UnsupportedOperationException if the <tt>remove</tt> operation
74 * is not supported by this map
75 * @throws ClassCastException if the key or value is of an inappropriate
76 * type for this map (optional)
77 * @throws NullPointerException if the specified key or value is null,
78 * and this map does not permit null keys or values (optional)
79 */
80 boolean remove(Object key, Object value);
81
82 /**
83 * Replaces the entry for a key only if currently mapped to a given value.
84 * This is equivalent to
85 * <pre>
86 * if (map.containsKey(key) &amp;&amp; map.get(key).equals(oldValue)) {
87 * map.put(key, newValue);
88 * return true;
89 * } else return false;</pre>
90 * except that the action is performed atomically.
91 *
92 * @param key key with which the specified value is associated
93 * @param oldValue value expected to be associated with the specified key
94 * @param newValue value to be associated with the specified key
95 * @return <tt>true</tt> if the value was replaced
96 * @throws UnsupportedOperationException if the <tt>put</tt> operation
97 * is not supported by this map
98 * @throws ClassCastException if the class of a specified key or value
99 * prevents it from being stored in this map
100 * @throws NullPointerException if a specified key or value is null,
101 * and this map does not permit null keys or values
102 * @throws IllegalArgumentException if some property of a specified key
103 * or value prevents it from being stored in this map
104 */
105 boolean replace(K key, V oldValue, V newValue);
106
107 /**
108 * Replaces the entry for a key only if currently mapped to some value.
109 * This is equivalent to
110 * <pre>
111 * if (map.containsKey(key)) {
112 * return map.put(key, value);
113 * } else return null;</pre>
114 * except that the action is performed atomically.
115 *
116 * @param key key with which the specified value is associated
117 * @param value value to be associated with the specified key
118 * @return the previous value associated with the specified key, or
119 * <tt>null</tt> if there was no mapping for the key.
120 * (A <tt>null</tt> return can also indicate that the map
121 * previously associated <tt>null</tt> with the key,
122 * if the implementation supports null values.)
123 * @throws UnsupportedOperationException if the <tt>put</tt> operation
124 * is not supported by this map
125 * @throws ClassCastException if the class of the specified key or value
126 * prevents it from being stored in this map
127 * @throws NullPointerException if the specified key or value is null,
128 * and this map does not permit null keys or values
129 * @throws IllegalArgumentException if some property of the specified key
130 * or value prevents it from being stored in this map
131 */
132 V replace(K key, V value);
133 }