ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.23
Committed: Mon May 2 18:36:04 2005 UTC (19 years, 1 month ago) by jsr166
Branch: MAIN
Changes since 1.22: +4 -8 lines
Log Message: 
improve rendering of whitespace around code examples

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.23 * return map.get(key);</pre>
33 jsr166 1.21 * except that the action is performed atomically.
34     *
35 tim 1.1 * @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 jsr166 1.22 * @throws UnsupportedOperationException if the <tt>put</tt> operation
43     * is not supported by this map.
44 tim 1.1 * @throws ClassCastException if the class of the specified key or value
45 jsr166 1.21 * prevents it from being stored in this map.
46 tim 1.1 * @throws IllegalArgumentException if some aspect of this key or value
47 jsr166 1.21 * prevents it from being stored in this map.
48 dholmes 1.9 * @throws NullPointerException if this map does not permit <tt>null</tt>
49 jsr166 1.21 * keys or values, and the specified key or value is <tt>null</tt>.
50 tim 1.1 *
51 dl 1.18 */
52 dl 1.4 V putIfAbsent(K key, V value);
53 dl 1.6
54     /**
55 jsr166 1.21 * Removes the entry for a key only if currently mapped to a given value.
56     * This is equivalent to
57     * <pre>
58     * if (map.containsKey(key) && map.get(key).equals(value)) {
59     * map.remove(key);
60     * return true;
61 jsr166 1.23 * } else return false;</pre>
62 dl 1.6 * except that the action is performed atomically.
63 jsr166 1.21 *
64 dl 1.7 * @param key key with which the specified value is associated.
65     * @param value value associated with the specified key.
66 dl 1.18 * @return true if the value was removed, false otherwise
67 jsr166 1.22 * @throws UnsupportedOperationException if the <tt>remove</tt> operation
68     * is not supported by this map.
69 dholmes 1.9 * @throws NullPointerException if this map does not permit <tt>null</tt>
70 jsr166 1.21 * keys or values, and the specified key or value is <tt>null</tt>.
71 dl 1.6 */
72 dl 1.7 boolean remove(Object key, Object value);
73 dl 1.14
74     /**
75 jsr166 1.21 * Replaces the entry for a key only if currently mapped to a given value.
76     * This is equivalent to
77     * <pre>
78     * if (map.containsKey(key) && map.get(key).equals(oldValue)) {
79     * map.put(key, newValue);
80     * return true;
81 jsr166 1.23 * } else return false;</pre>
82 dl 1.14 * except that the action is performed atomically.
83 jsr166 1.21 *
84 dl 1.14 * @param key key with which the specified value is associated.
85     * @param oldValue value expected to be associated with the specified key.
86     * @param newValue value to be associated with the specified key.
87     * @return true if the value was replaced
88 jsr166 1.22 * @throws UnsupportedOperationException if the <tt>put</tt> operation
89     * is not supported by this map.
90 dl 1.14 * @throws NullPointerException if this map does not permit <tt>null</tt>
91 jsr166 1.21 * keys or values, and the specified key or value is <tt>null</tt>.
92 dl 1.14 */
93     boolean replace(K key, V oldValue, V newValue);
94 dl 1.6
95 dl 1.15 /**
96 jsr166 1.21 * Replaces the entry for a key only if currently mapped to some value.
97     * This is equivalent to
98     * <pre>
99     * if (map.containsKey(key)) {
100     * return map.put(key, value);
101 jsr166 1.23 * } else return null;</pre>
102 dl 1.15 * except that the action is performed atomically.
103 jsr166 1.21 *
104 dl 1.15 * @param key key with which the specified value is associated.
105     * @param value value to be associated with the specified key.
106 dl 1.16 * @return previous value associated with specified key, or <tt>null</tt>
107     * if there was no mapping for key. A <tt>null</tt> return can
108     * also indicate that the map previously associated <tt>null</tt>
109     * with the specified key, if the implementation supports
110     * <tt>null</tt> values.
111 jsr166 1.22 * @throws UnsupportedOperationException if the <tt>put</tt> operation
112     * is not supported by this map.
113 dl 1.15 * @throws NullPointerException if this map does not permit <tt>null</tt>
114 jsr166 1.21 * keys or values, and the specified key or value is <tt>null</tt>.
115 dl 1.15 */
116 dl 1.16 V replace(K key, V value);
117 dl 1.15
118 tim 1.1 }