ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.19
Committed: Tue Jan 27 11:36:31 2004 UTC (20 years, 4 months ago) by dl
Branch: MAIN
CVS Tags: JSR166_PFD
Changes since 1.18: +5 -0 lines
Log Message: 
Add Collection framework membership doc

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 dholmes 1.9 * @throws NullPointerException if this map does not permit <tt>null</tt>
70 dl 1.8 * keys or values, and the specified key or value is
71     * <tt>null</tt>.
72 dl 1.6 */
73 dl 1.7 boolean remove(Object key, Object value);
74 dl 1.14
75    
76     /**
77     * Replace entry for key only if currently mapped to given value.
78     * Acts as
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     * </pre>
85     * except that the action is performed atomically.
86     * @param key key with which the specified value is associated.
87     * @param oldValue value expected to be associated with the specified key.
88     * @param newValue value to be associated with the specified key.
89     * @return true if the value was replaced
90     * @throws NullPointerException if this map does not permit <tt>null</tt>
91     * keys or values, and the specified key or value is
92     * <tt>null</tt>.
93     */
94     boolean replace(K key, V oldValue, V newValue);
95 dl 1.6
96 dl 1.15 /**
97     * Replace entry for key only if currently mapped to some value.
98     * Acts as
99     * <pre>
100     * if ((map.containsKey(key)) {
101 dl 1.16 * return map.put(key, value);
102     * } else return null;
103 dl 1.15 * </pre>
104     * except that the action is performed atomically.
105     * @param key key with which the specified value is associated.
106     * @param value value to be associated with the specified key.
107 dl 1.16 * @return previous value associated with specified key, or <tt>null</tt>
108     * if there was no mapping for key. A <tt>null</tt> return can
109     * also indicate that the map previously associated <tt>null</tt>
110     * with the specified key, if the implementation supports
111     * <tt>null</tt> values.
112 dl 1.15 * @throws NullPointerException if this map does not permit <tt>null</tt>
113     * keys or values, and the specified key or value is
114     * <tt>null</tt>.
115     */
116 dl 1.16 V replace(K key, V value);
117 dl 1.15
118 tim 1.1 }