ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.21
Committed: Tue Apr 26 01:43:01 2005 UTC (19 years, 1 month ago) by jsr166
Branch: MAIN
Changes since 1.20: +40 -42 lines
Log Message: 
doc fixes

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     * http://creativecommons.org/licenses/publicdomain
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 dl 1.14 * <tt>putIfAbsent</tt>, <tt>remove</tt>, and <tt>replace</tt> methods.
13 dl 1.19 *
14     * <p>This interface is a member of the
15     * <a href="{@docRoot}/../guide/collections/index.html">
16     * Java Collections Framework</a>.
17 jsr166 1.21 *
18 dl 1.4 * @since 1.5
19     * @author Doug Lea
20 dl 1.13 * @param <K> the type of keys maintained by this map
21 jsr166 1.21 * @param <V> the type of mapped values
22 dl 1.4 */
23 tim 1.1 public interface ConcurrentMap<K, V> extends Map<K, V> {
24     /**
25     * If the specified key is not already associated
26     * with a value, associate it with the given value.
27     * This is equivalent to
28     * <pre>
29 jsr166 1.21 * if (!map.containsKey(key))
30     * return map.put(key, value);
31 dl 1.5 * else
32 jsr166 1.21 * return map.get(key);
33 tim 1.1 * </pre>
34 jsr166 1.21 * except that the action is performed atomically.
35     *
36 tim 1.1 * @param key key with which the specified value is to be associated.
37     * @param value value to be associated with the specified key.
38     * @return previous value associated with specified key, or <tt>null</tt>
39     * if there was no mapping for key. A <tt>null</tt> return can
40     * also indicate that the map previously associated <tt>null</tt>
41     * with the specified key, if the implementation supports
42     * <tt>null</tt> values.
43     * @throws UnsupportedOperationException if the <tt>put</tt> operation is
44 jsr166 1.21 * not supported by this map.
45 tim 1.1 * @throws ClassCastException if the class of the specified key or value
46 jsr166 1.21 * prevents it from being stored in this map.
47 tim 1.1 * @throws IllegalArgumentException if some aspect of this key or value
48 jsr166 1.21 * prevents it from being stored in this map.
49 dholmes 1.9 * @throws NullPointerException if this map does not permit <tt>null</tt>
50 jsr166 1.21 * keys or values, and the specified key or value is <tt>null</tt>.
51 tim 1.1 *
52 dl 1.18 */
53 dl 1.4 V putIfAbsent(K key, V value);
54 dl 1.6
55     /**
56 jsr166 1.21 * Removes the entry for a key only if currently mapped to a given value.
57     * This is equivalent to
58     * <pre>
59     * if (map.containsKey(key) && map.get(key).equals(value)) {
60     * map.remove(key);
61     * return true;
62     * } else return false;
63 dl 1.6 * </pre>
64     * except that the action is performed atomically.
65 jsr166 1.21 *
66 dl 1.7 * @param key key with which the specified value is associated.
67     * @param value value associated with the specified key.
68 dl 1.18 * @return true if the value was removed, false otherwise
69 dl 1.20 * @throws UnsupportedOperationException if the <tt>remove</tt> operation is
70 jsr166 1.21 * not supported by this map.
71 dholmes 1.9 * @throws NullPointerException if this map does not permit <tt>null</tt>
72 jsr166 1.21 * keys or values, and the specified key or value is <tt>null</tt>.
73 dl 1.6 */
74 dl 1.7 boolean remove(Object key, Object value);
75 dl 1.14
76     /**
77 jsr166 1.21 * Replaces the entry for a key only if currently mapped to a given value.
78     * This is equivalent to
79     * <pre>
80     * if (map.containsKey(key) && map.get(key).equals(oldValue)) {
81     * map.put(key, newValue);
82     * return true;
83     * } else return false;
84 dl 1.14 * </pre>
85     * except that the action is performed atomically.
86 jsr166 1.21 *
87 dl 1.14 * @param key key with which the specified value is associated.
88     * @param oldValue value expected to be associated with the specified key.
89     * @param newValue value to be associated with the specified key.
90     * @return true if the value was replaced
91 dl 1.20 * @throws UnsupportedOperationException if the <tt>put</tt> operation is
92 jsr166 1.21 * not supported by this map.
93 dl 1.14 * @throws NullPointerException if this map does not permit <tt>null</tt>
94 jsr166 1.21 * keys or values, and the specified key or value is <tt>null</tt>.
95 dl 1.14 */
96     boolean replace(K key, V oldValue, V newValue);
97 dl 1.6
98 dl 1.15 /**
99 jsr166 1.21 * Replaces the entry for a key only if currently mapped to some value.
100     * This is equivalent to
101     * <pre>
102     * if (map.containsKey(key)) {
103     * return map.put(key, value);
104     * } else return null;
105 dl 1.15 * </pre>
106     * except that the action is performed atomically.
107 jsr166 1.21 *
108 dl 1.15 * @param key key with which the specified value is associated.
109     * @param value value to be associated with the specified key.
110 dl 1.16 * @return previous value associated with specified key, or <tt>null</tt>
111     * if there was no mapping for key. A <tt>null</tt> return can
112     * also indicate that the map previously associated <tt>null</tt>
113     * with the specified key, if the implementation supports
114     * <tt>null</tt> values.
115 dl 1.20 * @throws UnsupportedOperationException if the <tt>put</tt> operation is
116 jsr166 1.21 * not supported by this map.
117 dl 1.15 * @throws NullPointerException if this map does not permit <tt>null</tt>
118 jsr166 1.21 * keys or values, and the specified key or value is <tt>null</tt>.
119 dl 1.15 */
120 dl 1.16 V replace(K key, V value);
121 dl 1.15
122 tim 1.1 }