ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/ConcurrentMap.java
Revision: 1.24
Committed: Tue May 17 05:27:07 2005 UTC (19 years ago) by jsr166
Branch: MAIN
Changes since 1.23: +36 -36 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.23 * return map.get(key);</pre>
33 jsr166 1.21 * except that the action is performed atomically.
34     *
35 jsr166 1.24 * @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 the previous value associated with <tt>key</tt>, or
38     * <tt>null</tt> if there was no mapping for <tt>key</tt>.
39     * (A <tt>null</tt> return can also indicate that the map
40     * previously associated <tt>null</tt> with <tt>key</tt>,
41     * if the implementation supports <tt>null</tt> values.)
42 jsr166 1.22 * @throws UnsupportedOperationException if the <tt>put</tt> operation
43 jsr166 1.24 * is not supported by this map
44 tim 1.1 * @throws ClassCastException if the class of the specified key or value
45 jsr166 1.24 * prevents it from being stored in this map
46     * @throws NullPointerException if the specified key or value is null,
47     * and this map does not permit null keys or values
48     * @throws IllegalArgumentException if some property of the specified key
49     * or value prevents it from being stored in this map
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 jsr166 1.24 * if (map.containsKey(key) &amp;&amp; map.get(key).equals(value)) {
59 jsr166 1.21 * 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 jsr166 1.24 * @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 jsr166 1.24 * is not supported by this map
69     * @throws NullPointerException if the specified key or value is null,
70     * and this map does not permit null keys or values
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 jsr166 1.24 * if (map.containsKey(key) &amp;&amp; map.get(key).equals(oldValue)) {
79 jsr166 1.21 * 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 jsr166 1.24 * @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 dl 1.14 * @return true if the value was replaced
88 jsr166 1.22 * @throws UnsupportedOperationException if the <tt>put</tt> operation
89 jsr166 1.24 * is not supported by this map
90     * @throws NullPointerException if a specified key or value is null,
91     * and this map does not permit null keys or values
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 jsr166 1.24 * @param key key with which the specified value is associated
105     * @param value value to be associated with the specified key
106     * @return the previous value associated with <tt>key</tt>, or
107     * <tt>null</tt> if there was no mapping for <tt>key</tt>.
108     * (A <tt>null</tt> return can also indicate that the map
109     * previously associated <tt>null</tt> with <tt>key</tt>,
110     * if the implementation supports <tt>null</tt> values.)
111 jsr166 1.22 * @throws UnsupportedOperationException if the <tt>put</tt> operation
112 jsr166 1.24 * is not supported by this map
113     * @throws NullPointerException if the specified key or value is null,
114     * and this map does not permit null keys or values
115 dl 1.15 */
116 dl 1.16 V replace(K key, V value);
117 dl 1.15
118 tim 1.1 }