1 /* 2 * @(#)ConcurrentMap.java 1.6 04/07/12 3 * 4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 5 * SUN 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>This interface is a member of the 16 * <a HREF="{@docRoot}/../guide/collections/index.html"> 17 * Java Collections Framework</a>. 18 * 19 * @since 1.5 20 * @author Doug Lea 21 * @param <K> the type of keys maintained by this map 22 * @param <V> the type of mapped values 23 */ 24 public interface ConcurrentMap<K, V> extends Map<K, V> { 25 /** 26 * If the specified key is not already associated 27 * with a value, associate it with the given value. 28 * This is equivalent to 29 * <pre> 30 * if (!map.containsKey(key)) 31 * return map.put(key, value); 32 * else 33 * return map.get(key); 34 * </pre> 35 * Except that the action is performed atomically. 36 * @param key key with which the specified value is to be associated. 37 * @param value value to be associated with the specified key. 38 * @return previous value associated with specified key, or <tt>null</tt> 39 * if there was no mapping for key. A <tt>null</tt> return can 40 * also indicate that the map previously associated <tt>null</tt> 41 * with the specified key, if the implementation supports 42 * <tt>null</tt> values. 43 * 44 * @throws UnsupportedOperationException if the <tt>put</tt> operation is 45 * not supported by this map. 46 * @throws ClassCastException if the class of the specified key or value 47 * prevents it from being stored in this map. 48 * @throws IllegalArgumentException if some aspect of this key or value 49 * prevents it from being stored in this map. 50 * @throws NullPointerException if this map does not permit <tt>null</tt> 51 * keys or values, and the specified key or value is 52 * <tt>null</tt>. 53 * 54 */ 55 V putIfAbsent(K key, V value); 56 57 /** 58 * Remove entry for key only if currently mapped to given value. 59 * Acts as 60 * <pre> 61 * if ((map.containsKey(key) && map.get(key).equals(value)) { 62 * map.remove(key); 63 * return true; 64 * } else return false; 65 * </pre> 66 * except that the action is performed atomically. 67 * @param key key with which the specified value is associated. 68 * @param value value associated with the specified key. 69 * @return true if the value was removed, false otherwise 70 * @throws UnsupportedOperationException if the <tt>remove</tt> operation is 71 * not supported by this map. 72 * @throws NullPointerException if this map does not permit <tt>null</tt> 73 * keys or values, and the specified key or value is 74 * <tt>null</tt>. 75 */ 76 boolean remove(Object key, Object value); 77 78 79 /** 80 * Replace entry for key only if currently mapped to given value. 81 * Acts as 82 * <pre> 83 * if ((map.containsKey(key) && map.get(key).equals(oldValue)) { 84 * map.put(key, newValue); 85 * return true; 86 * } else return false; 87 * </pre> 88 * except that the action is performed atomically. 89 * @param key key with which the specified value is associated. 90 * @param oldValue value expected to be associated with the specified key. 91 * @param newValue value to be associated with the specified key. 92 * @return true if the value was replaced 93 * @throws UnsupportedOperationException if the <tt>put</tt> operation is 94 * not supported by this map. 95 * @throws NullPointerException if this map does not permit <tt>null</tt> 96 * keys or values, and the specified key or value is 97 * <tt>null</tt>. 98 */ 99 boolean replace(K key, V oldValue, V newValue); 100 101 /** 102 * Replace entry for key only if currently mapped to some value. 103 * Acts as 104 * <pre> 105 * if ((map.containsKey(key)) { 106 * return map.put(key, value); 107 * } else return null; 108 * </pre> 109 * except that the action is performed atomically. 110 * @param key key with which the specified value is associated. 111 * @param value value to be associated with the specified key. 112 * @return previous value associated with specified key, or <tt>null</tt> 113 * if there was no mapping for key. A <tt>null</tt> return can 114 * also indicate that the map previously associated <tt>null</tt> 115 * with the specified key, if the implementation supports 116 * <tt>null</tt> values. 117 * @throws UnsupportedOperationException if the <tt>put</tt> operation is 118 * not supported by this map. 119 * @throws NullPointerException if this map does not permit <tt>null</tt> 120 * keys or values, and the specified key or value is 121 * <tt>null</tt>. 122 */ 123 V replace(K key, V value); 124 125 } 126