JavaTM 2 Platform
Standard Ed. 5.0

java.util
类 AbstractMap<K,V>

java.lang.Object
  继承者 java.util.AbstractMap<K,V>
所有已实现的接口:
Map<K,V>
直接已知子类:
ConcurrentHashMap, EnumMap, HashMap, IdentityHashMap, TreeMap, WeakHashMap

public abstract class AbstractMap<K,V>
extends Object
implements Map<K,V>

此类提供了 Map 接口的骨干实现,从而最大限度地减少了实现此接口所需的工作。

要实现不可修改的映射,程序员只需扩展此类并提供 entrySet 方法的实现即可,该方法将返回映射的映射关系 Set 视图。通常,返回的 Set 将依次在 AbstractSet 上实现。此 Set 不支持 addremove 方法,其迭代器也不支持 remove 方法。

要实现可修改的映射,程序员还必须另外重写此类的 put 方法(否则将抛出 UnsupportedOperationException),并且由 entrySet().iterator() 所返回的迭代器必须另外实现其 remove 方法。

按照 Map 接口规范中的推荐,程序员通常应该提供一个 void(无参数)构造方法和 map 构造方法。

此类中每个非抽象方法的文档详细描述了其实现。如果要实现的映射允许更有效的实现,则可以重写这些方法中的每个方法。

此类是 Java Collections Framework 的成员。

从以下版本开始:
1.2
另请参见:
Map, Collection

嵌套类摘要
 
从接口 java.util.Map 继承的嵌套类/接口
Map.Entry<K,V>
 
构造方法摘要
protected AbstractMap()
          单独的构造方法。
 
方法摘要
 void clear()
          从此映射中移除所有映射关系(可选操作)。
protected  Object clone()
          返回此 AbstractMap 实例的浅表复制:不克隆键和值本身。
 boolean containsKey(Object key)
          如果此映射包含指定键的映射关系,则返回 true
 boolean containsValue(Object value)
          如果此映射将一个或多个键映射到该值,则返回 true
abstract  Set<Map.Entry<K,V>> entrySet()
          返回包含在此映射中的映射关系的 Set 视图。
 boolean equals(Object o)
          比较指定对象与此映射的相等性。
 V get(Object key)
          返回此映射将指定键映射到的值。
 int hashCode()
          返回此映射的哈希码值。
 boolean isEmpty()
          如果此映射不包含任何键-值映射关系,则返回 true
 Set<K> keySet()
          返回包含在此映射中的键的 Set 视图。
 V put(K key, V value)
          将指定的值与此映射中的指定键关联起来(可选操作)。
 void putAll(Map<? extends K,? extends V> t)
          将指定映射的所有映射关系复制到此映射中(可选操作)。
 V remove(Object key)
          如果此映射中存在此键的映射关系,则移除该映射关系(可选操作)。
 int size()
          返回此映射中键-值映射关系的数量。
 String toString()
          返回此映射的字符串表示形式。
 Collection<V> values()
          返回包含在此映射中的值的 collection 视图。
 
从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, wait, wait, wait
 

构造方法详细信息

AbstractMap

protected AbstractMap()
单独的构造方法。(由子类构造方法调用,通常是隐式的。)

方法详细信息

size

public int size()
返回此映射中键-值映射关系的数量。如果该映射包含多于 Integer.MAX_VALUE 的元素,则返回 Integer.MAX_VALUE

此实现返回 entrySet().size()

指定者:
接口 Map<K,V> 中的 size
返回:
此映射中键-值映射关系的数量。

isEmpty

public boolean isEmpty()
如果此映射不包含任何键-值映射关系,则返回 true

此实现返回 size() == 0

指定者:
接口 Map<K,V> 中的 isEmpty
返回:
如果此映射不包含任何键-值映射关系,则返回 true

containsValue

public boolean containsValue(Object value)
如果此映射将一个或多个键映射到该值,则返回 true。更正式地说,当且仅当此映射包含至少一个到值 v 的映射关系,并且 (value==null ? v==null : value.equals(v)) 时才返回 true。对于大多数映射实现而言,此操作所需的时间可能与映射的大小呈线性关系。

此实现在 entrySet() 上进行迭代,以搜索带有指定值的项。如果找到这样的项,则返回 true。如果迭代终止,并且没有找到这样的项,则返回 false。注意,此实现所需的时间与映射的大小呈线性关系。

指定者:
接口 Map<K,V> 中的 containsValue
参数:
value - 将测试此映射中是否存在的值。
返回:
如果此映射将一个或多个键映射到该值,则返回 true

containsKey

public boolean containsKey(Object key)
如果此映射包含指定键的映射关系,则返回 true

此实现在 entrySet() 上进行迭代,以搜索带有指定键的项。如果找到这样的项,则返回 true。如果迭代终止,并且没有找到这样的项,则返回 false。注意,此实现所需的时间与映射的大小呈线性关系;许多实现将重写此方法。

指定者:
接口 Map<K,V> 中的 containsKey
参数:
key - 将测试此映射中是否存在的键。
返回:
如果此映射包含指定键的映射关系,则返回 true
抛出:
NullPointerException - 如果该键为 null 并且此映射不允许包含 null 键。

get

public V get(Object key)
返回此映射将指定键映射到的值。如果该映射不包含此键的映射关系,则返回 null。返回值 null一定 表明该映射不包含该键的映射关系;也可能是该映射显式地将该键映射到 null。可以使用 containsKey 操作来区分这两种情况。

此实现在 entrySet() 上进行迭代,以搜索带有指定键的项。如果找到这样的项,则返回该项的值。如果迭代终止,并且没有找到这样的项,则返回 null。注意,此实现所需的时间与映射的大小呈线性关系;许多实现将重写此方法。

指定者:
接口 Map<K,V> 中的 get
参数:
key - 与返回值关联的键。
返回:
此映射将指定键映射到的值。
抛出:
NullPointerException - 如果键为 null 并且此映射不允许包含 null 键。
另请参见:
containsKey(Object)

put

public V put(K key,
             V value)
将指定的值与此映射中的指定键关联起来(可选操作)。如果映射以前包含此键的映射关系,则替换旧的值。

此实现始终抛出 UnsupportedOperationException

指定者:
接口 Map<K,V> 中的 put
参数:
key - 将与指定值关联的键。
value - 将与指定键关联的值。
返回:
指定键以前的关联值。如果没有该键的映射关系,则返回 null。(如果该实现支持 null 值,则返回 null 也可以表明该映射以前将 null 与指定键相关联。)
抛出:
UnsupportedOperationException - 如果此映射不支持 put 操作。
ClassCastException - 如果指定键或值的类不允许它存储在此映射中。
IllegalArgumentException - 如果此键或值 * 的某方面不允许它存储在此映射中。
NullPointerException - 如果此映射不允许 null 键或值,并且指定键或值为 null

remove

public V remove(Object key)
如果此映射中存在此键的映射关系,则移除该映射关系(可选操作)。

此实现在 entrySet() 上进行迭代,以搜索带有指定键的项。如果找到这样的项,则通过 getValue 操作获得该项的值,然后使用迭代器的 remove 操作从 Collection(以及底层映射)中移除该项,并返回保存的值。如果迭代终止,并且没有找到这样的项,则返回 null。注意,此实现所需要时间与映射大小呈线性关系;许多实现将重写此方法。

注意,如果 entrySet 迭代器不支持 remove 方法并且此映射包含指定键的映射关系,则此实现会抛出 UnsupportedOperationException

指定者:
接口 Map<K,V> 中的 remove
参数:
key - 将从映射中移除其映射关系的键。
返回:
指定键以前的关联值。如果没有该键的项,则返回 null。(如果该实现支持 null 值,则返回 null 也可以表明该映射以前将 null 与指定键相关联。)
抛出:
UnsupportedOperationException - 如果此映射不支持 remove 操作。

putAll

public void putAll(Map<? extends K,? extends V> t)
将指定映射的所有映射关系复制到此映射中(可选操作)。这些映射关系将替代此映射中已有的,并且指定映射中目前也存在的所有键的映射关系。

此实现在指定映射的 entrySet() 集合上进行迭代,并对迭代返回的每一项调用一次此映射的 put 操作。

注意,如果此映射不支持 put 操作,并且指定映射为非空,则此实现会抛出 UnsupportedOperationException

指定者:
接口 Map<K,V> 中的 putAll
参数:
t - 要存储在此映射中的映射关系。
抛出:
UnsupportedOperationException - 如果此映射不支持 putAll 操作。
ClassCastException - 如果指定映射中的键或值的类不允许它存储在此映射中。
IllegalArgumentException - 如果指定映射中的键或值的某方面不允许它存储在此映射中。
NullPointerException - 如果指定的映射为 null,或者此映射不允许 null 键或值,但指定的映射包含了 null 键或值。

clear

public void clear()
从此映射中移除所有映射关系(可选操作)。

此实现调用 entrySet().clear()。 注意,如果 entrySet 不支持 clear 操作,则此实现会抛出 UnsupportedOperationException

指定者:
接口 Map<K,V> 中的 clear
抛出:
UnsupportedOperationException - 此映射不支持 clear 操作。

keySet

public Set<K> keySet()
返回包含在此映射中的键的 Set 视图。该 Set 受映射的支持,所以对映射的更改反映在 Set 中,反之亦然。(如果在对 Set 进行迭代的同时修改映射,则迭代的结果是不明确的。)Set 支持元素移除,即通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作从映射中移除相应的项。 它不支持 add 或 addAll 操作。

此实现返回一个为 AbstractSet 创建子类的 Set。子类的 iterator 方法通过此映射的 entrySet() 迭代器返回一个“包装器对象”。size 方法委托给此映射的 size 方法,而 contains 方法委托给此映射的 containsKey 方法。

Set 是在第一次调用此方法时创建的,并为响应所有后续调用而返回。 因为不执行同步操作,所以对此方法的多个调用很少返回不同的 Set。

指定者:
接口 Map<K,V> 中的 keySet
返回:
包含在此映射中的键的 Set 视图。

values

public Collection<V> values()
返回包含在此映射中的值的 collection 视图。该 collection 受映射的支持,所以对映射的更改反映在 collection 中,反之亦然。(如果在对 collection 进行迭代的同时修改映射,则迭代的结果是不明确的。)collection 支持元素移除,即通过 Iterator.removeCollection.removeremoveAllretainAllclear 操作从映射中移除相应的项。它不支持 addaddAll 操作。

此实现返回一个为抽象 collection 创建子类的 collection。子类的 iterator 方法通过此映射的 entrySet() 迭代器返回一个“包装器对象”。size 方法委托给此映射的 size 方法,而 contains 方法委托给此映射的 containsValue 方法。

collection 是在第一次调用此方法时创建的,并为响应所有后续调用而返回。因为不执行同步操作,所以对此方法的多个调用很少返回不同的 Collection。

指定者:
接口 Map<K,V> 中的 values
返回:
包含在此映射中的值的 collection 视图。

entrySet

public abstract Set<Map.Entry<K,V>> entrySet()
返回包含在此映射中的映射关系的 Set 视图。此 Set 的每一个元素都是一个 Map.Entry。该 Set 受映射的支持,所以对映射的更改反映在 Set 中,反之亦然。(如果在对 Set 进行迭代的同时修改映射,则迭代的结果是不明确的。)Set 支持元素移除,即通过 Iterator.removeSet.removeremoveAllretainAllclear 操作从映射中移除相应的项。它不支持 addaddAll 操作。

指定者:
接口 Map<K,V> 中的 entrySet
返回:
包含在此映射中的映射关系的 Set 视图。

equals

public boolean equals(Object o)
比较指定对象与此映射的相等性。如果给定对象也是一个映射并且两个映射表示相同的映射关系,则返回 true。更正式地说,如果 t1.keySet().equals(t2.keySet()) 并且对于每一个 t1.keySet() 中的键 k 都存在 (t1.get(k)==null ? t2.get(k)==null :t1.get(k).equals(t2.get(k))),则两个映射 t1t2 表示相同的映射关系 。这可以确保 equals 方法在 map 接口的不同实现中正常工作。

此实现首先检查指定的对象是否为此映射;如果是,则返回 true。然后,它将检查指定的对象是否是一个大小与此 set 的大小相等的映射;如果不是,则返回 false。如果是,则在此映射的 entrySet 集合上进行迭代,并检查指定的映射是否包含此映射所包含的每个映射关系。如果指定的映射中不包含这样的映射关系,则返回 false。如果迭代完成,则返回 true

指定者:
接口 Map<K,V> 中的 equals
覆盖:
Object 中的 equals
参数:
o - 要与此映射进行相等性比较的对象。
返回:
如果指定的对象等于此映射,则返回 true
另请参见:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
返回此映射的哈希码值。映射的哈希码被定义为该映射的 entrySet() 视图中每一项的哈希码的总和。这确保了 t1.equals(t2) 对于任意两个映射 t1t2 都意味着 t1.hashCode()==t2.hashCode(),正如 Object.hashCode 的常规协定所要求的。

此实现在 entrySet() 上进行迭代,对 Collection 中的每个元素(项)调用 hashCode,并合计结果。

指定者:
接口 Map<K,V> 中的 hashCode
覆盖:
Object 中的 hashCode
返回:
此映射的哈希码值。
另请参见:
Map.Entry.hashCode(), Object.hashCode(), Object.equals(Object), Set.equals(Object)

toString

public String toString()
返回此映射的字符串表示形式。该字符串表示形式由键-值映射关系的一个列表组成,此列表是按照映该射 entrySet 视图的迭代器返回的顺序排列的,并用括号 ("{}") 括起来。相邻的映射关系是用字符 ", "(逗号加空格)分隔的。每个键-值映射关系按以下方式呈现:键,后面是一个等号 ("="),再后面是相关联的值。键和值都通过 String.valueOf(Object) 转换为字符串。

此实现会创建一个空的字符串缓冲区,追加一个左括号,然后在映射的 entrySet 视图上进行迭代,依次追加每个 map.entry 的字符串表示形式。每追加一项后(最后一项除外),将追加字符串 ", "。最后,追加一个右括号。从字符串缓冲区中获得一个字符串并返回它。

覆盖:
Object 中的 toString
返回:
此映射的字符串表示形式。

clone

protected Object clone()
                throws CloneNotSupportedException
返回此 AbstractMap 实例的浅表复制:不克隆键和值本身。

覆盖:
Object 中的 clone
返回:
此映射的浅表复制。
抛出:
CloneNotSupportedException - 如果对象的类不支持 Cloneable 接口,则重写 clone 方法的子类也会抛出此异常,以指示无法克隆某个实例。
另请参见:
Cloneable

JavaTM 2 Platform
Standard Ed. 5.0

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

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