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
#	Content
1	/*
2	* Written by Doug Lea with assistance from members of JCP JSR-166
3	* Expert Group and released to the public domain, as explained at
4	* http://creativecommons.org/publicdomain/zero/1.0/
5	*/
6
7	package java.util.concurrent;
8	import java.util.Map;
9	import java.util.function.BiFunction;
10
11	/**
12	* A {@link java.util.Map} providing thread safety and atomicity
13	* guarantees.
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	/**
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	/**
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	* <pre> {@code
52	* if (!map.containsKey(key))
53	* return map.put(key, value);
54	* else
55	* return map.get(key);}</pre>
56	*
57	* except that the action is performed atomically.
58	*
59	* @param key key with which the specified value is to be associated
60	* @param value value to be associated with the specified key
61	* @return the previous value associated with the specified key, or
62	* {@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	* if the implementation supports null values.)
66	* @throws UnsupportedOperationException if the {@code put} operation
67	* is not supported by this map
68	* @throws ClassCastException if the class of the specified key or value
69	* 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	*/
75	V putIfAbsent(K key, V value);
76
77	/**
78	* Removes the entry for a key only if currently mapped to a given value.
79	* This is equivalent to
80	* <pre> {@code
81	* if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
82	* map.remove(key);
83	* return true;
84	* } else
85	* return false;}</pre>
86	*
87	* except that the action is performed atomically.
88	*
89	* @param key key with which the specified value is associated
90	* @param value value expected to be associated with the specified key
91	* @return {@code true} if the value was removed
92	* @throws UnsupportedOperationException if the {@code remove} operation
93	* is not supported by this map
94	* @throws ClassCastException if the key or value is of an inappropriate
95	* type for this map
96	* (<a href="../Collection.html#optional-restrictions">optional</a>)
97	* @throws NullPointerException if the specified key or value is null,
98	* and this map does not permit null keys or values
99	* (<a href="../Collection.html#optional-restrictions">optional</a>)
100	*/
101	boolean remove(Object key, Object value);
102
103	/**
104	* Replaces the entry for a key only if currently mapped to a given value.
105	* This is equivalent to
106	* <pre> {@code
107	* if (map.containsKey(key) && Objects.equals(map.get(key), oldValue)) {
108	* map.put(key, newValue);
109	* return true;
110	* } else
111	* return false;}</pre>
112	*
113	* except that the action is performed atomically.
114	*
115	* @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	* @return {@code true} if the value was replaced
119	* @throws UnsupportedOperationException if the {@code put} operation
120	* is not supported by this map
121	* @throws ClassCastException if the class of a specified key or value
122	* prevents it from being stored in this map
123	* @throws NullPointerException if a specified key or value is null,
124	* and this map does not permit null keys or values
125	* @throws IllegalArgumentException if some property of a specified key
126	* or value prevents it from being stored in this map
127	*/
128	boolean replace(K key, V oldValue, V newValue);
129
130	/**
131	* Replaces the entry for a key only if currently mapped to some value.
132	* This is equivalent to
133	* <pre> {@code
134	* if (map.containsKey(key)) {
135	* return map.put(key, value);
136	* } else
137	* return null;}</pre>
138	*
139	* except that the action is performed atomically.
140	*
141	* @param key key with which the specified value is associated
142	* @param value value to be associated with the specified key
143	* @return the previous value associated with the specified key, or
144	* {@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	* if the implementation supports null values.)
148	* @throws UnsupportedOperationException if the {@code put} operation
149	* is not supported by this map
150	* @throws ClassCastException if the class of the specified key or value
151	* prevents it from being stored in this map
152	* @throws NullPointerException if the specified key or value is null,
153	* and this map does not permit null keys or values
154	* @throws IllegalArgumentException if some property of the specified key
155	* or value prevents it from being stored in this map
156	*/
157	V replace(K key, V value);
158
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	}