ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.20
Committed: Thu Jun 24 23:55:02 2004 UTC (19 years, 11 months ago) by dl
Branch: MAIN
Changes since 1.19: +6 -0 lines
Log Message: 
Documentation wording 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     *
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     * @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 dl 1.5 * if (!map.containsKey(key))
30     * return map.put(key, value);
31     * else
32     * return map.get(key);
33 tim 1.1 * </pre>
34     * Except that the action is performed atomically.
35     * @param key key with which the specified value is to be associated.
36     * @param value value to be associated with the specified key.
37     * @return previous value associated with specified key, or <tt>null</tt>
38     * if there was no mapping for key. A <tt>null</tt> return can
39     * also indicate that the map previously associated <tt>null</tt>
40     * with the specified key, if the implementation supports
41     * <tt>null</tt> values.
42     *
43     * @throws UnsupportedOperationException if the <tt>put</tt> operation is
44     * not supported by this map.
45     * @throws ClassCastException if the class of the specified key or value
46     * prevents it from being stored in this map.
47     * @throws IllegalArgumentException if some aspect of this key or value
48     * prevents it from being stored in this map.
49 dholmes 1.9 * @throws NullPointerException if this map does not permit <tt>null</tt>
50 tim 1.1 * keys or values, and the specified key or value is
51     * <tt>null</tt>.
52     *
53 dl 1.18 */
54 dl 1.4 V putIfAbsent(K key, V value);
55 dl 1.6
56     /**
57     * Remove entry for key only if currently mapped to given value.
58     * Acts as
59     * <pre>
60 dl 1.14 * if ((map.containsKey(key) && map.get(key).equals(value)) {
61 dl 1.7 * map.remove(key);
62     * return true;
63 tim 1.10 * } else return false;
64 dl 1.6 * </pre>
65     * except that the action is performed atomically.
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     * not supported by this map.
71 dholmes 1.9 * @throws NullPointerException if this map does not permit <tt>null</tt>
72 dl 1.8 * keys or values, and the specified key or value is
73     * <tt>null</tt>.
74 dl 1.6 */
75 dl 1.7 boolean remove(Object key, Object value);
76 dl 1.14
77    
78     /**
79     * Replace entry for key only if currently mapped to given value.
80     * Acts as
81     * <pre>
82     * if ((map.containsKey(key) && map.get(key).equals(oldValue)) {
83     * map.put(key, newValue);
84     * return true;
85     * } else return false;
86     * </pre>
87     * except that the action is performed atomically.
88     * @param key key with which the specified value is associated.
89     * @param oldValue value expected to be associated with the specified key.
90     * @param newValue value to be associated with the specified key.
91     * @return true if the value was replaced
92 dl 1.20 * @throws UnsupportedOperationException if the <tt>put</tt> operation is
93     * not supported by this map.
94 dl 1.14 * @throws NullPointerException if this map does not permit <tt>null</tt>
95     * keys or values, and the specified key or value is
96     * <tt>null</tt>.
97     */
98     boolean replace(K key, V oldValue, V newValue);
99 dl 1.6
100 dl 1.15 /**
101     * Replace entry for key only if currently mapped to some value.
102     * Acts as
103     * <pre>
104     * if ((map.containsKey(key)) {
105 dl 1.16 * return map.put(key, value);
106     * } else return null;
107 dl 1.15 * </pre>
108     * except that the action is performed atomically.
109     * @param key key with which the specified value is associated.
110     * @param value value to be associated with the specified key.
111 dl 1.16 * @return previous value associated with specified key, or <tt>null</tt>
112     * if there was no mapping for key. A <tt>null</tt> return can
113     * also indicate that the map previously associated <tt>null</tt>
114     * with the specified key, if the implementation supports
115     * <tt>null</tt> values.
116 dl 1.20 * @throws UnsupportedOperationException if the <tt>put</tt> operation is
117     * not supported by this map.
118 dl 1.15 * @throws NullPointerException if this map does not permit <tt>null</tt>
119     * keys or values, and the specified key or value is
120     * <tt>null</tt>.
121     */
122 dl 1.16 V replace(K key, V value);
123 dl 1.15
124 tim 1.1 }