util/concurrent/ConcurrentMap.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util.concurrent;
import java.util.Map;
import java.util.function.BiFunction;

/**
 * A {@link java.util.Map} providing thread safety and atomicity
 * guarantees.
 *
 * <p>Memory consistency effects: As with other concurrent
 * collections, actions in a thread prior to placing an object into a
 * {@code ConcurrentMap} as a key or value
 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
 * actions subsequent to the access or removal of that object from
 * the {@code ConcurrentMap} in another thread.
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @since 1.5
 * @author Doug Lea
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
public interface ConcurrentMap<K,V> extends Map<K,V> {

    /**
     * {@inheritDoc}
     *
     * @implNote This implementation assumes that the ConcurrentMap cannot
     * contain null values and get() returning null unambiguously means the key
     * is absent. Implementations which support null values must override this
     * default implementation.
     */
    @Override
    default V getOrDefault(Object key, V defaultValue) {
        V v;
        return ((v = get(key)) != null) ? v : defaultValue;
    }

    /**
     * If the specified key is not already associated
     * with a value, associate it with the given value.
     * This is equivalent to
     *  <pre> {@code
     * if (!map.containsKey(key))
     *   return map.put(key, value);
     * else
     *   return map.get(key);}</pre>
     *
     * except that the action is performed atomically.
     *
     * @param key key with which the specified value is to be associated
     * @param value value to be associated with the specified key
     * @return the previous value associated with the specified key, or
     *         {@code null} if there was no mapping for the key.
     *         (A {@code null} return can also indicate that the map
     *         previously associated {@code null} with the key,
     *         if the implementation supports null values.)
     * @throws UnsupportedOperationException if the {@code put} operation
     *         is not supported by this map
     * @throws ClassCastException if the class of the specified key or value
     *         prevents it from being stored in this map
     * @throws NullPointerException if the specified key or value is null,
     *         and this map does not permit null keys or values
     * @throws IllegalArgumentException if some property of the specified key
     *         or value prevents it from being stored in this map
     */
    V putIfAbsent(K key, V value);

    /**
     * Removes the entry for a key only if currently mapped to a given value.
     * This is equivalent to
     *  <pre> {@code
     * if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
     *   map.remove(key);
     *   return true;
     * } else
     *   return false;}</pre>
     *
     * except that the action is performed atomically.
     *
     * @param key key with which the specified value is associated
     * @param value value expected to be associated with the specified key
     * @return {@code true} if the value was removed
     * @throws UnsupportedOperationException if the {@code remove} operation
     *         is not supported by this map
     * @throws ClassCastException if the key or value is of an inappropriate
     *         type for this map
     *         (<a href="../Collection.html#optional-restrictions">optional</a>)
     * @throws NullPointerException if the specified key or value is null,
     *         and this map does not permit null keys or values
     *         (<a href="../Collection.html#optional-restrictions">optional</a>)
     */
    boolean remove(Object key, Object value);

    /**
     * Replaces the entry for a key only if currently mapped to a given value.
     * This is equivalent to
     *  <pre> {@code
     * if (map.containsKey(key) && Objects.equals(map.get(key), oldValue)) {
     *   map.put(key, newValue);
     *   return true;
     * } else
     *   return false;}</pre>
     *
     * except that the action is performed atomically.
     *
     * @param key key with which the specified value is associated
     * @param oldValue value expected to be associated with the specified key
     * @param newValue value to be associated with the specified key
     * @return {@code true} if the value was replaced
     * @throws UnsupportedOperationException if the {@code put} operation
     *         is not supported by this map
     * @throws ClassCastException if the class of a specified key or value
     *         prevents it from being stored in this map
     * @throws NullPointerException if a specified key or value is null,
     *         and this map does not permit null keys or values
     * @throws IllegalArgumentException if some property of a specified key
     *         or value prevents it from being stored in this map
     */
    boolean replace(K key, V oldValue, V newValue);

    /**
     * Replaces the entry for a key only if currently mapped to some value.
     * This is equivalent to
     *  <pre> {@code
     * if (map.containsKey(key)) {
     *   return map.put(key, value);
     * } else
     *   return null;}</pre>
     *
     * except that the action is performed atomically.
     *
     * @param key key with which the specified value is associated
     * @param value value to be associated with the specified key
     * @return the previous value associated with the specified key, or
     *         {@code null} if there was no mapping for the key.
     *         (A {@code null} return can also indicate that the map
     *         previously associated {@code null} with the key,
     *         if the implementation supports null values.)
     * @throws UnsupportedOperationException if the {@code put} operation
     *         is not supported by this map
     * @throws ClassCastException if the class of the specified key or value
     *         prevents it from being stored in this map
     * @throws NullPointerException if the specified key or value is null,
     *         and this map does not permit null keys or values
     * @throws IllegalArgumentException if some property of the specified key
     *         or value prevents it from being stored in this map
     */
    V replace(K key, V value);

    /**
     * {@inheritDoc}
     *
     * @implNote This implementation assumes that the ConcurrentMap cannot
     * contain null values and get() returning null unambiguously means the key
     * is absent. Implementations which support null values
     * <strong>must</strong> override this default implementation.
     */
    @Override
    default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function) {
        if (function == null) throw new NullPointerException();
        for (Map.Entry<K, V> entry : entrySet()) {
            K k; V v;
            try {
                k = entry.getKey();
                v = entry.getValue();
            } catch (IllegalStateException ise) {
                continue; // skip if entry was removed
            }

            while (!replace(k, v, function.apply(k, v))) {
                if ((v = get(k)) == null) // give up if k now removed
                    break;
            }
        }
    }

}
Revision:	1.44
Committed:	Tue Jun 18 09:13:42 2013 UTC (10 years, 11 months ago) by dl
Branch:	MAIN
Changes since 1.43:	+29 -0 lines
Log Message:	Synch with lambda
#	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	jsr166	1.31	* http://creativecommons.org/publicdomain/zero/1.0/
5	dl	1.2	*/
6
7	tim	1.1	package java.util.concurrent;
8			import java.util.Map;
9	dl	1.44	import java.util.function.BiFunction;
10	tim	1.1
11			/**
12	jsr166	1.43	* A {@link java.util.Map} providing thread safety and atomicity
13	dl	1.42	* guarantees.
14	dl	1.19	*
15	jsr166	1.29	* <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	dl	1.19	* <p>This interface is a member of the
23	jsr166	1.30	* <a href="{@docRoot}/../technotes/guides/collections/index.html">
24	dl	1.19	* Java Collections Framework</a>.
25	jsr166	1.21	*
26	dl	1.4	* @since 1.5
27			* @author Doug Lea
28	dl	1.13	* @param <K> the type of keys maintained by this map
29	jsr166	1.21	* @param <V> the type of mapped values
30	dl	1.4	*/
31	jsr166	1.39	public interface ConcurrentMap<K,V> extends Map<K,V> {
32	dl	1.41
33			/**
34			* {@inheritDoc}
35			*
36			* @implNote This implementation assumes that the ConcurrentMap cannot
37			* contain null values and get() returning null unambiguously means the key
38			* is absent. Implementations which support null values must override this
39			* default implementation.
40			*/
41			@Override
42			default V getOrDefault(Object key, V defaultValue) {
43			V v;
44			return ((v = get(key)) != null) ? v : defaultValue;
45			}
46
47	tim	1.1	/**
48			* If the specified key is not already associated
49			* with a value, associate it with the given value.
50			* This is equivalent to
51	jsr166	1.36	* <pre> {@code
52			* if (!map.containsKey(key))
53			* return map.put(key, value);
54			* else
55			* return map.get(key);}</pre>
56			*
57	jsr166	1.21	* except that the action is performed atomically.
58			*
59	jsr166	1.24	* @param key key with which the specified value is to be associated
60			* @param value value to be associated with the specified key
61	jsr166	1.25	* @return the previous value associated with the specified key, or
62	jsr166	1.38	* {@code null} if there was no mapping for the key.
63			* (A {@code null} return can also indicate that the map
64			* previously associated {@code null} with the key,
65	jsr166	1.25	* if the implementation supports null values.)
66	jsr166	1.38	* @throws UnsupportedOperationException if the {@code put} operation
67	jsr166	1.24	* is not supported by this map
68	tim	1.1	* @throws ClassCastException if the class of the specified key or value
69	jsr166	1.24	* prevents it from being stored in this map
70			* @throws NullPointerException if the specified key or value is null,
71			* and this map does not permit null keys or values
72			* @throws IllegalArgumentException if some property of the specified key
73			* or value prevents it from being stored in this map
74	dl	1.18	*/
75	dl	1.4	V putIfAbsent(K key, V value);
76	dl	1.6
77			/**
78	jsr166	1.21	* Removes the entry for a key only if currently mapped to a given value.
79			* This is equivalent to
80	jsr166	1.36	* <pre> {@code
81	dl	1.40	* if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
82	jsr166	1.36	* map.remove(key);
83			* return true;
84			* } else
85			* return false;}</pre>
86			*
87	dl	1.6	* except that the action is performed atomically.
88	jsr166	1.21	*
89	jsr166	1.24	* @param key key with which the specified value is associated
90	jsr166	1.25	* @param value value expected to be associated with the specified key
91	jsr166	1.38	* @return {@code true} if the value was removed
92			* @throws UnsupportedOperationException if the {@code remove} operation
93	jsr166	1.24	* is not supported by this map
94	jsr166	1.25	* @throws ClassCastException if the key or value is of an inappropriate
95	jsr166	1.35	* type for this map
96	dl	1.33	* (<a href="../Collection.html#optional-restrictions">optional</a>)
97	jsr166	1.24	* @throws NullPointerException if the specified key or value is null,
98	dl	1.32	* and this map does not permit null keys or values
99	dl	1.33	* (<a href="../Collection.html#optional-restrictions">optional</a>)
100	dl	1.6	*/
101	dl	1.7	boolean remove(Object key, Object value);
102	dl	1.14
103			/**
104	jsr166	1.21	* Replaces the entry for a key only if currently mapped to a given value.
105			* This is equivalent to
106	jsr166	1.36	* <pre> {@code
107	dl	1.40	* if (map.containsKey(key) && Objects.equals(map.get(key), oldValue)) {
108	jsr166	1.36	* map.put(key, newValue);
109			* return true;
110			* } else
111			* return false;}</pre>
112			*
113	dl	1.14	* except that the action is performed atomically.
114	jsr166	1.21	*
115	jsr166	1.24	* @param key key with which the specified value is associated
116			* @param oldValue value expected to be associated with the specified key
117			* @param newValue value to be associated with the specified key
118	jsr166	1.38	* @return {@code true} if the value was replaced
119			* @throws UnsupportedOperationException if the {@code put} operation
120	jsr166	1.24	* is not supported by this map
121	jsr166	1.25	* @throws ClassCastException if the class of a specified key or value
122			* prevents it from being stored in this map
123	jsr166	1.24	* @throws NullPointerException if a specified key or value is null,
124			* and this map does not permit null keys or values
125	jsr166	1.25	* @throws IllegalArgumentException if some property of a specified key
126			* or value prevents it from being stored in this map
127	dl	1.14	*/
128			boolean replace(K key, V oldValue, V newValue);
129	dl	1.6
130	dl	1.15	/**
131	jsr166	1.21	* Replaces the entry for a key only if currently mapped to some value.
132			* This is equivalent to
133	jsr166	1.36	* <pre> {@code
134			* if (map.containsKey(key)) {
135			* return map.put(key, value);
136			* } else
137			* return null;}</pre>
138			*
139	dl	1.15	* except that the action is performed atomically.
140	jsr166	1.21	*
141	jsr166	1.24	* @param key key with which the specified value is associated
142			* @param value value to be associated with the specified key
143	jsr166	1.25	* @return the previous value associated with the specified key, or
144	jsr166	1.38	* {@code null} if there was no mapping for the key.
145			* (A {@code null} return can also indicate that the map
146			* previously associated {@code null} with the key,
147	jsr166	1.25	* if the implementation supports null values.)
148	jsr166	1.38	* @throws UnsupportedOperationException if the {@code put} operation
149	jsr166	1.24	* is not supported by this map
150	jsr166	1.25	* @throws ClassCastException if the class of the specified key or value
151			* prevents it from being stored in this map
152	jsr166	1.24	* @throws NullPointerException if the specified key or value is null,
153			* and this map does not permit null keys or values
154	jsr166	1.25	* @throws IllegalArgumentException if some property of the specified key
155			* or value prevents it from being stored in this map
156	dl	1.15	*/
157	dl	1.16	V replace(K key, V value);
158	dl	1.44
159			/**
160			* {@inheritDoc}
161			*
162			* @implNote This implementation assumes that the ConcurrentMap cannot
163			* contain null values and get() returning null unambiguously means the key
164			* is absent. Implementations which support null values
165			* <strong>must</strong> override this default implementation.
166			*/
167			@Override
168			default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function) {
169			if (function == null) throw new NullPointerException();
170			for (Map.Entry<K, V> entry : entrySet()) {
171			K k; V v;
172			try {
173			k = entry.getKey();
174			v = entry.getValue();
175			} catch (IllegalStateException ise) {
176			continue; // skip if entry was removed
177			}
178
179			while (!replace(k, v, function.apply(k, v))) {
180			if ((v = get(k)) == null) // give up if k now removed
181			break;
182			}
183			}
184			}
185
186	tim	1.1	}