ConcurrentMap


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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags