Java java.util 接口 Map<K,V>（JDK5）

所有类

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

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 操作。