| ConcurrentMap.java |
1 /*
2 * %W% %E%
3 *
4 * Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
5 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6 */
7
8 package java.util.concurrent;
9 import java.util.Map;
10
11 /**
12 * A {@link java.util.Map} providing additional atomic
13 * <tt>putIfAbsent</tt>, <tt>remove</tt>, and <tt>replace</tt> methods.
14 *
15 * <p>Memory consistency effects: As with other concurrent
16 * collections, actions in a thread prior to placing an object into a
17 * {@code ConcurrentMap} as a key or value
18 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
19 * actions subsequent to the access or removal of that object from
20 * the {@code ConcurrentMap} in another thread.
21 *
22 * <p>This interface is a member of the
23 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
24 * Java Collections Framework</a>.
25 *
26 * @since 1.5
27 * @author Doug Lea
28 * @param <K> the type of keys maintained by this map
29 * @param <V> the type of mapped values
30 */
31 public interface ConcurrentMap<K, V> extends Map<K, V> {
32 /**
33 * If the specified key is not already associated
34 * with a value, associate it with the given value.
35 * This is equivalent to
36 * <pre>
37 * if (!map.containsKey(key))
38 * return map.put(key, value);
39 * else
40 * return map.get(key);</pre>
41 * except that the action is performed atomically.
42 *
43 * @param key key with which the specified value is to be associated
44 * @param value value to be associated with the specified key
45 * @return the previous value associated with the specified key, or
46 * <tt>null</tt> if there was no mapping for the key.
47 * (A <tt>null</tt> return can also indicate that the map
48 * previously associated <tt>null</tt> with the key,
49 * if the implementation supports null values.)
50 * @throws UnsupportedOperationException if the <tt>put</tt> operation
51 * is not supported by this map
52 * @throws ClassCastException if the class of the specified key or value
53 * prevents it from being stored in this map
54 * @throws NullPointerException if the specified key or value is null,
55 * and this map does not permit null keys or values
56 * @throws IllegalArgumentException if some property of the specified key
57 * or value prevents it from being stored in this map
58 *
59 */
60 V putIfAbsent(K key, V value);
61
62 /**
63 * Removes the entry for a key only if currently mapped to a given value.
64 * This is equivalent to
65 * <pre>
66 * if (map.containsKey(key) && map.get(key).equals(value)) {
67 * map.remove(key);
68 * return true;
69 * } else return false;</pre>
70 * except that the action is performed atomically.
71 *
72 * @param key key with which the specified value is associated
73 * @param value value expected to be associated with the specified key
74 * @return <tt>true</tt> if the value was removed
75 * @throws UnsupportedOperationException if the <tt>remove</tt> operation
76 * is not supported by this map
77 * @throws ClassCastException if the key or value is of an inappropriate
78 * type for this map (optional)
79 * @throws NullPointerException if the specified key or value is null,
80 * and this map does not permit null keys or values (optional)
81 */
82 boolean remove(Object key, Object value);
83
84 /**
85 * Replaces the entry for a key only if currently mapped to a given value.
86 * This is equivalent to
87 * <pre>
88 * if (map.containsKey(key) && map.get(key).equals(oldValue)) {
89 * map.put(key, newValue);
90 * return true;
91 * } else return false;</pre>
92 * except that the action is performed atomically.
93 *
94 * @param key key with which the specified value is associated
95 * @param oldValue value expected to be associated with the specified key
96 * @param newValue value to be associated with the specified key
97 * @return <tt>true</tt> if the value was replaced
98 * @throws UnsupportedOperationException if the <tt>put</tt> operation
99 * is not supported by this map
100 * @throws ClassCastException if the class of a specified key or value
101 * prevents it from being stored in this map
102 * @throws NullPointerException if a specified key or value is null,
103 * and this map does not permit null keys or values
104 * @throws IllegalArgumentException if some property of a specified key
105 * or value prevents it from being stored in this map
106 */
107 boolean replace(K key, V oldValue, V newValue);
108
109 /**
110 * Replaces the entry for a key only if currently mapped to some value.
111 * This is equivalent to
112 * <pre>
113 * if (map.containsKey(key)) {
114 * return map.put(key, value);
115 * } else return null;</pre>
116 * except that the action is performed atomically.
117 *
118 * @param key key with which the specified value is associated
119 * @param value value to be associated with the specified key
120 * @return the previous value associated with the specified key, or
121 * <tt>null</tt> if there was no mapping for the key.
122 * (A <tt>null</tt> return can also indicate that the map
123 * previously associated <tt>null</tt> with the key,
124 * if the implementation supports null values.)
125 * @throws UnsupportedOperationException if the <tt>put</tt> operation
126 * is not supported by this map
127 * @throws ClassCastException if the class of the specified key or value
128 * prevents it from being stored in this map
129 * @throws NullPointerException if the specified key or value is null,
130 * and this map does not permit null keys or values
131 * @throws IllegalArgumentException if some property of the specified key
132 * or value prevents it from being stored in this map
133 */
134 V replace(K key, V value);
135 }
136