JavaTM Platform
Standard Ed. 6

java.util.concurrent
类 ConcurrentHashMap<K,V>

java.lang.Object
  继承者 java.util.AbstractMap<K,V>
      继承者 java.util.concurrent.ConcurrentHashMap<K,V>
类型参数:
K - 此映射维护的键的类型
V - 映射值的类
所有已实现的接口:
Serializable, ConcurrentMap<K,V>, Map<K,V>

public class ConcurrentHashMap<K,V>
extends AbstractMap<K,V>
implements ConcurrentMap<K,V>, Serializable

支持获取的完全并发和更新的所期望可调整并发的哈希表。此类遵守与 Hashtable 相同的功能规范,并且包括对应于 Hashtable 的每个方法的方法版本。不过,尽管所有操作都是线程安全的,但获取操作 必锁定,并且 支持以某种防止所有访问的方式锁定整个表。此类可以通过程序完全与 Hashtable 进行互操作,这取决于其线程安全,而与其同步细节无关。

获取操作(包括 get)通常不会受阻塞,因此,可能与更新操作交迭(包括 putremove)。获取会影响最近完成的 更新操作的结果。对于一些聚合操作,比如 putAllclear,并发获取可能只影响某些条目的插入和移除。类似地,在创建迭代器/枚举时或自此之后,Iterators 和 Enumerations 返回在某一时间点上影响哈希表状态的元素。它们不会 抛出 ConcurrentModificationException。不过,迭代器被设计成每次仅由一个线程使用。

这允许通过可选的 concurrencyLevel 构造方法参数(默认值为 16)来引导更新操作之间的并发,该参数用作内部调整大小的一个提示。表是在内部进行分区的,试图允许指示无争用并发更新的数量。因为哈希表中的位置基本上是随意的,所以实际的并发将各不相同。理想情况下,应该选择一个尽可能多地容纳并发修改该表的线程的值。使用一个比所需要的值高很多的值可能会浪费空间和时间,而使用一个显然低很多的值可能导致线程争用。对数量级估计过高或估计过低通常都会带来非常显著的影响。当仅有一个线程将执行修改操作,而其他所有线程都只是执行读取操作时,才认为某个值是合适的。此外,重新调整此类或其他任何种类哈希表的大小都是一个相对较慢的操作,因此,在可能的时候,提供构造方法中期望表大小的估计值是一个好主意。

此类及其视图和迭代器实现了 MapIterator 接口的所有可选 方法。

此类与 Hashtable 相似,但与 HashMap 不同,它 允许将 null 用作键或值。

此类是 Java Collections Framework 的成员。

从以下版本开始:
1.5
另请参见:
序列化表格

嵌套类摘要
 
从类 java.util.AbstractMap 继承的嵌套类/接口
AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>
 
从接口 java.util.Map 继承的嵌套类/接口
Map.Entry<K,V>
 
构造方法摘要
ConcurrentHashMap()
          创建一个带有默认初始容量 (16)、加载因子 (0.75) 和 concurrencyLevel (16) 的新的空映射。
ConcurrentHashMap(int initialCapacity)
          创建一个带有指定初始容量、默认加载因子 (0.75) 和 concurrencyLevel (16) 的新的空映射。
ConcurrentHashMap(int initialCapacity, float loadFactor)
          创建一个带有指定初始容量、加载因子和默认 concurrencyLevel (16) 的新的空映射。
ConcurrentHashMap(int initialCapacity, float loadFactor, int concurrencyLevel)
          创建一个带有指定初始容量、加载因子和并发级别的新的空映射。
ConcurrentHashMap(Map<? extends K,? extends V> m)
          构造一个与给定映射具有相同映射关系的新映射。
 
方法摘要
 void clear()
          从该映射中移除所有映射关系
 boolean contains(Object value)
          一种遗留方法,测试此表中是否有一些与指定值存在映射关系的键。
 boolean containsKey(Object key)
          测试指定对象是否为此表中的键。
 boolean containsValue(Object value)
          如果此映射将一个或多个键映射到指定值,则返回 true
 Enumeration<V> elements()
          返回此表中值的枚举。
 Set<Map.Entry<K,V>> entrySet()
          返回此映射所包含的映射关系的 Set 视图。
 V get(Object key)
          返回指定键所映射到的值,如果此映射不包含该键的映射关系,则返回 null
 boolean isEmpty()
          如果此映射不包含键-值映射关系,则返回 true
 Enumeration<K> keys()
          返回此表中键的枚举。
 Set<K> keySet()
          返回此映射中包含的键的 Set 视图。
 V put(K key, V value)
          将指定键映射到此表中的指定值。
 void putAll(Map<? extends K,? extends V> m)
          将指定映射中所有映射关系复制到此映射中。
 V putIfAbsent(K key, V value)
          如果指定键已经不再与某个值相关联,则将它与给定值关联。
 V remove(Object key)
          从此映射中移除键(及其相应的值)。
 boolean remove(Object key, Object value)
          只有目前将键的条目映射到给定值时,才移除该键的条目。
 V replace(K key, V value)
          只有目前将键的条目映射到某一值时,才替换该键的条目。
 boolean replace(K key, V oldValue, V newValue)
          只有目前将键的条目映射到给定值时,才替换该键的条目。
 int size()
          返回此映射中的键-值映射关系数。
 Collection<V> values()
          返回此映射中包含的值的 Collection 视图。
 
从类 java.util.AbstractMap 继承的方法
clone, equals, hashCode, toString
 
从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, wait, wait, wait
 
从接口 java.util.Map 继承的方法
equals, hashCode
 

构造方法详细信息

ConcurrentHashMap

public ConcurrentHashMap(int initialCapacity,
                         float loadFactor,
                         int concurrencyLevel)
创建一个带有指定初始容量、加载因子和并发级别的新的空映射。

参数:
initialCapacity - 初始容量。该实现执行内部大小调整,以容纳这些元素。
loadFactor - 加载因子阈值,用来控制重新调整大小。在每 bin 中的平均元素数大于此阈值时,可能要重新调整大小。
concurrencyLevel - 当前更新线程的估计数。该实现将执行内部大小调整,以尽量容纳这些线程。
抛出:
IllegalArgumentException - 如果初始容量为负,或者加载因子或 concurrencyLevel 为非正。

ConcurrentHashMap

public ConcurrentHashMap(int initialCapacity,
                         float loadFactor)
创建一个带有指定初始容量、加载因子和默认 concurrencyLevel (16) 的新的空映射。

参数:
initialCapacity - 该实现执行内部的大小调整,以容纳这些元素。
loadFactor - 加载因子阈值,用来控制重新调整大小。在每 bin 中的平均元素数大于此阈值时,可能要重新调整大小。
抛出:
IllegalArgumentException - 如果元素的初始容量为负,或者加载因子为非正
从以下版本开始:
1.6

ConcurrentHashMap

public ConcurrentHashMap(int initialCapacity)
创建一个带有指定初始容量、默认加载因子 (0.75) 和 concurrencyLevel (16) 的新的空映射。

参数:
initialCapacity - 初始容量。该实现执行内部的大小调整,以容纳这些元素。
抛出:
IllegalArgumentException - 如果元素的初始容量为负。

ConcurrentHashMap

public ConcurrentHashMap()
创建一个带有默认初始容量 (16)、加载因子 (0.75) 和 concurrencyLevel (16) 的新的空映射。


ConcurrentHashMap

public ConcurrentHashMap(Map<? extends K,? extends V> m)
构造一个与给定映射具有相同映射关系的新映射。使用给定映射中映射关系数 1.5 倍的容量或 16(选更大的那一个)、默认加载因子 (0.75) 和 concurrencyLevel (16) 来创建该映射。

参数:
m - 映射
方法详细信息

isEmpty

public boolean isEmpty()
如果此映射不包含键-值映射关系,则返回 true

指定者:
接口 Map<K,V> 中的 isEmpty
覆盖:
AbstractMap<K,V> 中的 isEmpty
返回:
如果此映射不包含键-值映射关系,则返回 true

size

public int size()
返回此映射中的键-值映射关系数。如果该映射包含的元素多于 Integer.MAX_VALUE,则返回 Integer.MAX_VALUE

指定者:
接口 Map<K,V> 中的 size
覆盖:
AbstractMap<K,V> 中的 size
返回:
此映射中的键-值映射关系数

get

public V get(Object key)
返回指定键所映射到的值,如果此映射不包含该键的映射关系,则返回 null

更确切地讲,如果此映射包含满足从键 k 到值 v 的映射关系 key.equals(k),则此方法返回 v;否则它返回 null。(最多只能有一个这样的映射关系)。

指定者:
接口 Map<K,V> 中的 get
覆盖:
AbstractMap<K,V> 中的 get
参数:
key - 要返回其关联值的键
返回:
指定键所映射的值;如果此映射不包含该键的映射关系,则返回 null
抛出:
NullPointerException - 如果指定键为 null

containsKey

public boolean containsKey(Object key)
测试指定对象是否为此表中的键。

指定者:
接口 Map<K,V> 中的 containsKey
覆盖:
AbstractMap<K,V> 中的 containsKey
参数:
key - 可能的键
返回:
当且仅当指定对象(由 equals 方法确定)是此表中的键时,返回 true;否则返回 false
抛出:
NullPointerException - 如果指定键为 null

containsValue

public boolean containsValue(Object value)
如果此映射将一个或多个键映射到指定值,则返回 true。注:此方法需要完全内部遍历哈希表,因此它比方法 containsKey 更慢。

指定者:
接口 Map<K,V> 中的 containsValue
覆盖:
AbstractMap<K,V> 中的 containsValue
参数:
value - 测试在此映射中是否存在的值
返回:
如果此映射将一个或多个键映射到指定值,则返回 true
抛出:
NullPointerException - 如果指定值为 null

contains

public boolean contains(Object value)
一种遗留方法,测试此表中是否有一些与指定值存在映射关系的键。此方法在功能上等同于 containsValue(java.lang.Object),并且它的存在只是为了确保与 Hashtable 类完全兼容,在引入 Java Collection 框架之前,该类支持此方法。

参数:
value - 要搜索的值
返回:
当且仅当此表中某个键映射到 value 参数时(由 equals 方法确定),返回 true;否则返回 false
抛出:
NullPointerException - 如果指定值为 null

put

public V put(K key,
             V value)
将指定键映射到此表中的指定值。键和值都不可以为 null

通过使用与原来的键相同的键调用 get 方法,可以获取相应的值。

指定者:
接口 Map<K,V> 中的 put
覆盖:
AbstractMap<K,V> 中的 put
参数:
key - 与指定值相关联的键
value - 与指定键相关联的值
返回:
以前与 key 相关联的值,如果 key 没有映射关系,则返回 null
抛出:
NullPointerException - 如果指定键或值为 null

putIfAbsent

public V putIfAbsent(K key,
                     V value)
如果指定键已经不再与某个值相关联,则将它与给定值关联。这等价于:
   if (!map.containsKey(key)) 
      return map.put(key, value);
  else
       return map.get(key);
除了原子地执行此操作之外。

指定者:
接口 ConcurrentMap<K,V> 中的 putIfAbsent
参数:
key - 与指定值相关联的键
value - 与指定键相关联的值
返回:
以前与指定键相关联的值,如果该键没有映射关系,则返回 null
抛出:
NullPointerException - 如果指定键或值为 null

putAll

public void putAll(Map<? extends K,? extends V> m)
将指定映射中所有映射关系复制到此映射中。针对指定映射中的当前所有键,这些映射关系将替换此映射中具有的所有映射关系。

指定者:
接口 Map<K,V> 中的 putAll
覆盖:
AbstractMap<K,V> 中的 putAll
参数:
m - 将存储在此映射中的映射关系

remove

public V remove(Object key)
从此映射中移除键(及其相应的值)。如果该键不在映射中,则此方法不执行任何操作。

指定者:
接口 Map<K,V> 中的 remove
覆盖:
AbstractMap<K,V> 中的 remove
参数:
key - 需要移除的键
返回:
key 关联的先前值;如果 key 没有映射关系,则返回 null
抛出:
NullPointerException - 如果指定键为 null

remove

public boolean remove(Object key,
                      Object value)
只有目前将键的条目映射到给定值时,才移除该键的条目。这等效于:
   if (map.containsKey(key) && map.get(key).equals(value)) {
       map.remove(key);
       return true;
   } else return false;
不同之处在于该操作是以原子方式 (atomically) 执行的。

指定者:
接口 ConcurrentMap<K,V> 中的 remove
参数:
key - 与指定值相关联的键
value - 期望与指定键相关联的值
返回:
如果该值被移除,则返回 true
抛出:
NullPointerException - 如果指定键为 null

replace

public boolean replace(K key,
                       V oldValue,
                       V newValue)
只有目前将键的条目映射到给定值时,才替换该键的条目。这等效于:
   if (map.containsKey(key) && map.get(key).equals(oldValue)) {
       map.put(key, newValue);
       return true;
   } else return false;
不同之处在于该操作是以原子方式执行的。

指定者:
接口 ConcurrentMap<K,V> 中的 replace
参数:
key - 与指定值相关联的键
oldValue - 期望与指定键相关联的值
newValue - 与指定键相关联的值
返回:
如果该值被替换,则返回 true
抛出:
NullPointerException - 如果任何参数为 null

replace

public V replace(K key,
                 V value)
只有目前将键的条目映射到某一值时,才替换该键的条目。这等效于:
   if (map.containsKey(key)) {
       return map.put(key, value);
   } else return null;
不同之处在于该操作是以原子方式执行的。

指定者:
接口 ConcurrentMap<K,V> 中的 replace
参数:
key - 与指定值相关联的键
value - 与指定键相关联的值
返回:
与指定键关联的先前值;如果没有该键的映射关系,则返回 null
抛出:
NullPointerException - 如果指定键或值为 null

clear

public void clear()
从该映射中移除所有映射关系

指定者:
接口 Map<K,V> 中的 clear
覆盖:
AbstractMap<K,V> 中的 clear

keySet

public Set<K> keySet()
返回此映射中包含的键的 Set 视图。该 set 受映射支持,所以对映射的改变可在该 set 中反映出来,反之亦然。该 set 支持元素的移除,它通过 Iterator.removeSet.removeremoveAllretainAllclear 操作,从此映射中移除相应的映射关系。它不支持 addaddAll 操作。

该视图的 iterator 是一个“弱一致”的迭代器,它从来不会抛出 ConcurrentModificationException,并且确保可遍历迭代器构造时存在的元素,此外还可能(但并不保证)反映构造后的所有修改。

指定者:
接口 Map<K,V> 中的 keySet
覆盖:
AbstractMap<K,V> 中的 keySet
返回:
此映射中包含的键的 set 视图

values

public Collection<V> values()
返回此映射中包含的值的 Collection 视图。该 collection 受映射支持,所以对映射的改变可在该 collection 中反映出来,反之亦然。该 collection 支持元素的移除,它通过 Iterator.removeCollection.removeremoveAllretainAllclear 操作,从此映射中移除相应的映射关系。它不支持 addaddAll 操作。

该视图的 iterator 是一个“弱一致”迭代器,它不会抛出 ConcurrentModificationException,并且确保可遍历迭代器构造时存在的元素,此外还可能(但并不保证)反映构造后的所有修改。

指定者:
接口 Map<K,V> 中的 values
覆盖:
AbstractMap<K,V> 中的 values
返回:
此映射中包含的值的 collection 视图

entrySet

public Set<Map.Entry<K,V>> entrySet()
返回此映射所包含的映射关系的 Set 视图。该 set 受映射支持,所以对映射的改变可在该 set 中反映出来,反之亦然。该 set 支持元素的移除,它通过 Iterator.removeSet.removeremoveAllretainAllclear 操作,从此映射中移除相应的映射关系。它不支持 addaddAll 操作。

该视图的返回的 iterator 是一个“弱一致”迭代器,它不会抛出 ConcurrentModificationException,并且确保可遍历迭代器构造时存在的元素,此外还可能(但并不保证)反映构造后的所有修改。

指定者:
接口 Map<K,V> 中的 entrySet
指定者:
AbstractMap<K,V> 中的 entrySet
返回:
此映射中包含的映射关系的 set 视图

keys

public Enumeration<K> keys()
返回此表中键的枚举。

返回:
此表中键的枚举
另请参见:
keySet()

elements

public Enumeration<V> elements()
返回此表中值的枚举。

返回:
此表中值的枚举
另请参见:
values()

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策