java.util
類別 IdentityHashMap<K,V>

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

所有已實作的介面：

Serializable, Cloneable, Map<K,V>

public class IdentityHashMap<K,V>
extends AbstractMap<K,V>
implements Map<K,V>, Serializable, Cloneable

此類別利用雜湊表實作 Map 介面，比較鍵（和值）時使用參考相等性代替物件相等性。換句話說，在 IdentityHashMap 中，當且僅當 (k1==k2) 時，才認為兩個鍵 k1 和 k2 相等（在正常 Map 實作（如 HashMap）中，當且僅當滿足下列條件時才認為兩個鍵 k1 和 k2 相等：(k1==null ? k2==null : e1.equals(e2))）。

此類別不是 通用 Map 實作！此類別實作 Map 介面時，它有意違反 Map 的常規協定，該協定在比較物件時強制使用 equals 方法。此類別設計僅用於其中需要參考相等性語義的罕見情況。

此類別的典型用法是拓撲保留物件圖形轉換，如序列化或深層複製。要執行這樣的轉換，程序必須維護用於追蹤所有已處理物件參考的「節點表」。節點表一定不等於不同物件，即使它們偶然相等也如此。此類別的另一種典型用法是維護代理物件。例如，除錯設施可能希望為正在除錯程序中的每個物件維護代理物件。

此類別提供所有的可選映射操作，並且允許 null 值和 null 鍵。此類別對映射的順序不提供任何保證；特別是不保證順序隨時間的推移保持不變。

此類別提供基本操作（get 和 put）的穩定性能，假定系統標識了將桶間元素正確分開的雜湊函數 (System.identityHashCode(Object))。

此類別具有一個調整參數（影響性能但不影響語義）：expected maximum size。此參數是希望映射保持的鍵值映射關係最大數。在內部，此參數用於確定最初組成雜湊表的桶數。未指定所期望的最大數量和桶數之間的確切關係。

如果映射的大小（鍵值映射關係數）已經超過期望的最大數量，則桶數會增加，增加桶數（「重新雜湊」）可能相當昂貴，因此創建具有足夠大的期望最大數量的標識雜湊映射更合算。另一方面，對 collection 視圖進行迭代所需的時間與雜湊表中的桶數成正比，所以如果特別注重迭代性能或記憶體使用，則不宜將期望的最大數量設置得過高。

注意，此實作不是同步的。如果多個執行緒同時存取標識雜湊映射，並且其中至少一個執行緒從結構上修改了該映射，則其必須 保持外部同步（結構上的修改是指添加或刪除一個或多個映射關係的操作；僅改變與實例已經包含的鍵關聯的值不是結構上的修改。）這一般通過對自然封裝該映射的物件進行同步操作來完成。 如果不存在這樣的物件，則應該使用 Collections.synchronizedMap 方法來「包裹」該映射。最好在創建時完成這一操作，以防止對映射進行意外的不同步存取，如下所示：

     Map m = Collections.synchronizedMap(new HashMap(...)); 

由所有此類別的「collection 視圖方法」所返回的collections的iterator 方法返回的迭代器都是快速失敗 的：在迭代器創建之後，如果從結構上對映射進行修改，除非通過迭代器自身的 remove 或 add 方法，其他任何時間任何方式的修改，迭代器都將拋出 ConcurrentModificationException。因此，面對共時的修改，迭代器很快就會完全失敗，而不冒在將來不確定的時間任意發生不確定行為的風險。

注意，迭代器的快速失敗行為不能得到保證，一般來說，存在不同步的共時修改時，不可能作出任何強有力的保證。快速失敗迭代器盡最大努力拋出 ConcurrentModificationException。因此，編寫依賴於此異常的程序的方式是錯誤的，正確做法是：迭代器的快速失敗行為應該僅用於檢測程序錯誤。

實作注意事項：此為簡單的線性探頭 雜湊表，如 Sedgewick 和 Knuth 原文範例中所述。該陣列交替保持鍵和值（對於大型表來說，它比使用獨立組保持鍵和值更具優勢）。對於多數 JRE 實作和混合操作，此類別比 HashMap（它使用鏈 而不使用線性探頭）能產生更好的性能。

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.4

另請參見：

System.identityHashCode(Object), Object.hashCode(), Collection, Map, HashMap, TreeMap, 序列化表格

巢狀類別摘要

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

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

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

Map.Entry<K,V>

建構子摘要

IdentityHashMap()
建構一個具有預設期望最大數量 (21) 的新的空標識雜湊映射。

IdentityHashMap(int expectedMaxSize)
建構一個具有指定期望最大數量的新的空映射。

IdentityHashMap(Map<? extends K,? extends V> m)
建構包含指定映射中鍵-值映射關係的新標識雜湊映射。

方法摘要

void	clear() 從映射中移除所有映射關係。
Object	clone() 返回此標識雜湊映射的淺表副本：不複製鍵和值本身。
boolean	containsKey(Object key) 測試指定的物件參考是否為此標識雜湊映射中的鍵。
boolean	containsValue(Object value) 測試指定的物件參考是否為此標識雜湊映射中的值。
Set<Map.Entry<K,V>>	entrySet() 返回此映射所包含映射關係的 Set 視圖。
boolean	equals(Object o) 比較指定對象與此映射的相等性。
V	get(Object key) 返回指定鍵映射的值；如果映射不包含此鍵的任何映射關係，則返回 null。
int	hashCode() 返回映射的雜湊碼值。
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 繼承的方法

toString

從類別 java.lang.Object 繼承的方法

finalize, getClass, notify, notifyAll, wait, wait, wait

建構子詳細資訊

IdentityHashMap

public IdentityHashMap()

建構一個具有預設期望最大數量 (21) 的新的空標識雜湊映射。

IdentityHashMap

public IdentityHashMap(int expectedMaxSize)

建構一個具有指定期望最大數量的新的空映射。將多於期望數的鍵-值映射關係放置到映射中可能會導致內部資料結構的增長，這種增長是頗為耗時的。

參數：

expectedMaxSize - 映射的期望最大數量

拋出：

IllegalArgumentException - 如果 expectedMaxSize 是負數

IdentityHashMap

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

建構包含指定映射中鍵-值映射關係的新標識雜湊映射。

參數：

m - 要將其映射關係放置在此映射中的映射

拋出：

NullPointerException - 如果指定的映射為 null

方法詳細資訊

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。

更確切地講，如果此映射包含滿足 (key == k) 的從鍵 k 到值 v 的映射關係，則此方法返回 v；否則，返回 null。（最多只能有一個這樣的映射關係。）

返回值為 null 並不一定 表示映射不包含此鍵的映射關係；也可能是映射顯式地將鍵映射到 null。使用 containsKey 方法可以區分這兩種情況。

指定者：

介面 Map<K,V> 中的 get

覆寫：

類別 AbstractMap<K,V> 中的 get

參數：

key - 要返回其關聯值的鍵

返回：

指定鍵所映射的值；如果此映射不包含該鍵的映射關係，則返回 null

另請參見：

put(Object, Object)

containsKey

public boolean containsKey(Object key)

測試指定的物件參考是否為此標識雜湊映射中的鍵。

指定者：

介面 Map<K,V> 中的 containsKey

覆寫：

類別 AbstractMap<K,V> 中的 containsKey

參數：

key - 可能的鍵

返回：

如果指定的物件參考是此映射中的鍵，則返回 true

另請參見：

containsValue(Object)

containsValue

public boolean containsValue(Object value)

測試指定的物件參考是否為此標識雜湊映射中的值。

指定者：

介面 Map<K,V> 中的 containsValue

覆寫：

類別 AbstractMap<K,V> 中的 containsValue

參數：

value - 要測試其是否在此映射中存在的值

返回：

如果此映射將一個或多個鍵映射到指定物件參考，則返回 true

另請參見：

containsKey(Object)

put

public V put(K key,
             V value)

在此標識雜湊映射中關聯指定值與指定鍵。如果映射以前包含了一個此鍵的映射關係，那麼將替換舊值。

指定者：

介面 Map<K,V> 中的 put

覆寫：

類別 AbstractMap<K,V> 中的 put

參數：

key - 要將指定值關聯到的鍵

value - 要關聯到指定鍵的值

返回：

返回與 key 相關聯的先前值，如果 key 沒有映射關係，則返回 null（返回 null 可能還表示映射以前將 null 與指定鍵關聯）

另請參見：

Object.equals(Object), get(Object), containsKey(Object)

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)

移除映射中此鍵的映射關係（如果存在的話）。

指定者：

介面 Map<K,V> 中的 remove

覆寫：

類別 AbstractMap<K,V> 中的 remove

參數：

key - 其映射關係要從映射中移除的鍵

返回：

返回與 key 相關聯的先前值，如果 key 沒有任何映射關係，則返回 null（返回 null 還客表示映射以前將 null 與 key 關聯）。

clear

public void clear()

從映射中移除所有映射關係。 此調用返回後映射將為空。

指定者：

介面 Map<K,V> 中的 clear

覆寫：

類別 AbstractMap<K,V> 中的 clear

equals

public boolean equals(Object o)

比較指定對象與此映射的相等性。如果給定對象也是一個映射並且兩個映射表示相同的物件參考映射關係，則返回 true。更確切地講，當且僅當映射 this.entrySet().equals(m.entrySet()) 時，此映射等於另一個映射 m。

由於此映射基於參考相等性的語義，所以如果將此映射與正常映射相比，則可能違反 Object.equals 協定的對稱性和傳遞性要求。但是，需要保證在 IdentityHashMap 實例間遵守 Object.equals 協定。

指定者：

介面 Map<K,V> 中的 equals

覆寫：

類別 AbstractMap<K,V> 中的 equals

參數：

o - 要與此映射進行相等性比較的物件

返回：

如果指定物件等於此映射，則返回 true

另請參見：

Object.equals(Object)

hashCode

public int hashCode()

返回映射的雜湊碼值。映射的雜湊碼被定義為該映射 entrySet() 視圖中所有項的雜湊碼和。這確保了 m1.equals(m2) 意味著對於任何兩個 IdentityHashMap 實例 m1 和 m2 而言，都存在 m1.hashCode()==m2.hashCode()，這是 Object.hashCode() 的通用協定的所要求的。

由於此映射的 entrySet 方法所返回 set 中 Map.Entry 實例的基於參考相等性的語義，所以如果進行比較的兩個物件中一個是 IdentityHashMap 實例，而另一個是正常映射，則可能違反以上段落中提到的 Object.hashCode 的協定要求。

指定者：

介面 Map<K,V> 中的 hashCode

覆寫：

類別 AbstractMap<K,V> 中的 hashCode

返回：

此映射的雜湊碼值

另請參見：

Object.equals(Object), equals(Object)

clone

public Object clone()

返回此標識雜湊映射的淺表副本：不複製鍵和值本身。

覆寫：

類別 AbstractMap<K,V> 中的 clone

返回：

此映射的淺表副本

另請參見：

Cloneable

keySet

public Set<K> keySet()

返回映射中所包含鍵的基於標識的 set 視圖。該 set 受映射支持，所以對映射的改變可在此 set 中反映出來，反之亦然。如果在對 set 進行迭代的同時修改映射，則迭代的結果是未定義的。該 set 支持元素的移除，通過 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 方法可從映射中移除相應的映射關係。它不支持 add 或 addAll 方法。

此方法返回的物件實作 Set 介面時，它不 遵守 Set 的常規協定。與其底層映射一樣，此方法返回的 set 將元素相等性定義為參考相等性，而非物件相等性。這一點將對其 contains、remove、containsAll、equals 和 hashCode 方法的行為產生影響。

如果指定物件是一個套件含與返回 set 完全相同的物件參考的 set，則返回 set 的 equals 方法將返回 true。如果將此方法返回的 set 與正常 set 相比較，則可能違反 Object.equals 協定的對稱性和傳遞性要求。但是，需要保證在此方法返回的 set 中遵守 Object.equals 協定。

返回 set 的 hashCode 方法返回該 set 中元素的標識雜湊碼 和，而不是其雜湊碼的和。為了強制遵守此方法所返回 set 中 Object.hashCode 方法的常規協定，需要通過更改 equals 方法的語義來強制完成。

指定者：

介面 Map<K,V> 中的 keySet

覆寫：

類別 AbstractMap<K,V> 中的 keySet

返回：

映射所含鍵的基於標識的 set 視圖

另請參見：

Object.equals(Object), System.identityHashCode(Object)

values

public Collection<V> values()

返回映射所包含值的 Collection 視圖。該 collection 受映射的支持，所以對映射的改變可在此 collection 中反映出來，反之亦然。如果在對 collection 進行迭代的同時修改映射，則迭代的結果是未定義的。該 collection 支持元素的移除，通過 Iterator.remove、Collection.remove、removeAll、retainAll 和 clear 方法可從該映射中移除相應的映射關係。它不支持 add 或 addAll 方法。

此方法返回的物件實作 Collection 介面時，它不 遵守 Collection 的常規協定。與其底層映射一樣，此方法返回的 collection 將元素相等性定義為參考相等性，而非物件相等性。這一點將對其 contains、remove 和 containsAll 方法的行為產生影響。

指定者：

介面 Map<K,V> 中的 values

覆寫：

類別 AbstractMap<K,V> 中的 values

返回：

此映射中包含的值的 collection 視圖

entrySet

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

返回此映射所包含映射關係的 Set 視圖。在返回的 set 中，每個元素都是一個基於參考相等性的 Map.Entry。該 set 受映射支持，所以對映射的改變可在此 set 中反映出來，反之亦然。如果在對 set 進行迭代的同時修改映射，則迭代的結果是未定義的。該 set 支持元素的移除，通過 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 方法可從此映射移除相應的映射關係。它不支持 add 或 addAll 方法。

與底層映射一樣，此方法所返回 set 中的 Map.Entry 物件將鍵和值的相等性定義為參考相等性，而非物件相等性。這一點將對 Map.Entry 物件的 equals 和 hashCode 方法的行為產生影響。當且僅當 o 為 Map.Entry 並且 e.getKey()==o.getKey() && e.getValue()==o.getValue() 時，基於參考相等性的 Map.Entry e 等於物件 o。為了適應這些相等語義，hashCode 方法返回 System.identityHashCode(e.getKey()) ^ System.identityHashCode(e.getValue())。

由於此方法所返回 set 中 Map.Entry 實例的基於參考相等性的語義，所以如果將該 set 中的任何項與正常映射項相比較，或者將此方法返回的 set 與正常映射項（比如在正式映射上對此方法的調用所返回的項）的 set 相比較，則可能違反 Object.equals(Object) 協定的對稱性和傳遞性要求。但是，需要保證在基於標識的映射項中和在這些項的 set 中遵守 Object.equals 協定。

指定者：

介面 Map<K,V> 中的 entrySet

指定者：

類別 AbstractMap<K,V> 中的 entrySet

返回：

此映射所含標識映射關係的 set 視圖