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

巢狀類別摘要

從類別 java.util.AbstractMap 繼承的巢狀類別/介面

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

建構子摘要

WeakHashMap()
建構具有預設初始容量 (16) 和載入因子 (0.75) 的新的空 WeakHashMap。

WeakHashMap(int initialCapacity)
建構具有給定初始容量和預設載入因子 (0.75) 的新的空 WeakHashMap。

WeakHashMap(int initialCapacity, float loadFactor)
用給定的初始容量和載入因子建構一個新的空 WeakHashMap。

WeakHashMap(Map<? extends K,? extends V> m)
建構一個新 WeakHashMap，使其與指定的映射具有相同的映射關係。

方法摘要

void	clear() 從此映射中移除所有映射關係。
boolean	containsKey(Object key) 如果此映射對於指定的鍵包含映射關係，則返回 true。
boolean	containsValue(Object value) 如果此映射將一個或多個鍵映射到指定值，則返回 true。
Set<Map.Entry<K,V>>	entrySet() 返回此映射所包含的映射關係的 Set 視圖。
V	get(Object key) 返回指定鍵所映射的值，如果對於該鍵來說，此映射不包含任何映射關係，則返回 null。
boolean	isEmpty() 如果此映射不包含鍵-值映射關係，則返回 true。
Set<K>	keySet() 返回此映射所包含的鍵的 Set 視圖。
V	put(K key, V value) 關聯此映射中的指定值與指定鍵。
void	putAll(Map<? extends K,? extends V> m) 將指定映射的全部映射關係複製到此映射。
V	remove(Object key) 從此弱雜湊映射中移除鍵的映射關係（如果存在）。
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

建構子詳細資訊

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 視圖