java.util
類別 Hashtable<K,V>

java.lang.Object
  java.util.Dictionary<K,V>
      java.util.Hashtable<K,V>

所有已實作的介面：

Serializable, Cloneable, Map<K,V>

直接已知子類別：

Properties, UIDefaults

public class Hashtable<K,V>
extends Dictionary<K,V>
implements Map<K,V>, Cloneable, Serializable

此類別實作一個雜湊表，該雜湊表將鍵映射到相應的值。任何非 null 物件都可以用作鍵或值。

為了成功地在雜湊表中存儲和獲取物件，用作鍵的物件必須實作 hashCode 方法和 equals 方法。

Hashtable 的實例有兩個參數影響其性能：初始容量 和載入因子。容量 是雜湊表中桶 的數量，初始容量 就是雜湊表創建時的容量。注意，雜湊表的狀態為 open：在發生「雜湊衝突」的情況下，單個桶會存儲多個條目，這些條目必須按順序搜尋。載入因子 是對雜湊表在其容量自動增加之前可以達到多滿的一個尺度。初始容量和載入因子這兩個參數只是對該實作的提示。關於何時以及是否調用 rehash 方法的具體細節則依賴於該實作。

通常，預設載入因子(.75)在時間和空間成本上尋求一種折衷。載入因子過高雖然減少了空間開銷，但同時也增加了尋找某個條目的時間（在大多數 Hashtable 操作中，包括 get 和 put 操作，都反映了這一點）。

初始容量主要控制空間消耗與執行 rehash 操作所需要的時間損耗之間的平衡。如果初始容量大於 Hashtable 所包含的最大條目數除以載入因子，則永遠 不會發生 rehash 操作。但是，將初始容量設置太高可能會浪費空間。

如果很多條目要存儲在一個 Hashtable 中，那麼與根據需要執行自動 rehashing 操作來增大表的容量的做法相比，使用足夠大的初始容量創建雜湊表或許可以更有效地插入條目。

下面這個範例創建了一個數字的雜湊表。它將數字的名稱用作鍵：

   Hashtable<String, Integer> numbers
     = new Hashtable<String, Integer>();
   numbers.put("one", 1);
   numbers.put("two", 2);
   numbers.put("three", 3);

要獲取一個數字，可以使用以下程式碼：

   Integer n = numbers.get("two");
     if (n != null) {
         System.out.println("two = " + n);
     }
   }

由全部類別的「collection 視圖方法」返回的 collection 的 iterator 方法返回的迭代器都是快速失敗 的：在創建 Iterator 之後，如果從結構上對 Hashtable 進行修改，除非通過 Iterator 自身的 remove 方法，否則在任何時間以任何方式對其進行修改，Iterator 都將拋出ConcurrentModificationException。因此，面對共時的修改，Iterator 很快就會完全失敗，而不冒在將來某個不確定的時間發生任意不確定行為的風險。由 Hashtable 的鍵和元素方法返回的 Enumeration 不 是快速失敗的。

注意，迭代器的快速失敗行為無法得到保證，因為一般來說，不可能對是否出現不同步共時修改做出任何硬性保證。快速失敗迭代器會盡最大努力拋出 ConcurrentModificationException。因此，為提高這類別迭代器的正確性而編寫一個依賴於此異常的程序是錯誤做法：迭代器的快速失敗行為應該僅用於檢測程序錯誤。

從Java 2 平臺 v1.2起，此類別就被改進以實作 Map 介面，使它成為 Java Collections Framework 中的一個成員。不像新的 collection 實作，Hashtable 是同步的

從以下版本開始：

JDK1.0

另請參見：

Object.equals(java.lang.Object), Object.hashCode(), rehash(), Collection, Map, HashMap, TreeMap, 序列化表格

建構子摘要

Hashtable()
用預設的初始容量 (11) 和載入因子 (0.75) 建構一個新的空雜湊表。

Hashtable(int initialCapacity)
用指定初始容量和預設的載入因子 (0.75) 建構一個新的空雜湊表。

Hashtable(int initialCapacity, float loadFactor)
用指定初始容量和指定載入因子建構一個新的空雜湊表。

Hashtable(Map<? extends K,? extends V> t)
建構一個與給定的 Map 具有相同映射關係的新雜湊表。

方法摘要

void	clear() 將此雜湊表清空，使其不包含任何鍵。
Object	clone() 創建此雜湊表的淺表副本。
boolean	contains(Object value) 測試此映射表中是否存在與指定值關聯的鍵。
boolean	containsKey(Object key) 測試指定物件是否為此雜湊表中的鍵。
boolean	containsValue(Object value) 如果此 Hashtable 將一個或多個鍵映射到此值，則返回 true。
Enumeration<V>	elements() 返回此雜湊表中的值的列舉。
Set<Map.Entry<K,V>>	entrySet() 返回此映射中包含的鍵的 Set 視圖。
boolean	equals(Object o) 按照 Map 介面的定義，比較指定 Object 與此 Map 是否相等。
V	get(Object key) 返回指定鍵所映射到的值，如果此映射不包含此鍵的映射，則返回 null. 更確切地講，如果此映射包含滿足 (key.equals(k)) 的從鍵 k 到值 v 的映射，則此方法返回 v；否則，返回 null。
int	hashCode() 按照 Map 介面的定義，返回此 Map 的雜湊碼值。
boolean	isEmpty() 測試此雜湊表是否沒有鍵映射到值。
Enumeration<K>	keys() 返回此雜湊表中的鍵的列舉。
Set<K>	keySet() 返回此映射中包含的鍵的 Set 視圖。
V	put(K key, V value) 將指定 key 映射到此雜湊表中的指定 value。
void	putAll(Map<? extends K,? extends V> t) 將指定映射的所有映射關係複製到此雜湊表中，這些映射關係將替換此雜湊表擁有的、針對當前指定映射中所有鍵的所有映射關係。
protected void	rehash() 增加此雜湊表的容量並在內部對其進行重組，以便更有效地容納和存取其元素。
V	remove(Object key) 從雜湊表中移除該鍵及其相應的值。
int	size() 返回此雜湊表中的鍵的數量。
String	toString() 返回此 Hashtable 物件的字元串表示形式，其形式為 ASCII 字元 ", " （逗號加空格）分隔開的、括在括號中的一組條目。
Collection<V>	values() 返回此映射中包含的鍵的 Collection 視圖。

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

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

建構子詳細資訊

Hashtable

public Hashtable(int initialCapacity,
                 float loadFactor)

用指定初始容量和指定載入因子建構一個新的空雜湊表。

參數：

initialCapacity - 雜湊表的初始容量。

loadFactor - 雜湊表的載入因子。

拋出：

IllegalArgumentException - 如果初始容量小於零，或者載入因子為非正數。

Hashtable

public Hashtable(int initialCapacity)

用指定初始容量和預設的載入因子 (0.75) 建構一個新的空雜湊表。

參數：

initialCapacity - 雜湊表的初始容量。

拋出：

IllegalArgumentException - 如果初始容量小於零。

Hashtable

public Hashtable()

用預設的初始容量 (11) 和載入因子 (0.75) 建構一個新的空雜湊表。

Hashtable

public Hashtable(Map<? extends K,? extends V> t)

建構一個與給定的 Map 具有相同映射關係的新雜湊表。該雜湊表是用足以容納給定 Map 中映射關係的初始容量和預設的載入因子（0.75）創建的。

參數：

t - 其映射關係將存放在此映射中的映射。

拋出：

NullPointerException - 如果指定映射為 null。

從以下版本開始：

1.2

方法詳細資訊

size

public int size()

返回此雜湊表中的鍵的數量。

指定者：

介面 Map<K,V> 中的 size

指定者：

類別 Dictionary<K,V> 中的 size

返回：

此雜湊表中的鍵的數量。

isEmpty

public boolean isEmpty()

測試此雜湊表是否沒有鍵映射到值。

指定者：

介面 Map<K,V> 中的 isEmpty

指定者：

類別 Dictionary<K,V> 中的 isEmpty

返回：

如果此雜湊表沒有將任何鍵映射到值，則返回 true；否則返回 false。

keys

public Enumeration<K> keys()

返回此雜湊表中的鍵的列舉。

指定者：

類別 Dictionary<K,V> 中的 keys

返回：

此雜湊表中的鍵的列舉。

另請參見：

Enumeration, elements(), keySet(), Map

elements

public Enumeration<V> elements()

返回此雜湊表中的值的列舉。對返回的物件使用 Enumeration 方法，以便按順序獲取這些元素。

指定者：

類別 Dictionary<K,V> 中的 elements

返回：

此雜湊表中的值的列舉。

另請參見：

Enumeration, keys(), values(), Map

contains

public boolean contains(Object value)

測試此映射表中是否存在與指定值關聯的鍵。此操作比 containsKey 方法的開銷更大。

注意，此方法在功能上等同於 containsValue 方法，containValue 是 collection 框架中 Map 介面的一部分。

參數：

value - 要搜尋的值。

返回：

當且僅當此雜湊表中某個鍵映射到 value 參數（由 equals 方法確定）時，返回 true；否則返回 false。

拋出：

NullPointerException - 如果該值為 null

containsValue

public boolean containsValue(Object value)

如果此 Hashtable 將一個或多個鍵映射到此值，則返回 true。

注意，此方法在功能上等同於contains（它先於 Map 介面）。

指定者：

介面 Map<K,V> 中的 containsValue

參數：

value - 將要測試是否存在此雜湊表中的值

返回：

如果此映射將一個或多個鍵映射到指定值，則返回 true

拋出：

NullPointerException - 如果該值為 null

從以下版本開始：

1.2

containsKey

public boolean containsKey(Object key)

測試指定物件是否為此雜湊表中的鍵。

指定者：

介面 Map<K,V> 中的 containsKey

參數：

key - 可能的鍵

返回：

當且僅當指定物件（由 equals 方法確定）是此雜湊表中的鍵時，才返回 true；否則返回 false。

拋出：

NullPointerException - 如果該鍵為 null

另請參見：

contains(Object)

get

public V get(Object key)

返回指定鍵所映射到的值，如果此映射不包含此鍵的映射，則返回 null.

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

指定者：

介面 Map<K,V> 中的 get

指定者：

類別 Dictionary<K,V> 中的 get

參數：

key - 要返回其相關值的鍵

返回：

指定鍵映射到的值，如果此映射不包含到鍵的映射，則返回 null。

拋出：

NullPointerException - 如果指定鍵為 null

另請參見：

put(Object, Object)

rehash

protected void rehash()

增加此雜湊表的容量並在內部對其進行重組，以便更有效地容納和存取其元素。當雜湊表中的鍵的數量超出雜湊表的容量和載入因子時，自動調用此方法。

put

public V put(K key,
             V value)

將指定 key 映射到此雜湊表中的指定 value。鍵和值都不可以為 null。

通過使用與原來的鍵相同的鍵調用 get 方法，可以獲取相應的值。

指定者：

介面 Map<K,V> 中的 put

指定者：

類別 Dictionary<K,V> 中的 put

參數：

key - 雜湊表的鍵

value - 值

返回：

此雜湊表中指定鍵的以前的值；如果不存在該值，則返回 null

拋出：

NullPointerException - 如果鍵或值為 null

另請參見：

Object.equals(Object), get(Object)

remove

public V remove(Object key)

從雜湊表中移除該鍵及其相應的值。如果該鍵不在雜湊表中，則此方法不執行任何操作。

指定者：

介面 Map<K,V> 中的 remove

指定者：

類別 Dictionary<K,V> 中的 remove

參數：

key - 需要移除的鍵

返回：

此雜湊表中與該鍵存在映射關係的值；如果該鍵沒有映射關係，則返回 null

拋出：

NullPointerException - 如果該鍵為 null

putAll

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

將指定映射的所有映射關係複製到此雜湊表中，這些映射關係將替換此雜湊表擁有的、針對當前指定映射中所有鍵的所有映射關係。

指定者：

介面 Map<K,V> 中的 putAll

參數：

t - 將存儲在此映射中的映射關係。

拋出：

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

從以下版本開始：

1.2

clear

public void clear()

將此雜湊表清空，使其不包含任何鍵。

指定者：

介面 Map<K,V> 中的 clear

clone

public Object clone()

創建此雜湊表的淺表副本。複製雜湊表自身的所有結構，但不複製它的鍵和值。這是一個開銷相對較大的操作。

覆寫：

類別 Object 中的 clone

返回：

雜湊表的一個副本

另請參見：

Cloneable

toString

public String toString()

返回此 Hashtable 物件的字元串表示形式，其形式為 ASCII 字元 ", " （逗號加空格）分隔開的、括在括號中的一組條目。每個條目都按以下方式呈現：鍵，一個等號 = 和相關元素，其中 toString 方法用於將鍵和元素轉換為字元串。

覆寫：

類別 Object 中的 toString

返回：

此雜湊表的字元串表示形式

keySet

public Set<K> keySet()

返回此映射中包含的鍵的 Set 視圖。此 set 受映射支持，因此對映射的更改可在 set 中反映出來，反之亦然。如果在此 set 上的迭代器處於進行中時修改此映射（除非通過迭代器自身的 remove 操作），則迭代器的結果是不確定的。通過 Iterator.remove、Set.remove、removeAll、 retainAll、和 clear 操作，此 set 支持元素移除，可從映射中移除相應的映射關係。它不支持 add 或 addAll 操作。

指定者：

介面 Map<K,V> 中的 keySet

返回：

此映射中包含的鍵的 set 視圖

從以下版本開始：

1.2

entrySet

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

返回此映射中包含的鍵的 Set 視圖。此 set 受映射支持，因此對映射的更改可在 set 中反映出來，反之亦然。如果在此 set 上的迭代器處於進行中時修改此映射（除非通過迭代器自身的 remove 操作，或通過由迭代器返回的映射條目上的 setValue 操作），則迭代器的結果是不確定的。通過 Iterator.remove、Set.remove、removeAll、 retainAll、 和 clear 操作，此set 支持元素移除，可從映射中移除相應的映射關係。它不支持 add 或 addAll 操作。

指定者：

介面 Map<K,V> 中的 entrySet

返回：

此映射中包含的映射關係的 set 視圖

從以下版本開始：

1.2

values

public Collection<V> values()

返回此映射中包含的鍵的 Collection 視圖。此 collection 受映射支持，因此對映射的更改可在 collection 中反映出來，反之亦然。如果在此 collection 上的迭代器處於進行中時修改此映射（除非通過迭代器自身的 remove 操作），則迭代器的結果是不確定的。通過 Iterator.remove、Collection.remove、removeAll、 retainAll、 和 clear 操作，此set 支持元素移除，可從映射中移除相應的映射關係。它不支持 add 或 addAll 操作。

指定者：

介面 Map<K,V> 中的 values

返回：

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

從以下版本開始：

1.2

equals

public boolean equals(Object o)

按照 Map 介面的定義，比較指定 Object 與此 Map 是否相等。

指定者：

介面 Map<K,V> 中的 equals

覆寫：

類別 Object 中的 equals

參數：

o - 將與此雜湊表進行比較相等性的物件

返回：

如果指定的 Object 與此 Map 相等，則返回 true。

從以下版本開始：

1.2

另請參見：

Map.equals(Object)

hashCode

public int hashCode()

按照 Map 介面的定義，返回此 Map 的雜湊碼值。

指定者：

介面 Map<K,V> 中的 hashCode

覆寫：

類別 Object 中的 hashCode

返回：

此物件的一個雜湊碼值。

從以下版本開始：

1.2

另請參見：

Map.hashCode()