java.util
类 WeakHashMap<K,V>

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.WeakHashMap<K,V>

类型参数：

K - 此映射所维护的键的类型

V - 映射值的类型

所有已实现的接口：

Map<K,V>

public class WeakHashMap<K,V>
extends AbstractMap<K,V>
implements Map<K,V>

以弱键 实现的基于哈希表的 Map。在 WeakHashMap 中，当某个键不再正常使用时，将自动移除其条目。更精确地说，对于一个给定的键，其映射的存在并不阻止垃圾回收器对该键的丢弃，这就使该键成为可终止的，被终止，然后被回收。丢弃某个键时，其条目从映射中有效地移除，因此，该类的行为与其他的 Map 实现有所不同。

null 值和 null 键都被支持。该类具有与 HashMap 类相似的性能特征,并具有相同的效能参数初始容量 和加载因子。

像大多数 collection 类一样，该类是不同步的。可以使用 Collections.synchronizedMap 方法来构造同步的 WeakHashMap。

该类主要与这样的键对象一起使用，其 equals 方法使用 == 运算符来测试对象标识。一旦这种键被丢弃，就永远无法再创建了，所以，过段时间后在 WeakHashMap 中查找此键是不可能的，不必对其项已移除而感到惊讶。该类十分适合与 equals 方法不是基于对象标识的键对象一起使用，比如，String 实例。然而，对于这种可重新创建的键对象，键若丢弃，就自动移除 WeakHashMap 条目，这种表现令人疑惑。

WeakHashMap 类的行为部分取决于垃圾回收器的动作，所以，几个常见的（虽然不是必需的）Map 常量不支持此类。因为垃圾回收器在任何时候都可能丢弃键，WeakHashMap 就像是一个被悄悄移除条目的未知线程。特别地，即使对 WeakHashMap 实例进行同步，并且没有调用任何赋值方法，在一段时间后 size 方法也可能返回较小的值，对于 isEmpty 方法，返回 false，然后返回 true，对于给定的键，containsKey 方法返回 true 然后返回 false，对于给定的键，get 方法返回一个值，但接着返回 null，对于以前出现在映射中的键，put 方法返回 null，而 remove 方法返回 false，对于键 set、值 collection 和条目 set 进行的检查，生成的元素数量越来越少。

WeakHashMap 中的每个键对象间接地存储为一个弱引用的指示对象。因此，不管是在映射内还是在映射之外，只有在垃圾回收器清除某个键的弱引用之后，该键才会自动移除。

实现注意事项：WeakHashMap 中的值对象由普通的强引用保持。因此应该小心谨慎，确保值对象不会直接或间接地强引用其自身的键，因为这会阻止键的丢弃。注意，值对象可以通过 WeakHashMap 本身间接引用其对应的键；这就是说，某个值对象可能强引用某个其他的键对象，而与该键对象相关联的值对象转而强引用第一个值对象的键。处理此问题的一种方法是，在插入前将值自身包装在 WeakReferences 中，如：m.put(key, new WeakReference(value))，然后，分别用 get 进行解包。

collection 的 iterator 方法所返回的迭代器（由该类所有“collection 视图方法”返回）均是快速失败的：在迭代器创建之后，如果从结构上对映射进行修改，除非通过迭代器自身的 remove 或 add 方法,其他任何时间任何方式的修改，迭代器都将抛出 ConcurrentModificationException。因此，面对并发的修改，迭代器很快就完全失败，而不是冒着在将来不确定的时间任意发生不确定行为的风险。

注意，迭代器的快速失败行为不能得到保证，一般来说，存在不同步的并发修改时，不可能作出任何坚决的保证。快速失败迭代器尽最大努力抛出 ConcurrentModificationException。因此，编写依赖于此异常程序的方式是错误的，正确做法是：迭代器的快速失败行为应该仅用于检测 bug。

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.2

另请参见：

HashMap, WeakReference

WeakHashMap

public WeakHashMap(int initialCapacity,
                   float loadFactor)

用给定的初始容量和加载因子构造一个新的空 WeakHashMap。

参数：

initialCapacity - WeakHashMap 的初始容量

loadFactor - WeakHashMap 的加载因子

抛出：

IllegalArgumentException - 如果初始容量为负，或加载因子为非正。

WeakHashMap

public WeakHashMap(int initialCapacity)

构造具有给定初始容量和默认加载因子 (0.75) 的新的空 WeakHashMap。

参数：

initialCapacity - WeakHashMap 的初始容量

抛出：

IllegalArgumentException - 如果初始容量为负

WeakHashMap

public WeakHashMap()

构造具有默认初始容量 (16) 和加载因子 (0.75) 的新的空 WeakHashMap。

WeakHashMap

public WeakHashMap(Map<? extends K,? extends V> m)

构造一个新 WeakHashMap，使其与指定的映射具有相同的映射关系。创建具有默认加载因子 (0.75) 的 WeakHashMap，初始容量足以容纳指定映射中的映射关系。

参数：

m - 映射，其映射关系将存放在此映射中

抛出：

NullPointerException - 如果指定的映射为 null

从以下版本开始：

1.3

size

public int size()

返回该映射中的键-值映射关系的数目。此结果是个快照，可能无法反映未处理的项，这些项因为不再引用而在下次试图访问前被移除。

指定者：

接口 Map<K,V> 中的 size

覆盖：

类 AbstractMap<K,V> 中的 size

返回：

此映射中的键-值映射关系数

isEmpty

public boolean isEmpty()

如果此映射不包含键-值映射关系，则返回 true。此结果是个快照，可能无法反映未处理的项，这些项因为不再引用而在下次访问前被移除。

指定者：

接口 Map<K,V> 中的 isEmpty

覆盖：

类 AbstractMap<K,V> 中的 isEmpty

返回：

如果此映射未包含键-值映射关系，则返回 true

get

public V get(Object key)

返回指定键所映射的值，如果对于该键来说，此映射不包含任何映射关系，则返回 null。

更确切地讲，如果此映射包含一个满足以下条件的从键 k 到值 v 的映射关系：(key==null ? k==null : key.equals(k))，则此方法返回 v；否则它返回 null。（最多只能有一个这样的映射关系）。

返回值为 null 并不一定 表示映射不包含该键的任何映射关系；也可能是映射显式地将键映射到 null。使用 containsKey 操作可以区分这两种情况。

指定者：

接口 Map<K,V> 中的 get

覆盖：

类 AbstractMap<K,V> 中的 get

参数：

key - 要返回其关联值的键

返回：

指定键所映射的值；如果此映射不包含该键的映射关系，则返回 null

另请参见：

put(Object, Object)

containsKey

public boolean containsKey(Object key)

如果此映射对于指定的键包含映射关系，则返回 true。

指定者：

接口 Map<K,V> 中的 containsKey

覆盖：

类 AbstractMap<K,V> 中的 containsKey

参数：

key - 要测试其是否在此映射中存在的键

返回：

如果有 key 的映射关系，则返回 true，否则返回 false。

put

public V put(K key,
             V value)

关联此映射中的指定值与指定键。如果此映射以前包含了一个该键的映射关系，则替换旧值。

指定者：

接口 Map<K,V> 中的 put

覆盖：

类 AbstractMap<K,V> 中的 put

参数：

key - 指定值将要关联的键。

value - 指定键将要关联的值。

返回：

返回与 key 关联的先前值，如果 key 没有任何映射关系，则返回 null。（返回 null 还可以表示该映射以前关联了 null 与 key）。

putAll

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

将指定映射的全部映射关系复制到此映射。这些映射关系将替换此映射针对当前指定映射中任何键所具有的任何映射关系。

指定者：

接口 Map<K,V> 中的 putAll

覆盖：

类 AbstractMap<K,V> 中的 putAll

参数：

m - 要在此映射中存储的映射关系。

抛出：

NullPointerException - 如果指定的映射为 null。

remove

public V remove(Object key)

从此弱哈希映射中移除键的映射关系（如果存在）。更确切地讲，如果此映射包含一个满足以下条件的从键 k 到值 v 的映射关系：(key==null ? k==null : key.equals(k))，则移除该映射关系。（该映射最多只能包含一个这样的映射关系）。

返回此映射先前与该键关联的值，如果映射不包含该键的任何映射关系，则返回 null。返回值为 null 并不一定 表示映射不包含该键的任何映射关系；也可能是映射显式地将键映射到 null。

一旦调用返回，则该映射将不再包含指定键的映射关系。

指定者：

接口 Map<K,V> 中的 remove

覆盖：

类 AbstractMap<K,V> 中的 remove

参数：

key - 其映射关系要从映射中移除的键

返回：

与 key 相关联的先前值，如果 key 没有任何映射关系，则返回 null

clear

public void clear()

从此映射中移除所有映射关系。此调用返回后，该映射将是空的。

指定者：

接口 Map<K,V> 中的 clear

覆盖：

类 AbstractMap<K,V> 中的 clear

containsValue

public boolean containsValue(Object value)

如果此映射将一个或多个键映射到指定值，则返回 true。

指定者：

接口 Map<K,V> 中的 containsValue

覆盖：

类 AbstractMap<K,V> 中的 containsValue

参数：

value - 要测试其是否在此映射中存在的值

返回：

如果此映射将一个或多个键映射到指定值，则返回 true

keySet

public Set<K> keySet()

返回此映射所包含的键的 Set 视图。该 set 受映射支持，所以对映射的改变可在此 set 中反映出来，反之亦然。如果在该 set 上进行迭代时修改该映射（通过迭代器自己的 remove 操作除外），则迭代结果是不确定的。该 set 支持元素的移除，通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作可从该映射移除相应的映射关系。它不支持 add 或 addAll 操作。

指定者：

接口 Map<K,V> 中的 keySet

覆盖：

类 AbstractMap<K,V> 中的 keySet

返回：

此映射中包含的键的 set 视图

values

public Collection<V> values()

返回此映射所包含的值的 Collection 视图。该 collection 受映射支持，所以对映射的改变可在该 collection 中反映出来，反之亦然。如果在该 collection 上进行迭代时修改该映射（通过迭代器自己的 remove 操作除外），则迭代结果是不确定的。该 collection 支持元素的移除，通过 Iterator.remove、Collection.remove、removeAll、retainAll 和 clear 操作可从该映射中移除相应的映射关系。它不支持 add 或 addAll 操作。

指定者：

接口 Map<K,V> 中的 values

覆盖：

类 AbstractMap<K,V> 中的 values

返回：

此映射中包含的值的 collection 视图

entrySet

public Set<Map.Entry<K,V>> entrySet()

返回此映射所包含的映射关系的 Set 视图。该 set 受映射支持，所以对映射的改变可在此 set 中反映出来，反之亦然。如果在该 set 上进行迭代时修改该映射（通过迭代器自己的 remove 操作，或者通过迭代器所返回的映射项上的 setValue 操作除外），则迭代结果是不确定的。该 set 支持元素的移除，通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作，从该映射移除相应的映射关系。它不支持 add 或 addAll 操作。

指定者：

接口 Map<K,V> 中的 entrySet

指定者：

类 AbstractMap<K,V> 中的 entrySet

返回：

此映射中包含的映射关系的 set 视图

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