Map (Java Platform SE 6) - JavaTM 2 Platform Standard Edition 6.0 API 规范中文版
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
java.util
接口 Map<K,V>
- 类型参数：
K- 此映射所维护的键的类型V- 映射值的类型
- 所有已知子接口：
- Bindings, ConcurrentMap<K,V>, ConcurrentNavigableMap<K,V>, LogicalMessageContext, MessageContext, NavigableMap<K,V>, SOAPMessageContext, SortedMap<K,V>
- 所有已知实现类：
- AbstractMap, Attributes, AuthProvider, ConcurrentHashMap, ConcurrentSkipListMap, EnumMap, HashMap, Hashtable, IdentityHashMap, LinkedHashMap, PrinterStateReasons, Properties, Provider, RenderingHints, SimpleBindings, TabularDataSupport, TreeMap, UIDefaults, WeakHashMap
public interface Map<K,V>
将键映射到值的对象。一个映射不能包含重复的键；每个键最多只能映射到一个值。
此接口取代 Dictionary 类，后者完全是一个抽象类，而不是一个接口。
Map 接口提供三种collection 视图，允许以键集、值集或键-值映射关系集的形式查看某个映射的内容。映射顺序 定义为迭代器在映射的 collection 视图上返回其元素的顺序。某些映射实现可明确保证其顺序，如 TreeMap 类；另一些映射实现则不保证顺序，如 HashMap 类。
注：将可变对象用作映射键时必须格外小心。当对象是映射中某个键时，如果以影响 equals 比较的方式更改了对象的值，则映射的行为将是不确定的。此项禁止的一种特殊情况是不允许某个映射将自身作为一个键包含。虽然允许某个映射将自身作为值包含，但请格外小心：在这样的映射上 equals 和 hashCode 方法的定义将不再是明确的。
所有通用的映射实现类应该提供两个“标准的”构造方法：一个 void（无参数）构造方法，用于创建空映射；一个是带有单个 Map 类型参数的构造方法，用于创建一个与其参数具有相同键-值映射关系的新映射。实际上，后一个构造方法允许用户复制任意映射，生成所需类的一个等价映射。尽管无法强制执行此建议（因为接口不能包含构造方法），但是 JDK 中所有通用的映射实现都遵从它。
此接口中包含的“破坏”方法可修改其操作的映射，如果此映射不支持该操作，这些方法将抛出 UnsupportedOperationException。如果是这样，那么在调用对映射无效时，这些方法可以（但不要求）抛出 UnsupportedOperationException。例如，如果某个不可修改的映射（其映射关系是“重叠”的）为空，则对该映射调用 putAll(Map) 方法时，可以（但不要求）抛出异常。
某些映射实现对可能包含的键和值有所限制。例如，某些实现禁止 null 键和值，另一些则对其键的类型有限制。尝试插入不合格的键或值将抛出一个未经检查的异常，通常是 NullPointerException 或 ClassCastException。试图查询是否存在不合格的键或值可能抛出异常，或者返回 false；某些实现将表现出前一种行为，而另一些则表现后一种。一般来说，试图对不合格的键或值执行操作且该操作的完成不会导致不合格的元素被插入映射中时，将可能抛出一个异常，也可能操作成功，这取决于实现本身。这样的异常在此接口的规范中标记为“可选”。
此接口是 Java Collections Framework 的成员。
Collections Framework 接口中的很多方法是根据 equals 方法定义的。例如，containsKey(Object key) 方法的规范中写道：“当且仅当此映射包含针对满足 (key==null ? k==null : key.equals(k)) 的键 k 的映射关系时，返回 true”。不 应将此规范解释为：调用具有非空参数 key 的 Map.containsKey 将导致对任意的键 k 调用 key.equals(k)。实现可随意进行优化，以避免调用 equals，例如，可首先比较两个键的哈希码（Object.hashCode() 规范保证哈希码不相等的两个对象不会相等）。一般来说，只要实现者认为合适，各种 Collections Framework 接口的实现可随意利用底层 Object 方法的指定行为。
| 嵌套类摘要 | |
|---|---|
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)
返回指定键所映射的值；如果此映射不包含该键的映射关系，则返回 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 视图。 |
| 方法详细信息 |
|---|
size
int size()
- 返回此映射中的键-值映射关系数。如果该映射包含的元素大于 Integer.MAX_VALUE，则返回 Integer.MAX_VALUE。
- 返回：
- 此映射中的键-值映射关系数
isEmpty
boolean isEmpty()
- 如果此映射未包含键-值映射关系，则返回 true。
- 返回：
- 如果此映射未包含键-值映射关系，则返回 true
containsKey
boolean containsKey(Object key)
- 如果此映射包含指定键的映射关系，则返回 true。更确切地讲，当且仅当此映射包含针对满足 (key==null ? k==null : key.equals(k)) 的键 k 的映射关系时，返回 true。（最多只能有一个这样的映射关系）。
- 参数：
key- 测试是否存在于此映射中的键- 返回：
- 如果此映射包含指定键的映射关系，则返回 true
- 抛出：
ClassCastException- 如果该键对于此映射是不合适的类型（可选）NullPointerException- 如果指定键为 null 并且此映射不允许 null 键（可选）
containsValue
boolean containsValue(Object value)
- 如果此映射将一个或多个键映射到指定值，则返回 true。更确切地讲，当且仅当此映射至少包含一个对满足 (value==null ? v==null : value.equals(v)) 的值 v 的映射关系时，返回 true。对于大多数 Map 接口的实现而言，此操作需要的时间可能与映射大小呈线性关系。
- 参数：
value- 测试是否存在于此映射中的值- 返回：
- 如果此映射将一个或多个键映射到指定值，则返回 true
- 抛出：
ClassCastException- 如果该值对于此映射是不合适的类型（可选）NullPointerException- 如果指定值为 null 并且此映射不允许 null 值（可选）
get
V get(Object key)
- 返回指定键所映射的值；如果此映射不包含该键的映射关系，则返回
null。更确切地讲，如果此映射包含满足
(key==null ? k==null : key.equals(k))的键k到值v的映射关系，则此方法返回v；否则返回null。（最多只能有一个这样的映射关系）。如果此映射允许 null 值，则返回
null值并不一定 表示该映射不包含该键的映射关系；也可能该映射将该键显示地映射到null。使用containsKey操作可区分这两种情况。- 参数：
key- 要返回其关联值的键- 返回：
- 指定键所映射的值；如果此映射不包含该键的映射关系，则返回
null - 抛出：
ClassCastException- 如果该键对于此映射是不合适的类型（可选）NullPointerException- 如果指定键为 null 并且此映射不允许 null 键（可选）
put
V put(K key, V value)
- 将指定的值与此映射中的指定键关联（可选操作）。如果此映射以前包含一个该键的映射关系，则用指定值替换旧值（当且仅当
m.containsKey(k)返回 true 时，才能说映射 m 包含键 k 的映射关系）。- 参数：
key- 与指定值关联的键value- 与指定键关联的值- 返回：
- 以前与 key 关联的值，如果没有针对 key 的映射关系，则返回 null。（如果该实现支持 null 值，则返回 null 也可能表示此映射以前将 null 与 key 关联）。
- 抛出：
UnsupportedOperationException- 如果此映射不支持 put 操作ClassCastException- 如果指定键或值的类不允许将其存储在此映射中NullPointerException- 如果指定键或值为 null，并且此映射不允许 null 键或值IllegalArgumentException- 如果指定键或值的某些属性不允许将其存储在此映射中
remove
V remove(Object key)
- 如果存在一个键的映射关系，则将其从此映射中移除（可选操作）。更确切地讲，如果此映射包含从满足
(key==null ? k==null :key.equals(k))的键 k 到值 v 的映射关系，则移除该映射关系。（该映射最多只能包含一个这样的映射关系。）返回此映射中以前关联该键的值，如果此映射不包含该键的映射关系，则返回 null。
如果此映射允许 null 值，则返回 null 值并不一定 表示该映射不包含该键的映射关系；也可能该映射将该键显示地映射到 null。
调用返回后，此映射将不再包含指定键的映射关系。
- 参数：
key- 从映射中移除其映射关系的键- 返回：
- 以前与 key 关联的值；如果没有 key 的映射关系，则返回 null。
- 抛出：
UnsupportedOperationException- 如果此映射不支持 remove 操作ClassCastException- 如果该键对于此映射是不合适的类型（可选）NullPointerException- 如果指定键为 null 并且此映射不允许 null 键（可选）
putAll
void putAll(Map<? extends K,? extends V> m)
- 从指定映射中将所有映射关系复制到此映射中（可选操作）。对于指定映射中的每个键 k 到值 v 的映射关系，此调用等效于对此映射调用一次
put(k, v)。如果正在进行此操作的同时修改了指定的映射，则此操作的行为是不确定的。- 参数：
m- 要存储在此映射中的映射关系- 抛出：
UnsupportedOperationException- 如果此映射不支持 putAll 操作ClassCastException- 如果指定映射中的键或值的类不允许将其存储在此映射中NullPointerException- 如果指定映射为 null，或者此映射不允许 null 键或值，并且指定的映射包含 null 键或值IllegalArgumentException- 如果指定映射中的键或值的某些属性不允许将其存储在此映射中
clear
void clear()
- 从此映射中移除所有映射关系（可选操作）。此调用返回后，该映射将为空。
- 抛出：
UnsupportedOperationException- 如果此映射不支持 clear 操作
keySet
Set<K> keySet()
- 返回此映射中包含的键的
Set视图。该 set 受映射支持，所以对映射的更改可在此 set 中反映出来，反之亦然。如果对该 set 进行迭代的同时修改了映射（通过迭代器自己的 remove 操作除外），则迭代结果是不确定的。set 支持元素移除，通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作可从映射中移除相应的映射关系。它不支持 add 或 addAll 操作。- 返回：
- 此映射中包含的键的 set 视图
values
Collection<V> values()
- 返回此映射中包含的值的
Collection视图。该 collection 受映射支持，所以对映射的更改可在此 collection 中反映出来，反之亦然。如果对该 collection 进行迭代的同时修改了映射（通过迭代器自己的 remove 操作除外），则迭代结果是不确定的。collection 支持元素移除，通过 Iterator.remove、Collection.remove、removeAll、retainAll 和 clear 操作可从映射中移除相应的映射关系。它不支持 add 或 addAll 操作。- 返回：
- 此映射中包含的值的 collection 视图
entrySet
Set<Map.Entry<K,V>> entrySet()
- 返回此映射中包含的映射关系的
Set视图。该 set 受映射支持，所以对映射的更改可在此 set 中反映出来，反之亦然。如果对该 set 进行迭代的同时修改了映射（通过迭代器自己的 remove 操作，或者通过对迭代器返回的映射项执行 setValue 操作除外），则迭代结果是不确定的。set 支持元素移除，通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作可从映射中移除相应的映射关系。它不支持 add 或 addAll 操作。- 返回：
- 此映射中包含的映射关系的 set 视图
equals
boolean equals(Object o)
- 比较指定的对象与此映射是否相等。如果给定的对象也是一个映射，并且这两个映射表示相同的映射关系，则返回 true。更确切地讲，如果 m1.entrySet().equals(m2.entrySet())，则两个映射 m1 和 m2 表示相同的映射关系。这可以确保 equals 方法在不同的 Map 接口实现间运行正常。
- 参数：
o- 要与此映射进行相等性比较的对象- 返回：
- 如果指定的对象等于此映射，则返回 true
- 另请参见：
Object.hashCode(),Hashtable
hashCode
int hashCode()
- 返回此映射的哈希码值。映射的哈希码定义为此映射 entrySet() 视图中每个项的哈希码之和。这确保 m1.equals(m2) 对于任意两个映射 m1 和 m2 而言，都意味着 m1.hashCode()==m2.hashCode()，正如
Object.hashCode()常规协定的要求。- 返回：
- 此映射的哈希码值
- 另请参见：
Map.Entry.hashCode(),Object.equals(Object),equals(Object)
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。
版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。