fixed some formatting typos

[vimdoclet.git] / sample / java.util.concurrent.ConcurrentHashMap.txt

*java.util.concurrent.ConcurrentHashMap* *ConcurrentHashMap* A hash table suppor

public class ConcurrentHashMap<K,V>
  extends    |java.util.AbstractMap|
  implements |java.util.concurrent.ConcurrentMap|
             |java.io.Serializable|

|java.util.concurrent.ConcurrentHashMap_Description|
|java.util.concurrent.ConcurrentHashMap_Fields|
|java.util.concurrent.ConcurrentHashMap_Constructors|
|java.util.concurrent.ConcurrentHashMap_Methods|

================================================================================

*java.util.concurrent.ConcurrentHashMap_Constructors*
|java.util.concurrent.ConcurrentHashMap()|Creates a new, empty map with a defau
|java.util.concurrent.ConcurrentHashMap(int)|Creates a new, empty map with the 
|java.util.concurrent.ConcurrentHashMap(int,float)|Creates a new, empty map wit
|java.util.concurrent.ConcurrentHashMap(int,float,int)|Creates a new, empty map
|java.util.concurrent.ConcurrentHashMap(Map<?extendsK,?extendsV>)|Creates a new

*java.util.concurrent.ConcurrentHashMap_Methods*
|java.util.concurrent.ConcurrentHashMap.clear()|Removes all of the mappings fro
|java.util.concurrent.ConcurrentHashMap.contains(Object)|Legacy method testing 
|java.util.concurrent.ConcurrentHashMap.containsKey(Object)|Tests if the specif
|java.util.concurrent.ConcurrentHashMap.containsValue(Object)|Returns true if t
|java.util.concurrent.ConcurrentHashMap.elements()|Returns an enumeration of th
|java.util.concurrent.ConcurrentHashMap.entrySet()|Returns aSetview of the mapp
|java.util.concurrent.ConcurrentHashMap.get(Object)|Returns the value to which 
|java.util.concurrent.ConcurrentHashMap.isEmpty()|Returns true if this map cont
|java.util.concurrent.ConcurrentHashMap.keys()|Returns an enumeration of the ke
|java.util.concurrent.ConcurrentHashMap.keySet()|Returns aSetview of the keys c
|java.util.concurrent.ConcurrentHashMap.put(K,V)|Maps the specified key to the 
|java.util.concurrent.ConcurrentHashMap.putAll(Map<?extendsK,?extendsV>)|Copies
|java.util.concurrent.ConcurrentHashMap.putIfAbsent(K,V)|
|java.util.concurrent.ConcurrentHashMap.remove(Object)|Removes the key (and its
|java.util.concurrent.ConcurrentHashMap.remove(Object,Object)|
|java.util.concurrent.ConcurrentHashMap.replace(K,V)|
|java.util.concurrent.ConcurrentHashMap.replace(K,V,V)|
|java.util.concurrent.ConcurrentHashMap.size()|Returns the number of key-value 
|java.util.concurrent.ConcurrentHashMap.values()|Returns aCollectionview of the

*java.util.concurrent.ConcurrentHashMap_Description*

A hash table supporting full concurrency of retrievals and adjustable expected 
concurrency for updates. This class obeys the same functional specification as 
(|java.util.Hashtable|) , and includes versions of methods corresponding to 
each method of Hashtable. However, even though all operations are thread-safe, 
retrieval operations do not entail locking, and there is not any support for 
locking the entire table in a way that prevents all access. This class is fully 
interoperable with Hashtable in programs that rely on its thread safety but not 
on its synchronization details. 

Retrieval operations (including get) generally do not block, so may overlap 
with update operations (including put and remove). Retrievals reflect the 
results of the most recently completed update operations holding upon their 
onset. For aggregate operations such as putAll and clear, concurrent retrievals 
may reflect insertion or removal of only some entries. Similarly, Iterators and 
Enumerations return elements reflecting the state of the hash table at some 
point at or since the creation of the iterator/enumeration. They do not throw 
(|java.util.ConcurrentModificationException|) . However, iterators are designed 
to be used by only one thread at a time. 

The allowed concurrency among update operations is guided by the optional 
concurrencyLevel constructor argument (default 16), which is used as a hint for 
internal sizing. The table is internally partitioned to try to permit the 
indicated number of concurrent updates without contention. Because placement in 
hash tables is essentially random, the actual concurrency will vary. Ideally, 
you should choose a value to accommodate as many threads as will ever 
concurrently modify the table. Using a significantly higher value than you need 
can waste space and time, and a significantly lower value can lead to thread 
contention. But overestimates and underestimates within an order of magnitude 
do not usually have much noticeable impact. A value of one is appropriate when 
it is known that only one thread will modify and all others will only read. 
Also, resizing this or any other kind of hash table is a relatively slow 
operation, so, when possible, it is a good idea to provide estimates of 
expected table sizes in constructors. 

This class and its views and iterators implement all of the optional methods of 
the (|java.util.Map|) and (|java.util.Iterator|) interfaces. 

Like (|java.util.Hashtable|) but unlike (|java.util.HashMap|) , this class does 
not allow null to be used as a key or value. 

This class is a member of the <a 
href="/../technotes/guides/collections/index.html"> Java Collections Framework. 



*java.util.concurrent.ConcurrentHashMap()*

public ConcurrentHashMap()

Creates a new, empty map with a default initial capacity (16), load factor 
(0.75) and concurrencyLevel (16). 


*java.util.concurrent.ConcurrentHashMap(int)*

public ConcurrentHashMap(int initialCapacity)

Creates a new, empty map with the specified initial capacity, and with default 
load factor (0.75) and concurrencyLevel (16). 

    initialCapacity - the initial capacity. The implementation performs internal sizing to 
       accommodate this many elements. 

*java.util.concurrent.ConcurrentHashMap(int,float)*

public ConcurrentHashMap(
  int initialCapacity,
  float loadFactor)

Creates a new, empty map with the specified initial capacity and load factor 
and with the default concurrencyLevel (16). 

    initialCapacity - The implementation performs internal sizing to accommodate this many elements. 
    loadFactor - the load factor threshold, used to control resizing. Resizing may be performed 
       when the average number of elements per bin exceeds this threshold. 

*java.util.concurrent.ConcurrentHashMap(int,float,int)*

public ConcurrentHashMap(
  int initialCapacity,
  float loadFactor,
  int concurrencyLevel)

Creates a new, empty map with the specified initial capacity, load factor and 
concurrency level. 

    initialCapacity - the initial capacity. The implementation performs internal sizing to 
       accommodate this many elements. 
    loadFactor - the load factor threshold, used to control resizing. Resizing may be performed 
       when the average number of elements per bin exceeds this threshold. 
    concurrencyLevel - the estimated number of concurrently updating threads. The implementation 
       performs internal sizing to try to accommodate this many threads. 

*java.util.concurrent.ConcurrentHashMap(Map<?extendsK,?extendsV>)*

public ConcurrentHashMap(java.util.Map<? extends K, ? extends V> m)

Creates a new map with the same mappings as the given map. The map is created 
with a capacity of 1.5 times the number of mappings in the given map or 16 
(whichever is greater), and a default load factor (0.75) and concurrencyLevel 
(16). 

    m - the map 

*java.util.concurrent.ConcurrentHashMap.clear()*

public void clear()

Removes all of the mappings from this map. 



*java.util.concurrent.ConcurrentHashMap.contains(Object)*

public boolean contains(java.lang.Object value)

Legacy method testing if some key maps into the specified value in this table. 
This method is identical in functionality to 
(|java.util.concurrent.ConcurrentHashMap|) , and exists solely to ensure full 
compatibility with class (|java.util.Hashtable|) , which supported this method 
prior to introduction of the Java Collections framework. 


    value - a value to search for 

    Returns: true if and only if some key maps to the value argument in this table as 
             determined by the equals method; false otherwise 

*java.util.concurrent.ConcurrentHashMap.containsKey(Object)*

public boolean containsKey(java.lang.Object key)

Tests if the specified object is a key in this table. 


    key - possible key 

    Returns: true if and only if the specified object is a key in this table, as determined 
             by the equals method; false otherwise. 

*java.util.concurrent.ConcurrentHashMap.containsValue(Object)*

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more keys to the specified value. Note: 
This method requires a full internal traversal of the hash table, and so is 
much slower than method containsKey. 


    value - value whose presence in this map is to be tested 

    Returns: true if this map maps one or more keys to the specified value 

*java.util.concurrent.ConcurrentHashMap.elements()*

public |java.util.Enumeration|<V> elements()

Returns an enumeration of the values in this table. 



    Returns: an enumeration of the values in this table 

*java.util.concurrent.ConcurrentHashMap.entrySet()*

public |java.util.Set|<Entry<K,V>> entrySet()

Returns a (|java.util.Set|) view of the mappings contained in this map. The set 
is backed by the map, so changes to the map are reflected in the set, and 
vice-versa. The set supports element removal, which removes the corresponding 
mapping from the map, via the Iterator.remove, Set.remove, removeAll, 
retainAll, and clear operations. It does not support the add or addAll 
operations. 

The view's iterator is a "weakly consistent" iterator that will never throw 
(|java.util.ConcurrentModificationException|) , and guarantees to traverse 
elements as they existed upon construction of the iterator, and may (but is not 
guaranteed to) reflect any modifications subsequent to construction. 



*java.util.concurrent.ConcurrentHashMap.get(Object)*

public |V| get(java.lang.Object key)

Returns the value to which the specified key is mapped, ornullif this map 
contains no mapping for the key. 

More formally, if this map contains a mapping from a keykto a valuevsuch 
thatkey.equals(k), then this method returnsv; otherwise it returnsnull. (There 
can be at most one such mapping.) 



*java.util.concurrent.ConcurrentHashMap.isEmpty()*

public boolean isEmpty()

Returns true if this map contains no key-value mappings. 



    Returns: true if this map contains no key-value mappings 

*java.util.concurrent.ConcurrentHashMap.keys()*

public |java.util.Enumeration|<K> keys()

Returns an enumeration of the keys in this table. 



    Returns: an enumeration of the keys in this table 

*java.util.concurrent.ConcurrentHashMap.keySet()*

public |java.util.Set|<K> keySet()

Returns a (|java.util.Set|) view of the keys contained in this map. The set is 
backed by the map, so changes to the map are reflected in the set, and 
vice-versa. The set supports element removal, which removes the corresponding 
mapping from this map, via the Iterator.remove, Set.remove, removeAll, 
retainAll, and clear operations. It does not support the add or addAll 
operations. 

The view's iterator is a "weakly consistent" iterator that will never throw 
(|java.util.ConcurrentModificationException|) , and guarantees to traverse 
elements as they existed upon construction of the iterator, and may (but is not 
guaranteed to) reflect any modifications subsequent to construction. 



*java.util.concurrent.ConcurrentHashMap.put(K,V)*

public |V| put(
  K key,
  V value)

Maps the specified key to the specified value in this table. Neither the key 
nor the value can be null. 

The value can be retrieved by calling the get method with a key that is equal 
to the original key. 


    key - key with which the specified value is to be associated 
    value - value to be associated with the specified key 

    Returns: the previous value associated with key, or null if there was no mapping for key 

*java.util.concurrent.ConcurrentHashMap.putAll(Map<?extendsK,?extendsV>)*

public void putAll(java.util.Map<? extends K, ? extends V> m)

Copies all of the mappings from the specified map to this one. These mappings 
replace any mappings that this map had for any of the keys currently in the 
specified map. 


    m - mappings to be stored in this map 

*java.util.concurrent.ConcurrentHashMap.putIfAbsent(K,V)*

public |V| putIfAbsent(
  K key,
  V value)





    Returns: the previous value associated with the specified key, or null if there was no 
             mapping for the key 

*java.util.concurrent.ConcurrentHashMap.remove(Object)*

public |V| remove(java.lang.Object key)

Removes the key (and its corresponding value) from this map. This method does 
nothing if the key is not in the map. 


    key - the key that needs to be removed 

    Returns: the previous value associated with key, or null if there was no mapping for key 

*java.util.concurrent.ConcurrentHashMap.remove(Object,Object)*

public boolean remove(
  java.lang.Object key,
  java.lang.Object value)





*java.util.concurrent.ConcurrentHashMap.replace(K,V)*

public |V| replace(
  K key,
  V value)





    Returns: the previous value associated with the specified key, or null if there was no 
             mapping for the key 

*java.util.concurrent.ConcurrentHashMap.replace(K,V,V)*

public boolean replace(
  K key,
  V oldValue,
  V newValue)





*java.util.concurrent.ConcurrentHashMap.size()*

public int size()

Returns the number of key-value mappings in this map. If the map contains more 
than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE. 



    Returns: the number of key-value mappings in this map 

*java.util.concurrent.ConcurrentHashMap.values()*

public |java.util.Collection|<V> values()

Returns a (|java.util.Collection|) view of the values contained in this map. 
The collection is backed by the map, so changes to the map are reflected in the 
collection, and vice-versa. The collection supports element removal, which 
removes the corresponding mapping from this map, via the Iterator.remove, 
Collection.remove, removeAll, retainAll, and clear operations. It does not 
support the add or addAll operations. 

The view's iterator is a "weakly consistent" iterator that will never throw 
(|java.util.ConcurrentModificationException|) , and guarantees to traverse 
elements as they existed upon construction of the iterator, and may (but is not 
guaranteed to) reflect any modifications subsequent to construction.