java.util
接口 Map<K,V>

所有已知子接口：

ConcurrentMap<K,V>, SortedMap<K,V>

所有已知实现类：

AbstractMap, Attributes, AuthProvider, ConcurrentHashMap, EnumMap, HashMap, Hashtable, IdentityHashMap, LinkedHashMap, PrinterStateReasons, Properties, Provider, RenderingHints, 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) 方法时，可能但并不一定抛出异常。

某些映射实现对可能包含的键和值有所限制。例如，某些实现禁止空键和空值，而某些实现则对其键的类型有限制。尝试插入不合格的键或值会抛出一个未经检查的异常，通常是 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 方法的指定行为，而不管实现程序认为它是否合适。

从以下版本开始：

1.2

另请参见：

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 视图。

方法详细信息

size

int size()

返回此映射中的键-值映射关系数。如果该映射包含多个 Integer.MAX_VALUE 元素，则返回 Integer.MAX_VALUE。

返回：

此映射中的键-值映射关系数。

isEmpty

boolean isEmpty()

如果此映射未包含键-值映射关系，则返回 true。

返回：

如果此映射未包含键-值映射关系，则返回 true。

containsKey

boolean containsKey(Object key)

如果此映射包含指定键的映射关系，则返回 true。更正式地说，当且仅当此映射包含键 k 的以下映射关系时才返回 true：(key==null ? k==null : key.equals(k))。（最多只能有一个这样的映射关系）。

参数：

key - 测试在此映射中是否存在的键。

返回：

如果此映射包含指定键的映射关系，则返回 true。

抛出：

ClassCastException - 如果该键对于此映射是不合适的类型（可选）。

NullPointerException - 如果该键为 null 并且此映射不允许 null 键（可选）。

containsValue

boolean containsValue(Object value)

如果此映射为指定值映射一个或多个键，则返回 true。更正式地说，当且仅当此映射至少包含一个 v 的以下映射关系时才返回 true：(value==null ? v==null : value.equals(v))。对于大多数 Map 接口的实现而言，该操作可能需要与映射大小呈线性关系的时间。

参数：

value - 测试在该映射中是否存在的值。

返回：

如果该映射将一个或多个键映射到指定值，则返回 true。

抛出：

ClassCastException - 如果该值对于此映射是不合适的类型（可选）。

NullPointerException - 如果该值为 null 并且此映射不允许 null 值（可选）。

get

V get(Object key)

返回此映射中映射到指定键的值。如果此映射中没有该键的映射关系，则返回 null。返回 null 值并非一定 表明此映射不包含该键的映射关系；也可能此映射将该键显示地映射到 null。可使用 containsKey 操作来区分这两种情况。

更正式地说，如果此映射包含满足以下从键 k 到值 v 的映射关系：(key==null ? k==null :key.equals(k))，则此方法返回 v；否则返回 null（最多只能有一个这样的映射关系）。

参数：

key - 要返回其相关值的键。

返回：

此映射中映射到指定值的键，如果此映射不包含该键的映射关系，则返回 null。

抛出：

ClassCastException - 如果该键对于此映射是不合适的类型（可选）。

NullPointerException - 如果该键为 null 并且此映射不允许 null 键（可选）。

另请参见：

containsKey(Object)

put

V put(K key,
      V value)

将指定的值与此映射中的指定键相关联（可选操作）。如果此映射中以前包含一个该键的映射关系，则用指定值替换旧值（当且仅当 m.containsKey(k) 返回 true 时，才能说映射 m 包含键 k 的映射关系）。

参数：

key - 与指定值相关联的键。

value - 与指定键相关联的值。

返回：

以前与指定键相关联的值，如果没有该键的映射关系，则返回 null。如果该实现支持 null 值，则返回 null 也可表明此映射以前将 null 与指定键相关联。

抛出：

UnsupportedOperationException - 如果此映射不支持 put 操作。

ClassCastException - 如果指定键或值的类不允许将其存储在此映射中。

IllegalArgumentException - 如果此键或值的某些方面不允许将其存储在此映射中。

NullPointerException - 如果此映射不允许 null 键或值，并且指定的键或值为 null。

remove

V remove(Object key)

如果存在此键的映射关系，则将其从映射中移除（可选操作）。更正式地说，如果此映射包含满足以下从键 k 到值 v 的映射关系：(key==null ? k==null :key.equals(k))，则移除该映射关系（该映射最多只能包含一个这样的映射关系）。

返回此映射中以前映射该键的值，如果此映射不包含该键的映射关系，则返回 null（如果该实现支持 null 值，则返回 null 也可表明此映射以前将 null 与指定键相关联）。一旦调用返回，则此映射不包含指定键的映射关系。

参数：

key - 从映射中移除其映射关系的键。

返回：

以前与指定键相关联的值，如果没有该键的映射关系，则返回 null。

抛出：

ClassCastException - 如果该键对于此映射是不合适的类型（可选）。

NullPointerException - 如果该键为 null 并且此映射不允许 null 键（可选）。

UnsupportedOperationException - 如果此映射不支持 remove 操作。

putAll

void putAll(Map<? extends K,? extends V> t)

从指定映射中将所有映射关系复制到此映射中（可选操作）。对于指定映射中的每个键 k 到值 v 的映射关系，该调用的作用等效于在此映射上调用 put(k, v)。如果正在进行此操作的同时修改了指定的映射，则此操作的行为是未指定的。

参数：

t - 要存储在此映射中的映射关系。

抛出：

UnsupportedOperationException - 如果此映射不支持 putAll 方法。

ClassCastException - 如果指定映射中的键或值的类不允许将其存储在此映射中。

IllegalArgumentException - 如果指定映射中的键或值的某些方面不允许将其存储在此映射中。

NullPointerException - 如果指定的映射为 null，或者此映射不允许 null 键或值，并且指定的映射包含 null 键或值。

clear

void clear()

从此映射中移除所有映射关系（可选操作）。

抛出：

UnsupportedOperationException - 此映射不支持清除。

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 中的每个元素都是一个 Map.Entry。该 set 受映射支持，所以对映射的改变可在此 set 中反映出来，反之亦然。如果修改映射的同时正在对该 set 进行迭代（除了通过迭代器自己的 remove 操作，或者通过在迭代器返回的映射项上执行 setValue 操作外），则迭代结果是不明确的。set 支持通过 Iterator.remove、Set.remove、removeAll、retainAll 和 clear 操作实现元素移除，即从映射中移除相应的映射关系。它不支持 add 或 addAll 操作。

返回：

此映射中包含的映射关系的 set 视图。

equals

boolean equals(Object o)

比较指定的对象与此映射是否相等。如果给定的对象也是一个映射，并且这两个映射表示相同的映射关系，则返回 true。更正式地说，如果 t1.entrySet().equals(t2.entrySet())，则两个映射 t1 和 t2 表示相同的映射关系。这可以确保 equals 方法在不同的 Map 接口实现间可正确地工作。

覆盖：

类 Object 中的 equals

参数：

o - 要与此映射进行相等性比较的对象。

返回：

如果指定的对象等于此映射，则返回 true。

另请参见：

Object.hashCode(), Hashtable

hashCode

int hashCode()

返回此映射的哈希码值。映射的哈希码定义为此映射 entrySet 视图中每个项的 hashCode 之和。这确保 t1.equals(t2) 意味着对于任意两个映射 t1 和 t2 而言，t1.hashCode()==t2.hashCode()，这正是 Object.hashCode 常规协定所要求的。

覆盖：

类 Object 中的 hashCode

返回：

此映射的哈希码值。

另请参见：

Map.Entry.hashCode(), Object.hashCode(), Object.equals(Object), equals(Object)