JavaTM Platform
Standard Ed. 6

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) 时,才认为两个键 k1k2 相等(在正常 Map 实现(如 HashMap)中,当且仅当满足下列条件时才认为两个键 k1k2 相等:(k1==null ? k2==null : e1.equals(e2)))。

此类不是 通用 Map 实现!此类实现 Map 接口时,它有意违反 Map 的常规协定,该协定在比较对象时强制使用 equals 方法。此类设计仅用于其中需要引用相等性语义的罕见情况。

此类的典型用法是拓扑保留对象图形转换,如序列化或深层复制。要执行这样的转换,程序必须维护用于跟踪所有已处理对象引用的“节点表”。节点表一定不等于不同对象,即使它们偶然相等也如此。此类的另一种典型用法是维护代理对象。例如,调试设施可能希望为正在调试程序中的每个对象维护代理对象。

此类提供所有的可选映射操作,并且允许 null 值和 null 键。此类对映射的顺序不提供任何保证;特别是不保证顺序随时间的推移保持不变。

此类提供基本操作(getput)的稳定性能,假定系统标识了将桶间元素正确分开的哈希函数 (System.identityHashCode(Object))。

此类具有一个调整参数(影响性能但不影响语义):expected maximum size。此参数是希望映射保持的键值映射关系最大数。在内部,此参数用于确定最初组成哈希表的桶数。未指定所期望的最大数量和桶数之间的确切关系。

如果映射的大小(键值映射关系数)已经超过期望的最大数量,则桶数会增加,增加桶数(“重新哈希”)可能相当昂贵,因此创建具有足够大的期望最大数量的标识哈希映射更合算。另一方面,对 collection 视图进行迭代所需的时间与哈希表中的桶数成正比,所以如果特别注重迭代性能或内存使用,则不宜将期望的最大数量设置得过高。

注意,此实现不是同步的。如果多个线程同时访问标识哈希映射,并且其中至少一个线程从结构上修改了该映射,则其必须 保持外部同步(结构上的修改是指添加或删除一个或多个映射关系的操作;仅改变与实例已经包含的键关联的值不是结构上的修改。)这一般通过对自然封装该映射的对象进行同步操作来完成。 如果不存在这样的对象,则应该使用 Collections.synchronizedMap 方法来“包装”该映射。最好在创建时完成这一操作,以防止对映射进行意外的不同步访问,如下所示:

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

由所有此类的“collection 视图方法”所返回的collections的iterator 方法返回的迭代器都是快速失败 的:在迭代器创建之后,如果从结构上对映射进行修改,除非通过迭代器自身的 removeadd 方法,其他任何时间任何方式的修改,迭代器都将抛出 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 还客表示映射以前将 nullkey 关联)。

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 实例 m1m2 而言,都存在 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.removeSet.removeremoveAllretainAllclear 方法可从映射中移除相应的映射关系。它不支持 addaddAll 方法。

此方法返回的对象实现 Set 接口时,它 遵守 Set 的常规协定。与其底层映射一样,此方法返回的 set 将元素相等性定义为引用相等性,而非对象相等性。这一点将对其 containsremovecontainsAllequalshashCode 方法的行为产生影响。

如果指定对象是一个包含与返回 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.removeCollection.removeremoveAllretainAllclear 方法可从该映射中移除相应的映射关系。它不支持 addaddAll 方法。

此方法返回的对象实现 Collection 接口时,它 遵守 Collection 的常规协定。与其底层映射一样,此方法返回的 collection 将元素相等性定义为引用相等性,而非对象相等性。这一点将对其 containsremovecontainsAll 方法的行为产生影响。

指定者:
接口 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.removeSet.removeremoveAllretainAllclear 方法可从此映射移除相应的映射关系。它不支持 addaddAll 方法。

与底层映射一样,此方法所返回 set 中的 Map.Entry 对象将键和值的相等性定义为引用相等性,而非对象相等性。这一点将对 Map.Entry 对象的 equalshashCode 方法的行为产生影响。当且仅当 oMap.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 视图

JavaTM Platform
Standard Ed. 6

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

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