util/concurrent/ConcurrentMap.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

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

/**
 * A {@link java.util.Map} providing an additional atomic
 * <tt>putIfAbsent</tt> and <tt>remove</tt> methods.
 * @since 1.5
 * @author Doug Lea
 */
public interface ConcurrentMap<K, V> extends Map<K, V> {
    /**
     * If the specified key is not already associated
     * with a value, associate it with the given value.
     * This is equivalent to
     * <pre>
     *   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 previous value associated with specified key, or <tt>null</tt>
     *         if there was no mapping for key.  A <tt>null</tt> return can
     *         also indicate that the map previously associated <tt>null</tt>
     *         with the specified key, if the implementation supports
     *         <tt>null</tt> values.
     *
     * @throws UnsupportedOperationException if the <tt>put</tt> 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 IllegalArgumentException if some aspect of this key or value
     *            prevents it from being stored in this map.
     * @throws NullPointerException this map does not permit <tt>null</tt>
     *            keys or values, and the specified key or value is
     *            <tt>null</tt>.
     *
     **/
    V putIfAbsent(K key, V value);

    /**
     * Remove entry for key only if currently mapped to given value.
     * Acts as
     * <pre> 
     *  if (map.get(key).equals(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 associated with the specified key.
     * @return true if the value was removed
     * @throws NullPointerException this map does not permit <tt>null</tt>
     *            keys or values, and the specified key or value is
     *            <tt>null</tt>.
     */
    boolean remove(Object key, Object value);

}
Revision:	1.8
Committed:	Mon Aug 4 12:10:27 2003 UTC (20 years, 10 months ago) by dl
Branch:	MAIN
Changes since 1.7:	+3 -0 lines
Log Message:	Remove signatures now match Clarified nanoTime wraparound/overflow
#	User	Rev	Content
1	dl	1.2	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain. Use, modify, and
4			* redistribute this code in any way without acknowledgement.
5			*/
6
7	tim	1.1	package java.util.concurrent;
8			import java.util.Map;
9
10			/**
11	dl	1.3	* A {@link java.util.Map} providing an additional atomic
12	dl	1.6	* <tt>putIfAbsent</tt> and <tt>remove</tt> methods.
13	dl	1.4	* @since 1.5
14			* @author Doug Lea
15			*/
16	tim	1.1	public interface ConcurrentMap<K, V> extends Map<K, V> {
17			/**
18			* If the specified key is not already associated
19			* with a value, associate it with the given value.
20			* This is equivalent to
21			* <pre>
22	dl	1.5	* if (!map.containsKey(key))
23			* return map.put(key, value);
24			* else
25			* return map.get(key);
26	tim	1.1	* </pre>
27			* Except that the action is performed atomically.
28			* @param key key with which the specified value is to be associated.
29			* @param value value to be associated with the specified key.
30			* @return previous value associated with specified key, or <tt>null</tt>
31			* if there was no mapping for key. A <tt>null</tt> return can
32			* also indicate that the map previously associated <tt>null</tt>
33			* with the specified key, if the implementation supports
34			* <tt>null</tt> values.
35			*
36			* @throws UnsupportedOperationException if the <tt>put</tt> operation is
37			* not supported by this map.
38			* @throws ClassCastException if the class of the specified key or value
39			* prevents it from being stored in this map.
40			* @throws IllegalArgumentException if some aspect of this key or value
41			* prevents it from being stored in this map.
42			* @throws NullPointerException this map does not permit <tt>null</tt>
43			* keys or values, and the specified key or value is
44			* <tt>null</tt>.
45			*
46			**/
47	dl	1.4	V putIfAbsent(K key, V value);
48	dl	1.6
49			/**
50			* Remove entry for key only if currently mapped to given value.
51			* Acts as
52			* <pre>
53	dl	1.7	* if (map.get(key).equals(value)) {
54			* map.remove(key);
55			* return true;
56			* }
57			* else return false;
58	dl	1.6	* </pre>
59			* except that the action is performed atomically.
60	dl	1.7	* @param key key with which the specified value is associated.
61			* @param value value associated with the specified key.
62			* @return true if the value was removed
63	dl	1.8	* @throws NullPointerException this map does not permit <tt>null</tt>
64			* keys or values, and the specified key or value is
65			* <tt>null</tt>.
66	dl	1.6	*/
67	dl	1.7	boolean remove(Object key, Object value);
68	dl	1.6
69	tim	1.1	}