class="java" name="code">package java.util; /** * An object that maps keys to values. A map cannot contain duplicate keys; * each key can map to at most one value. * Map是一个存储k-v对的对象，一个Map不能包含重复的key，每一个key只能对应一个值。 * <p>This interface takes the place of the <tt>Dictionary</tt> class, which * was a totally abstract class rather than an interface. * Map取代了Dictionary，Dictionary是一个抽象类，而非接口。 * <p>The <tt>Map</tt> interface provides three <i>collection views</i>, which * allow a map's contents to be viewed as a set of keys, collection of values, * or set of key-value mappings. The <i>order</i> of a map is defined as * the order in which the iterators on the map's collection views return their * elements. Some map implementations, like the <tt>TreeMap</tt> class, make * specific guarantees as to their order; others, like the <tt>HashMap</tt> * class, do not. * Map提供了3个集合的视图，一个为Key set，一个为value collection和一个k-v对Set。 Map的顺序与map的集合类视图的iterators的顺序相同。TreeMap实现了它自己的排序， 而HashMap则没有。 * <p>Note: great care must be exercised if mutable objects are used as map * keys. The behavior of a map is not specified if the value of an object is * changed in a manner that affects <tt>equals</tt> comparisons while the * object is a key in the map. A special case of this prohibition is that it * is not permissible for a map to contain itself as a key. While it is * permissible for a map to contain itself as a value, extreme caution is * advised: the <tt>equals</tt> and <tt>hashCode</tt> methods are no longer * well defined on such a map. * 当我们选择object做key的时候要特别小心。如果一个key是变化的，那么我们就不能，精确 定位到key对应的值。特别的提醒，禁止一个Map做为key。建议equals和hashCode方法， 不要在Map中定义。 * <p>All general-purpose map implementation classes should provide two * "standard" constructors: a void (no arguments) constructor which creates an * empty map, and a constructor with a single argument of type <tt>Map</tt>, * which creates a new map with the same key-value mappings as its argument. * In effect, the latter constructor allows the user to copy any map, * producing an equivalent map of the desired class. There is no way to * enforce this recommendation (as interfaces cannot contain constructors) but * all of the general-purpose map implementations in the JDK comply. * Map的实现类，一般情况下要提供2个标准的构造函数，一个是无参的，用于创建一个空Map， 一个待Map类型的构造，用于创建一个与参数Map相同k-v映射的Map。有参的构造是用于 复制any Map 到一个相同类型的Map中。当然我们只是建议，这个非强制。 * <p>The "destructive" methods contained in this interface, that is, the * methods that modify the map on which they operate, are specified to throw * <tt>UnsupportedOperationException</tt> if this map does not support the * operation. If this is the case, these methods may, but are not required * to, throw an <tt>UnsupportedOperationException</tt> if the invocation would * have no effect on the map. For example, invoking the {@link #putAll(Map)} * method on an unmodifiable map may, but is not required to, throw the * exception if the map whose mappings are to be "superimposed" is empty. * Map可能包含destructive性质的方法，当使用这些方法修改Map时，如果Map支持这些操作， 则抛出UnsupportedOperationException。如果destructive性质的方法，对Map没有什么影响， 则不再需要抛出异常。比如unmodifiable map 调用putAll(Map)方法，是不需要抛出异常的。 * <p>Some map implementations have restrictions on the keys and values they * may contain. For example, some implementations prohibit null keys and * values, and some have restrictions on the types of their keys. Attempting * to insert an ineligible key or value throws an unchecked exception, * typically <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. * Attempting to query the presence of an ineligible key or value may throw an * exception, or it may simply return false; some implementations will exhibit * the former behavior and some will exhibit the latter. More generally, * attempting an operation on an ineligible key or value whose completion * would not result in the insertion of an ineligible element into the map may * throw an exception or it may succeed, at the option of the implementation. * Such exceptions are marked as "optional" in the specification for this * interface. * 有些Map的实现类，对key和value有严格的限制。比如禁止key和value为null，对key的类型 有限制。尝试插入一个非符合条件的key或value将抛出unchecked exception，具体如 NullPointerException， ClassCastException。尝试查询一个非符合条件的key和value， 也许会抛出一个异常或仅仅返回false；一些实现是抛出异常，其他一些是返回false。 一般情况下，在插入一个非符合条件的k-v时，实际不会插入到Map中， 我们可以选择，是抛出异常，还是可能插入成功。 * <p>This interface is a member of the * <a href="{@docRoot}/../technotes/guides/collections/index.html"> * Java Collections Framework</a>. * * <p>Many methods in Collections Framework interfaces are defined * in terms of the {@link Object#equals(Object) equals} method. For * example, the specification for the {@link #containsKey(Object) * containsKey(Object key)} method says: "returns <tt>true</tt> if and * only if this map contains a mapping for a key <tt>k</tt> such that * <tt>(key==null ? k==null : key.equals(k))</tt>." This specification should * <i>not</i> be construed to imply that invoking <tt>Map.containsKey</tt> * with a non-null argument <tt>key</tt> will cause <tt>key.equals(k)</tt> to * be invoked for any key <tt>k</tt>. Implementations are free to * implement optimizations whereby the <tt>equals</tt> invocation is avoided, * for example, by first comparing the hash codes of the two keys. (The * {@link Object#hashCode()} specification guarantees that two objects with * unequal hash codes cannot be equal.) More generally, implementations of * the various Collections Framework interfaces are free to take advantage of * the specified behavior of underlying {@link Object} methods wherever the * implementor deems it appropriate. * 在集合Collections框架中，都重新定义了 Object#equals(Object) equals方法。 比如说containsKey(Object)和containsKey(Object key)方法，判断Map中是否存在对应的Key。 只有非null的key我们才会进行比较。在我们实现的时候，equals是可以避免的，我们在 比较key的时候，首先比较的是hashCode，如果hashCode不相等，则两个对象就不等。具体的比较 实现我们可以根据具体场景，具体选择。 * @param <K> the type of keys maintained by this map * @param <V> the type of mapped values * * @author Josh Bloch * @see HashMap * @see TreeMap * @see Hashtable * @see SortedMap * @see Collection * @see Set * @since 1.2 */ public interface Map<K,V> { // Query Operations /** * Returns the number of key-value mappings in this map. If the * map contains more than <tt>Integer.MAX_VALUE</tt> elements, returns * <tt>Integer.MAX_VALUE</tt>. *返回Map的k-v对数量，最大值为Integer.MAX_VALUE，超过，则返回Integer.MAX_VALUE * @return the number of key-value mappings in this map */ int size(); /** * Returns <tt>true</tt> if this map contains no key-value mappings. *Map是否为null，即没有k-v * @return <tt>true</tt> if this map contains no key-value mappings */ boolean isEmpty(); /** * Returns <tt>true</tt> if this map contains a mapping for the specified * key. More formally, returns <tt>true</tt> if and only if * this map contains a mapping for a key <tt>k</tt> such that * <tt>(key==null ? k==null : key.equals(k))</tt>. (There can be * at most one such mapping.) * 如果Map中包含key，则返回true。当且仅当，map存在唯一的key时，才返回true * @param key key whose presence in this map is to be tested * @return <tt>true</tt> if this map contains a mapping for the specified * key * @throws ClassCastException if the key is of an inappropriate type for * this map * ([url=Collection.html#optional-restrictions]optional[/url]) * @throws NullPointerException if the specified key is null and this map * does not permit null keys * ([url=Collection.html#optional-restrictions]optional[/url]) */ boolean containsKey(Object key); /** * Returns <tt>true</tt> if this map maps one or more keys to the * specified value. More formally, returns <tt>true</tt> if and only if * this map contains at least one mapping to a value <tt>v</tt> such that * <tt>(value==null ? v==null : value.equals(v))</tt>. This operation * will probably require time linear in the map size for most * implementations of the <tt>Map</tt> interface. * 当队列中有一个或多个key对应的值为value，则返回true，这个操作的时间复杂度是线性的O（n）， 在大多数的Map实现类中 * @param value value whose presence in this map is to be tested * @return <tt>true</tt> if this map maps one or more keys to the * specified value * @throws ClassCastException if the value is of an inappropriate type for * this map * ([url=Collection.html#optional-restrictions]optional[/url]) * @throws NullPointerException if the specified value is null and this * map does not permit null values * ([url=Collection.html#optional-restrictions]optional[/url]) */ boolean containsValue(Object value); /** * Returns the value to which the specified key is mapped, * or {@code null} if this map contains no mapping for the key. * * <p>More formally, if this map contains a mapping from a key * {@code k} to a value {@code v} such that {@code (key==null ? k==null : * key.equals(k))}, then this method returns {@code v}; otherwise * it returns {@code null}. (There can be at most one such mapping.) * 返回key对应值value，如果没有对应的key，则返回为null。 * <p>If this map permits null values, then a return value of * {@code null} does not <i>necessarily</i> indicate that the map * contains no mapping for the key; it's also possible that the map * explicitly maps the key to {@code null}. The {@link #containsKey * containsKey} operation may be used to distinguish these two cases. *如果Map允许Null值的存在，则返回null是不必要的。 * @param key the key whose associated value is to be returned * @return the value to which the specified key is mapped, or * {@code null} if this map contains no mapping for the key * @throws ClassCastException if the key is of an inappropriate type for * this map * ([url=Collection.html#optional-restrictions]optional[/url]) * @throws NullPointerException if the specified key is null and this map * does not permit null keys * ([url=Collection.html#optional-restrictions]optional[/url]) */ V get(Object key); // Modification Operations /** * Associates the specified value with the specified key in this map * (optional operation). If the map previously contained a mapping for * the key, the old value is replaced by the specified value. (A map * <tt>m</tt> is said to contain a mapping for a key <tt>k</tt> if and only * if {@link #containsKey(Object) m.containsKey(k)} would return * <tt>true</tt>.) * 将一个k-v对，放入到Map中，如果Map已经存在对应的Key，则新的值，将覆盖旧值 * @param key key with which the specified value is to be associated * @param value value to be associated with the specified key * @return the previous value associated with <tt>key</tt>, or * <tt>null</tt> if there was no mapping for <tt>key</tt>. * (A <tt>null</tt> return can also indicate that the map * previously associated <tt>null</tt> with <tt>key</tt>, * if the implementation supports <tt>null</tt> values.) * @throws UnsupportedOperationException if the <tt>put</tt> operation * is not supported by this map * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map * @throws NullPointerException if the specified key or value is null * and this map does not permit null keys or values * @throws IllegalArgumentException if some property of the specified key * or value prevents it from being stored in this map */ V put(K key, V value); /** * Removes the mapping for a key from this map if it is present * (optional operation). More formally, if this map contains a mapping * from key <tt>k</tt> to value <tt>v</tt> such that * <code>(key==null ? k==null : key.equals(k))</code>, that mapping * is removed. (The map can contain at most one such mapping.) *从Map移除对应的k-v对 * <p>Returns the value to which this map previously associated the key, * or <tt>null</tt> if the map contained no mapping for the key. * * <p>If this map permits null values, then a return value of * <tt>null</tt> does not <i>necessarily</i> indicate that the map * contained no mapping for the key; it's also possible that the map * explicitly mapped the key to <tt>null</tt>. * * <p>The map will not contain a mapping for the specified key once the * call returns. * * @param key key whose mapping is to be removed from the map * @return the previous value associated with <tt>key</tt>, or * <tt>null</tt> if there was no mapping for <tt>key</tt>. * @throws UnsupportedOperationException if the <tt>remove</tt> operation * is not supported by this map * @throws ClassCastException if the key is of an inappropriate type for * this map * ([url=Collection.html#optional-restrictions]optional[/url]) * @throws NullPointerException if the specified key is null and this * map does not permit null keys * ([url=Collection.html#optional-restrictions]optional[/url]) */ V remove(Object key); // Bulk Operations /** * Copies all of the mappings from the specified map to this map * (optional operation). The effect of this call is equivalent to that * of calling {@link #put(Object,Object) put(k, v)} on this map once * for each mapping from key <tt>k</tt> to value <tt>v</tt> in the * specified map. The behavior of this operation is undefined if the * specified map is modified while the operation is in progress. * copy一个Map到当前Map，即遍历Copy Map的k-v，放入到当前Map中 * @param m mappings to be stored in this map * @throws UnsupportedOperationException if the <tt>putAll</tt> operation * is not supported by this map * @throws ClassCastException if the class of a key or value in the * specified map prevents it from being stored in this map * @throws NullPointerException if the specified map is null, or if * this map does not permit null keys or values, and the * specified map contains null keys or values * @throws IllegalArgumentException if some property of a key or value in * the specified map prevents it from being stored in this map */ void putAll(Map<? extends K, ? extends V> m); /** * Removes all of the mappings from this map (optional operation). * The map will be empty after this call returns. * 从当前Map中，移除所有的k-v对 * @throws UnsupportedOperationException if the <tt>clear</tt> operation * is not supported by this map */ void clear(); // Views /** * Returns a {@link Set} view of the keys contained in this map. * The set is backed by the map, so changes to the map are * reflected in the set, and vice-versa. If the map is modified * while an iteration over the set is in progress (except through * the iterator's own <tt>remove</tt> operation), the results of * the iteration are undefined. The set supports element removal, * which removes the corresponding mapping from the map, via the * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>, * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt> * operations. It does not support the <tt>add</tt> or <tt>addAll</tt> * operations. * 返回Map中key的视图Set，key Set与Map相关联，当Map改变时，将会影响Key set， 反之亦然。我们可以通过key Set的Iterator移除Map中的k-v * @return a set view of the keys contained in this map */ Set<K> keySet(); /** * Returns a {@link Collection} view of the values contained in this map. * The collection is backed by the map, so changes to the map are * reflected in the collection, and vice-versa. If the map is * modified while an iteration over the collection is in progress * (except through the iterator's own <tt>remove</tt> operation), * the results of the iteration are undefined. The collection * supports element removal, which removes the corresponding * mapping from the map, via the <tt>Iterator.remove</tt>, * <tt>Collection.remove</tt>, <tt>removeAll</tt>, * <tt>retainAll</tt> and <tt>clear</tt> operations. It does not * support the <tt>add</tt> or <tt>addAll</tt> operations. * 返回Map中value的视图Collection，这Collection与Map相关联，当Map改变时， 直接映射Value的视图Collection，反之亦然。 * @return a collection view of the values contained in this map */ Collection<V> values(); /** * Returns a {@link Set} view of the mappings contained in this map. * The set is backed by the map, so changes to the map are * reflected in the set, and vice-versa. If the map is modified * while an iteration over the set is in progress (except through * the iterator's own <tt>remove</tt> operation, or through the * <tt>setValue</tt> operation on a map entry returned by the * iterator) the results of the iteration are undefined. The set * supports element removal, which removes the corresponding * mapping from the map, via the <tt>Iterator.remove</tt>, * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and * <tt>clear</tt> operations. It does not support the * <tt>add</tt> or <tt>addAll</tt> operations. * 返回Map中所有K-v对的视图Set，k-v Set与Map相关联，当Map改变时，将会影响k-v set， 反之亦然。我们可以通过k-v Set的Iterator移除Map中的k-v * @return a set view of the mappings contained in this map */ Set<Map.Entry<K, V>> entrySet(); /** * A map entry (key-value pair). The <tt>Map.entrySet</tt> method returns * a collection-view of the map, whose elements are of this class. The * <i>only</i> way to obtain a reference to a map entry is from the * iterator of this collection-view. These <tt>Map.Entry</tt> objects are * valid <i>only</i> for the duration of the iteration; more formally, * the behavior of a map entry is undefined if the backing map has been * modified after the entry was returned by the iterator, except through * the <tt>setValue</tt> operation on the map entry. * Entry表示一个k-v对，Map.entrySet方法返回的k-v，就是Entry。从获取一个Map.Entry 的方法，只有从entrySet()返回的集合Set<Map.Entry<K, V>>的iterator。 Map.Entry仅仅在遍历iteration的期间有效的，进一步说，当Map通过setValue操作， 修改 Map.Entry时，iteration的返回值是不确定的 * @see Map#entrySet() * @since 1.2 */ interface Entry<K,V> { /** * Returns the key corresponding to this entry. * 返回k-v值对entry的key * @return the key corresponding to this entry * @throws IllegalStateException implementations may, but are not * required to, throw this exception if the entry has been * removed from the backing map. */ K getKey(); /** * Returns the value corresponding to this entry. If the mapping * has been removed from the backing map (by the iterator's * <tt>remove</tt> operation), the results of this call are undefined. * 返回k-v值对，entry的值，如果entry通过iterator从Map中移除，则返回结果是不确定的 * @return the value corresponding to this entry * @throws IllegalStateException implementations may, but are not * required to, throw this exception if the entry has been * removed from the backing map. */ V getValue(); /** * Replaces the value corresponding to this entry with the specified * value (optional operation). (Writes through to the map.) The * behavior of this call is undefined if the mapping has already been * removed from the map (by the iterator's <tt>remove</tt> operation). * 设置k-v值对，entry的值，如果在写到Map的过程中， entry被iterator从Map中移除，则返回结果是不确定的。 * @param value new value to be stored in this entry * @return old value corresponding to the entry * @throws UnsupportedOperationException if the <tt>put</tt> operation * is not supported by the backing map * @throws ClassCastException if the class of the specified value * prevents it from being stored in the backing map * @throws NullPointerException if the backing map does not permit * null values, and the specified value is null * @throws IllegalArgumentException if some property of this value * prevents it from being stored in the backing map * @throws IllegalStateException implementations may, but are not * required to, throw this exception if the entry has been * removed from the backing map. */ V setValue(V value); /** * Compares the specified object with this entry for equality. * Returns <tt>true</tt> if the given object is also a map entry and * the two entries represent the same mapping. More formally, two * entries <tt>e1</tt> and <tt>e2</tt> represent the same mapping * if<pre> * (e1.getKey()==null ? * e2.getKey()==null : e1.getKey().equals(e2.getKey())) && * (e1.getValue()==null ? * e2.getValue()==null : e1.getValue().equals(e2.getValue())) * </pre> 判断两个Entry是否相等，当且仅当，k和v都相等时才相等。 * This ensures that the <tt>equals</tt> method works properly across * different implementations of the <tt>Map.Entry</tt> interface. * * @param o object to be compared for equality with this map entry * @return <tt>true</tt> if the specified object is equal to this map * entry */ boolean equals(Object o); /** * Returns the hash code value for this map entry. The hash code * of a map entry <tt>e</tt> is defined to be: <pre> * (e.getKey()==null ? 0 : e.getKey().hashCode()) ^ * (e.getValue()==null ? 0 : e.getValue().hashCode()) * </pre> Entry的hash值，默认定义为k与v的hash值的异或结果 * This ensures that <tt>e1.equals(e2)</tt> implies that * <tt>e1.hashCode()==e2.hashCode()</tt> for any two Entries * <tt>e1</tt> and <tt>e2</tt>, as required by the general * contract of <tt>Object.hashCode</tt>. * * @return the hash code value for this map entry * @see Object#hashCode() * @see Object#equals(Object) * @see #equals(Object) */ int hashCode(); } // Comparison and hashing /** * Compares the specified object with this map for equality. Returns * <tt>true</tt> if the given object is also a map and the two maps * represent the same mappings. More formally, two maps <tt>m1</tt> and * <tt>m2</tt> represent the same mappings if * <tt>m1.entrySet().equals(m2.entrySet())</tt>. This ensures that the * <tt>equals</tt> method works properly across different implementations * of the <tt>Map</tt> interface. * 判断两个Map的所有Entry值是否相等 * @param o object to be compared for equality with this map * @return <tt>true</tt> if the specified object is equal to this map */ boolean equals(Object o); /** * Returns the hash code value for this map. The hash code of a map is * defined to be the sum of the hash codes of each entry in the map's * <tt>entrySet()</tt> view. This ensures that <tt>m1.equals(m2)</tt> * implies that <tt>m1.hashCode()==m2.hashCode()</tt> for any two maps * <tt>m1</tt> and <tt>m2</tt>, as required by the general contract of * {@link Object#hashCode}. * Map的hash值，默认定义为所有Entry所有hash值之和 * @return the hash code value for this map * @see Map.Entry#hashCode() * @see Object#equals(Object) * @see #equals(Object) */ int hashCode(); }
相关文章
