|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
public interface Map<K,V>
将键映射到值的对象。一个映射不能包含重复的键;每个键最多只能映射一个值。
此接口代替 Dictionary 类,后者完全是一个抽象类,而不是一个接口。
Map 接口提供三种collection 视图,允许以键集、值集合或键-值映射关系集的形式查看某个映射的内容。映射的顺序 定义为迭代器在映射的 collection 视图中返回其元素的顺序。某些映射实现可明确保证其顺序,如 TreeMap 类;某些映射实现则不保证顺序,如 HashMap 类。
注:将可变对象用作映射键时必须格外小心。当对象是映射中某个键时,如果以影响 equals 比较的方式更改了对象的值,则映射的行为就不是特定的。此项禁止的一个特殊情况是不允许某个映射包含其自身作为键。虽然允许某个映射包含其自身作为值,但建议要格外小心:在这样的映射上将无法再定义 equals 和 hashCode 方法。
所有通用的映射实现类应该提供两个“标准的”构造方法:一个 void(无参数)构造方法,用于创建空映射,另一个是带有 Map 类型单参数的构造方法,用于创建一个与其参数具有相同键-值映射关系的新映射。实际上,后一个构造方法允许用户复制任意映射,生成所需类的一个等价映射。尽管无法强制执行该建议(因为接口不能包含构造方法),但是 JDK 中所有通用的映射实现都遵从它。
该接口中包含的“破坏性”方法可修改其所操作的映射,如果此映射不支持该操作,则指定这些方法抛出 UnsupportedOperationException。如果是这样,那么在调用对该映射无效时,这些方法可能,但并不一定抛出 UnsupportedOperationException。例如,如果某个不可修改的映射(其映射关系是“重叠”的)为空,则对该映射调用 putAll(Map)
方法时,可能但并不一定抛出异常。
某些映射实现对可能包含的键和值有所限制。例如,某些实现禁止空键和空值,而某些实现则对其键的类型有限制。尝试插入不合格的键或值会抛出一个未经检查的异常,通常是 NullPointerException 或 ClassCastException。试图查询是否存在不合格的键或值可能抛出异常,或者只是简单地返回 false;某些实现将表现出前一种行为,而某些实现则表现后一种。较为常见的是,试图对不合格的键或值执行操作且该操作的完成不会导致不合格的元素被插入映射中时,将可能抛出一个异常,也可能操作成功,这取决于实现本身。这样的异常在此接口的规范中标记为“可选”。
此接口是 Java Collections Framework 的成员。
Collections Framework 接口中的很多方法是根据 equals
方法定义的。例如,contains(Object key)
方法的规范声明:“当且仅当此映射对于键 k 包含以下映射关系时才返回 true:(key==null ? k==null : key.equals(k))”。不 应将此规范解释为它暗指调用具有非空参数 key 的 Map.containsKey 会导致对任意的键 k 调用 key.equals(k)。可随意对各种实现执行优化,只要避免调用 equals 即可,例如,通过首先比较两个键的哈希码(Object.hashCode()
规范保证哈希码不相等的两个对象不会相等)。较为常见的是,各种 Collections Framework 接口的实现可随意利用基础 Object
方法的指定行为,而不管实现程序认为它是否合适。
HashMap
,
TreeMap
,
Hashtable
,
SortedMap
,
Collection
,
Set
嵌套类摘要 | |
---|---|
static interface |
Map.Entry<K,V>
映射项(键-值对)。 |
方法摘要 | |
---|---|
void |
clear()
从此映射中移除所有映射关系(可选操作)。 |
boolean |
containsKey(Object key)
如果此映射包含指定键的映射关系,则返回 true。 |
boolean |
containsValue(Object value)
如果此映射为指定值映射一个或多个键,则返回 true。 |
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()
返回此映射中的键-值映射关系数。 |
Collection<V> |
values()
返回此映射中包含的值的 collection 视图。 |
方法详细信息 |
---|
int size()
boolean isEmpty()
boolean containsKey(Object key)
key
- 测试在此映射中是否存在的键。
ClassCastException
- 如果该键对于此映射是不合适的类型(可选)。
NullPointerException
- 如果该键为 null 并且此映射不允许 null 键(可选)。boolean containsValue(Object value)
value
- 测试在该映射中是否存在的值。
ClassCastException
- 如果该值对于此映射是不合适的类型(可选)。
NullPointerException
- 如果该值为 null 并且此映射不允许 null 值(可选)。V get(Object key)
更正式地说,如果此映射包含满足以下从键 k 到值 v 的映射关系:(key==null ? k==null :key.equals(k)),则此方法返回 v;否则返回 null(最多只能有一个这样的映射关系)。
key
- 要返回其相关值的键。
ClassCastException
- 如果该键对于此映射是不合适的类型(可选)。
NullPointerException
- 如果该键为 null 并且此映射不允许 null 键(可选)。containsKey(Object)
V put(K key, V value)
m.containsKey(k)
返回 true 时,才能说映射 m 包含键 k 的映射关系)。
key
- 与指定值相关联的键。value
- 与指定键相关联的值。
UnsupportedOperationException
- 如果此映射不支持 put 操作。
ClassCastException
- 如果指定键或值的类不允许将其存储在此映射中。
IllegalArgumentException
- 如果此键或值的某些方面不允许将其存储在此映射中。
NullPointerException
- 如果此映射不允许 null 键或值,并且指定的键或值为 null。V remove(Object key)
(key==null ? k==null :key.equals(k))
,则移除该映射关系(该映射最多只能包含一个这样的映射关系)。
返回此映射中以前映射该键的值,如果此映射不包含该键的映射关系,则返回 null(如果该实现支持 null 值,则返回 null 也可表明此映射以前将 null 与指定键相关联)。一旦调用返回,则此映射不包含指定键的映射关系。
key
- 从映射中移除其映射关系的键。
ClassCastException
- 如果该键对于此映射是不合适的类型(可选)。
NullPointerException
- 如果该键为 null 并且此映射不允许 null 键(可选)。
UnsupportedOperationException
- 如果此映射不支持 remove 操作。void putAll(Map<? extends K,? extends V> t)
put(k, v)
。如果正在进行此操作的同时修改了指定的映射,则此操作的行为是未指定的。
t
- 要存储在此映射中的映射关系。
UnsupportedOperationException
- 如果此映射不支持 putAll 方法。
ClassCastException
- 如果指定映射中的键或值的类不允许将其存储在此映射中。
IllegalArgumentException
- 如果指定映射中的键或值的某些方面不允许将其存储在此映射中。
NullPointerException
- 如果指定的映射为 null,或者此映射不允许 null 键或值,并且指定的映射包含 null 键或值。void clear()
UnsupportedOperationException
- 此映射不支持清除。Set<K> keySet()
Collection<V> values()
Set<Map.Entry<K,V>> entrySet()
Map.Entry
。该 set 受映射支持,所以对映射的改变可在此 set 中反映出来,反之亦然。如果修改映射的同时正在对该 set 进行迭代(除了通过迭代器自己的 remove 操作,或者通过在迭代器返回的映射项上执行 setValue 操作外),则迭代结果是不明确的。set 支持通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作实现元素移除,即从映射中移除相应的映射关系。它不支持 add 或 addAll 操作。
boolean equals(Object o)
Object
中的 equals
o
- 要与此映射进行相等性比较的对象。
Object.hashCode()
,
Hashtable
int hashCode()
Object
中的 hashCode
Map.Entry.hashCode()
,
Object.hashCode()
,
Object.equals(Object)
,
equals(Object)
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。