sample/java.util.concurrent.ConcurrentHashMap.txt

   1 *java.util.concurrent.ConcurrentHashMap* *ConcurrentHashMap* A hash table suppor
   2
   3 public class ConcurrentHashMap
   4   extends    |java.util.AbstractMap|
   5   implements |java.util.concurrent.ConcurrentMap|
   6              |java.io.Serializable|
   7
   8 |java.util.concurrent.ConcurrentHashMap_Description|
   9 |java.util.concurrent.ConcurrentHashMap_Fields|
  10 |java.util.concurrent.ConcurrentHashMap_Constructors|
  11 |java.util.concurrent.ConcurrentHashMap_Methods|
  12
  13 ================================================================================
  14
  15 *java.util.concurrent.ConcurrentHashMap_Constructors*
  16 |java.util.concurrent.ConcurrentHashMap()|Creates a new, empty map with a defau
  17 |java.util.concurrent.ConcurrentHashMap(int)|Creates a new, empty map with the
  18 |java.util.concurrent.ConcurrentHashMap(int,float,int)|Creates a new, empty map
  19 |java.util.concurrent.ConcurrentHashMap(Map)|Creates a new map with the same ma
  20
  21 *java.util.concurrent.ConcurrentHashMap_Methods*
  22 |java.util.concurrent.ConcurrentHashMap.clear()|Removes all mappings from this
  23 |java.util.concurrent.ConcurrentHashMap.contains(Object)|Legacy method testing
  24 |java.util.concurrent.ConcurrentHashMap.containsKey(Object)|Tests if the specif
  25 |java.util.concurrent.ConcurrentHashMap.containsValue(Object)|Returns true if t
  26 |java.util.concurrent.ConcurrentHashMap.elements()|Returns an enumeration of th
  27 |java.util.concurrent.ConcurrentHashMap.entrySet()|Returns a collection view of
  28 |java.util.concurrent.ConcurrentHashMap.get(Object)|Returns the value to which
  29 |java.util.concurrent.ConcurrentHashMap.isEmpty()|
  30 |java.util.concurrent.ConcurrentHashMap.keys()|Returns an enumeration of the ke
  31 |java.util.concurrent.ConcurrentHashMap.keySet()|Returns a set view of the keys
  32 |java.util.concurrent.ConcurrentHashMap.put(K,V)|Maps the specified key to the
  33 |java.util.concurrent.ConcurrentHashMap.putAll(Map)|Copies all of the mappings
  34 |java.util.concurrent.ConcurrentHashMap.putIfAbsent(K,V)|If the specified key i
  35 |java.util.concurrent.ConcurrentHashMap.remove(Object)|Removes the key (and its
  36 |java.util.concurrent.ConcurrentHashMap.remove(Object,Object)|Remove entry for
  37 |java.util.concurrent.ConcurrentHashMap.replace(K,V)|Replace entry for key only
  38 |java.util.concurrent.ConcurrentHashMap.replace(K,V,V)|Replace entry for key on
  39 |java.util.concurrent.ConcurrentHashMap.size()|
  40 |java.util.concurrent.ConcurrentHashMap.values()|Returns a collection view of t
  41
  42 *java.util.concurrent.ConcurrentHashMap_Description*
  43
  44 A hash table supporting full concurrency of retrievals and adjustable expected
  45 concurrency for updates. This class obeys the same functional specification as
  46 (|java.util.Hashtable|) , and includes versions of methods corresponding to
  47 each method of Hashtable. However, even though all operations are thread-safe,
  48 retrieval operations do not entail locking, and there is not any support for
  49 locking the entire table in a way that prevents all access. This class is fully
  50 interoperable with Hashtable in programs that rely on its thread safety but not
  51 on its synchronization details.
  52
  53 Retrieval operations (including get) generally do not block, so may overlap
  54 with update operations (including put and remove). Retrievals reflect the
  55 results of the most recently completed update operations holding upon their
  56 onset. For aggregate operations such as putAll and clear, concurrent retrievals
  57 may reflect insertion or removal of only some entries. Similarly, Iterators and
  58 Enumerations return elements reflecting the state of the hash table at some
  59 point at or since the creation of the iterator/enumeration. They do not throw
  60 (|java.util.ConcurrentModificationException|) . However, iterators are designed
  61 to be used by only one thread at a time.
  62
  63 The allowed concurrency among update operations is guided by the optional
  64 concurrencyLevel constructor argument (default 16), which is used as a hint for
  65 internal sizing. The table is internally partitioned to try to permit the
  66 indicated number of concurrent updates without contention. Because placement in
  67 hash tables is essentially random, the actual concurrency will vary. Ideally,
  68 you should choose a value to accommodate as many threads as will ever
  69 concurrently modify the table. Using a significantly higher value than you need
  70 can waste space and time, and a significantly lower value can lead to thread
  71 contention. But overestimates and underestimates within an order of magnitude
  72 do not usually have much noticeable impact. A value of one is appropriate when
  73 it is known that only one thread will modify and all others will only read.
  74 Also, resizing this or any other kind of hash table is a relatively slow
  75 operation, so, when possible, it is a good idea to provide estimates of
  76 expected table sizes in constructors.
  77
  78 This class and its views and iterators implement all of the optional methods of
  79 the (|java.util.Map|) and (|java.util.Iterator|) interfaces.
  80
  81 Like (|java.util.Hashtable|) but unlike (|java.util.HashMap|) , this class does
  82 NOT allow null to be used as a key or value.
  83
  84 This class is a member of the <a href="/../guide/collections/index.html"> Java
  85 Collections Framework.
  86
  87
  88 *java.util.concurrent.ConcurrentHashMap()*
  89
  90 public ConcurrentHashMap()
  91
  92 Creates a new, empty map with a default initial capacity, load factor, and
  93 concurrencyLevel.
  94
  95
  96 *java.util.concurrent.ConcurrentHashMap(int)*
  97
  98 public ConcurrentHashMap(int initialCapacity)
  99
 100 Creates a new, empty map with the specified initial capacity, and with default
 101 load factor and concurrencyLevel.
 102
 103     initialCapacity - the initial capacity. The implementation performs internal sizing to
 104        accommodate this many elements.
 105
 106 *java.util.concurrent.ConcurrentHashMap(int,float,int)*
 107
 108 public ConcurrentHashMap(
 109   int initialCapacity,
 110   float loadFactor,
 111   int concurrencyLevel)
 112
 113 Creates a new, empty map with the specified initial capacity, load factor, and
 114 concurrency level.
 115
 116     initialCapacity - the initial capacity. The implementation performs internal sizing to
 117        accommodate this many elements.
 118     loadFactor - the load factor threshold, used to control resizing. Resizing may be performed
 119        when the average number of elements per bin exceeds this threshold.
 120     concurrencyLevel - the estimated number of concurrently updating threads. The implementation
 121        performs internal sizing to try to accommodate this many threads.
 122
 123 *java.util.concurrent.ConcurrentHashMap(Map)*
 124
 125 public ConcurrentHashMap(java.util.Map t)
 126
 127 Creates a new map with the same mappings as the given map. The map is created
 128 with a capacity of twice the number of mappings in the given map or 11
 129 (whichever is greater), and a default load factor and concurrencyLevel.
 130
 131     t - the map
 132
 133 *java.util.concurrent.ConcurrentHashMap.clear()*
 134
 135 public void clear()
 136
 137 Removes all mappings from this map.
 138
 139
 140 *java.util.concurrent.ConcurrentHashMap.contains(Object)*
 141
 142 public boolean contains(java.lang.Object value)
 143
 144 Legacy method testing if some key maps into the specified value in this table.
 145 This method is identical in functionality to
 146 (|java.util.concurrent.ConcurrentHashMap|) , and exists solely to ensure full
 147 compatibility with class (|java.util.Hashtable|) , which supported this method
 148 prior to introduction of the Java Collections framework.
 149
 150     value - a value to search for.
 151
 152     Returns: true if and only if some key maps to the value argument in this table as
 153              determined by the equals method; false otherwise.
 154 *java.util.concurrent.ConcurrentHashMap.containsKey(Object)*
 155
 156 public boolean containsKey(java.lang.Object key)
 157
 158 Tests if the specified object is a key in this table.
 159
 160     key - possible key.
 161
 162     Returns: true if and only if the specified object is a key in this table, as determined
 163              by the equals method; false otherwise.
 164 *java.util.concurrent.ConcurrentHashMap.containsValue(Object)*
 165
 166 public boolean containsValue(java.lang.Object value)
 167
 168 Returns true if this map maps one or more keys to the specified value. Note:
 169 This method requires a full internal traversal of the hash table, and so is
 170 much slower than method containsKey.
 171
 172     value - value whose presence in this map is to be tested.
 173
 174     Returns: true if this map maps one or more keys to the specified value.
 175 *java.util.concurrent.ConcurrentHashMap.elements()*
 176
 177 public |java.util.Enumeration| elements()
 178
 179 Returns an enumeration of the values in this table.
 180
 181
 182     Returns: an enumeration of the values in this table.
 183 *java.util.concurrent.ConcurrentHashMap.entrySet()*
 184
 185 public |java.util.Set| entrySet()
 186
 187 Returns a collection view of the mappings contained in this map. Each element
 188 in the returned collection is a Map.Entry. The collection is backed by the map,
 189 so changes to the map are reflected in the collection, and vice-versa. The
 190 collection supports element removal, which removes the corresponding mapping
 191 from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll,
 192 and clear operations. It does not support the add or addAll operations. The
 193 view's returned iterator is a "weakly consistent" iterator that will never
 194 throw (|java.util.ConcurrentModificationException|) , and guarantees to
 195 traverse elements as they existed upon construction of the iterator, and may
 196 (but is not guaranteed to) reflect any modifications subsequent to
 197 construction.
 198
 199
 200     Returns: a collection view of the mappings contained in this map.
 201 *java.util.concurrent.ConcurrentHashMap.get(Object)*
 202
 203 public |java.lang.Object| get(java.lang.Object key)
 204
 205 Returns the value to which the specified key is mapped in this table.
 206
 207     key - a key in the table.
 208
 209     Returns: the value to which the key is mapped in this table; null if the key is not
 210              mapped to any value in this table.
 211 *java.util.concurrent.ConcurrentHashMap.isEmpty()*
 212
 213 public boolean isEmpty()
 214
 215
 216
 217
 218 *java.util.concurrent.ConcurrentHashMap.keys()*
 219
 220 public |java.util.Enumeration| keys()
 221
 222 Returns an enumeration of the keys in this table.
 223
 224
 225     Returns: an enumeration of the keys in this table.
 226 *java.util.concurrent.ConcurrentHashMap.keySet()*
 227
 228 public |java.util.Set| keySet()
 229
 230 Returns a set view of the keys contained in this map. The set is backed by the
 231 map, so changes to the map are reflected in the set, and vice-versa. The set
 232 supports element removal, which removes the corresponding mapping from this
 233 map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear
 234 operations. It does not support the add or addAll operations. The view's
 235 returned iterator is a "weakly consistent" iterator that will never throw
 236 (|java.util.ConcurrentModificationException|) , and guarantees to traverse
 237 elements as they existed upon construction of the iterator, and may (but is not
 238 guaranteed to) reflect any modifications subsequent to construction.
 239
 240
 241     Returns: a set view of the keys contained in this map.
 242 *java.util.concurrent.ConcurrentHashMap.put(K,V)*
 243
 244 public |java.lang.Object| put(
 245   java.lang.Object key,
 246   java.lang.Object value)
 247
 248 Maps the specified key to the specified value in this table. Neither the key
 249 nor the value can be null.
 250
 251 The value can be retrieved by calling the get method with a key that is equal
 252 to the original key.
 253
 254     key - the table key.
 255     value - the value.
 256
 257     Returns: the previous value of the specified key in this table, or null if it did not
 258              have one.
 259 *java.util.concurrent.ConcurrentHashMap.putAll(Map)*
 260
 261 public void putAll(java.util.Map t)
 262
 263 Copies all of the mappings from the specified map to this one.
 264
 265 These mappings replace any mappings that this map had for any of the keys
 266 currently in the specified Map.
 267
 268     t - Mappings to be stored in this map.
 269
 270 *java.util.concurrent.ConcurrentHashMap.putIfAbsent(K,V)*
 271
 272 public |java.lang.Object| putIfAbsent(
 273   java.lang.Object key,
 274   java.lang.Object value)
 275
 276 If the specified key is not already associated with a value, associate it with
 277 the given value. This is equivalent to
 278
 279 if (!map.containsKey(key)) return map.put(key, value); else return
 280 map.get(key);
 281
 282 Except that the action is performed atomically.
 283
 284     key - key with which the specified value is to be associated.
 285     value - value to be associated with the specified key.
 286
 287     Returns: previous value associated with specified key, or null if there was no mapping
 288              for key.
 289 *java.util.concurrent.ConcurrentHashMap.remove(Object)*
 290
 291 public |java.lang.Object| remove(java.lang.Object key)
 292
 293 Removes the key (and its corresponding value) from this table. This method does
 294 nothing if the key is not in the table.
 295
 296     key - the key that needs to be removed.
 297
 298     Returns: the value to which the key had been mapped in this table, or null if the key
 299              did not have a mapping.
 300 *java.util.concurrent.ConcurrentHashMap.remove(Object,Object)*
 301
 302 public boolean remove(
 303   java.lang.Object key,
 304   java.lang.Object value)
 305
 306 Remove entry for key only if currently mapped to given value. Acts as
 307
 308 if (map.get(key).equals(value)) { map.remove(key); return true; } else return
 309 false;
 310
 311 except that the action is performed atomically.
 312
 313     key - key with which the specified value is associated.
 314     value - value associated with the specified key.
 315
 316     Returns: true if the value was removed
 317 *java.util.concurrent.ConcurrentHashMap.replace(K,V)*
 318
 319 public |java.lang.Object| replace(
 320   java.lang.Object key,
 321   java.lang.Object value)
 322
 323 Replace entry for key only if currently mapped to some value. Acts as
 324
 325 if ((map.containsKey(key)) { return map.put(key, value); } else return null;
 326
 327 except that the action is performed atomically.
 328
 329     key - key with which the specified value is associated.
 330     value - value to be associated with the specified key.
 331
 332     Returns: previous value associated with specified key, or null if there was no mapping
 333              for key.
 334 *java.util.concurrent.ConcurrentHashMap.replace(K,V,V)*
 335
 336 public boolean replace(
 337   java.lang.Object key,
 338   java.lang.Object oldValue,
 339   java.lang.Object newValue)
 340
 341 Replace entry for key only if currently mapped to given value. Acts as
 342
 343 if (map.get(key).equals(oldValue)) { map.put(key, newValue); return true; }
 344 else return false;
 345
 346 except that the action is performed atomically.
 347
 348     key - key with which the specified value is associated.
 349     oldValue - value expected to be associated with the specified key.
 350     newValue - value to be associated with the specified key.
 351
 352     Returns: true if the value was replaced
 353 *java.util.concurrent.ConcurrentHashMap.size()*
 354
 355 public int size()
 356
 357
 358
 359
 360 *java.util.concurrent.ConcurrentHashMap.values()*
 361
 362 public |java.util.Collection| values()
 363
 364 Returns a collection view of the values contained in this map. The collection
 365 is backed by the map, so changes to the map are reflected in the collection,
 366 and vice-versa. The collection supports element removal, which removes the
 367 corresponding mapping from this map, via the Iterator.remove,
 368 Collection.remove, removeAll, retainAll, and clear operations. It does not
 369 support the add or addAll operations. The view's returned iterator is a "weakly
 370 consistent" iterator that will never throw
 371 (|java.util.ConcurrentModificationException|) , and guarantees to traverse
 372 elements as they existed upon construction of the iterator, and may (but is not
 373 guaranteed to) reflect any modifications subsequent to construction.
 374
 375
 376     Returns: a collection view of the values contained in this map.
 377