JavaTM Platform
Standard Ed. 6

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 操作中,包括 getput 操作,都反映了这一点)。

初始容量主要控制空间消耗与执行 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.removeSet.removeremoveAllretainAll、和 clear 操作,此 set 支持元素移除,可从映射中移除相应的映射关系。它不支持 addaddAll 操作。

指定者:
接口 Map<K,V> 中的 keySet
返回:
此映射中包含的键的 set 视图
从以下版本开始:
1.2

entrySet

public Set<Map.Entry<K,V>> entrySet()
返回此映射中包含的键的 Set 视图。此 set 受映射支持,因此对映射的更改可在 set 中反映出来,反之亦然。如果在此 set 上的迭代器处于进行中时修改此映射(除非通过迭代器自身的 remove 操作,或通过由迭代器返回的映射条目上的 setValue 操作),则迭代器的结果是不确定的。通过 Iterator.removeSet.removeremoveAllretainAll、 和 clear 操作,此set 支持元素移除,可从映射中移除相应的映射关系。它不支持 addaddAll 操作。

指定者:
接口 Map<K,V> 中的 entrySet
返回:
此映射中包含的映射关系的 set 视图
从以下版本开始:
1.2

values

public Collection<V> values()
返回此映射中包含的键的 Collection 视图。此 collection 受映射支持,因此对映射的更改可在 collection 中反映出来,反之亦然。如果在此 collection 上的迭代器处于进行中时修改此映射(除非通过迭代器自身的 remove 操作),则迭代器的结果是不确定的。通过 Iterator.removeCollection.removeremoveAllretainAll、 和 clear 操作,此set 支持元素移除,可从映射中移除相应的映射关系。它不支持 addaddAll 操作。

指定者:
接口 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()

JavaTM Platform
Standard Ed. 6

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

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