本文详细介绍了Java中Map接口的功能和方法，包括基本操作、批量操作、视图操作以及比较和散列等内容。此外还提供了Map.Entry接口的说明，以及一些默认可选方法的解释。
public interface Map<K, V> {
/**
* 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>.<p>
*
* 返回map中key-value映射的数量。
* 如果map中包含的元素(key-value映射)数量超过Integer的最大值，返回Integer的最大值。<p>
*
* @return the number of key-value mappings in this map
*/
int size();
/**
* Returns <tt>true</tt> if this map contains no key-value mappings.<p>
*
* 如果map中没有key-value键值对，返回true。<p>
*
* @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.)<p>
*
* 如果该map包含指定key的映射，那么返回true，否则返回false。<p>
*
* @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
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key is null and this map
* does not permit null keys
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持key为null，传入null将抛出NullPointerException<p>
*/
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.<p>
*
* 如果该map含有一个或以上的key映射到指定的value，那么返回true，否则返回false
* 对于大多数Map接口的实现，这个操作可能需要根据map的大小花费相应的线性时间<p>
*
* @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
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified value is null and this
* map does not permit null values
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果map不支持value为null，传入null将抛出NullPointerException<p>
*/
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>
*
* 返回指定key映射的value，如果没有映射返回null<p>
*
* <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.)
*
* <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.<p>
*
* 如果该map允许value为null，返回值value为null不一定表明指定key在该map中没有映射；也可能是key对应的value就是null。
* containsKey操作可用于区分这两种情况<p>
*
* @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
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key is null and this map
* does not permit null keys
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持key为null，传入null将抛出NullPointerException<p>
*/
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>.)<p>
*
* 将key和value以键值对的方式放入map中。
* 如果map中已经包含了以key映射的键值对，那么新的value将会取代旧的value。
* 一个map已经包含以key映射的键值对的依据是m.containsKey(k)的方法返回true。<p>
*
* @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.)<p>
*
* 返回值是key先前对应的value，如果没有key对应的映射，那么返回null
* 如果Map的实现类支持value的值为null，那么返回null也可以表明key在先前对应的value就是null<p>
*
* @throws UnsupportedOperationException if the <tt>put</tt> operation
* is not supported by this map<p>
* 如果该map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map<p>
* 如果map阻止保存指定key或value的类型，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key or value is null
* and this map does not permit null keys or values<p>
* 如果该map不支持key或value为null，传入null将抛出NullPointerException<p>
*
* @throws IllegalArgumentException if some property of the specified key
* or value prevents it from being stored in this map<p>
* 如果该map阻止保存指定key或value的某些属性，抛出IllegalArgumentException异常<p>
*/
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.)<p>
*
* 如果该map包含key的映射，那么删除该映射。<p>
*
* <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>
*
* 返回值是key先前对应的value，如果没有key对应的映射，那么返回null。<p>
*
* <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>
*
* 如果map支持value的值为null，那么返回null也可能表明key在先前对应的value就是null。<p>
*
* <p>The map will not contain a mapping for the specified key once the
* call returns.<p>
*
* 一旦调用返回，该map将不再包含指定key的映射。<p>
*
* @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>.<p>
* 返回值是key先前对应的value，如果没有key对应的映射，那么返回null<p>
*
* @throws UnsupportedOperationException if the <tt>remove</tt> operation
* is not supported by this map<p>
* 如果该map不支持remove操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the key is of an inappropriate type for
* this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
* 如果key是非法类型，那么抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key is null and this
* map does not permit null keys
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
* 如果该map不支持key为null，传入null将抛出NullPointerException<p>
*/
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.<p>
*
* 从指定的map中拷贝所有的映射到该map中。
* 这个调用的作用相当于把指定map中的每一个key-value键值对都调用put(key,value)方法放入该map中。
* 如果在此操作过程中指定map被修改了，那么这个操作的行为是未定义的。<p>
*
* @param m mappings to be stored in this map
* @throws UnsupportedOperationException if the <tt>putAll</tt> operation
* is not supported by this map<p>
* 如果该map不支持putAll操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of a key or value in the
* specified map prevents it from being stored in this map<p>
* 如果key或value是非法类型，那么抛出ClassCastException异常<p>
*
* @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<p>
* 如果指定map为null，或该map不支持key或value为null且指定map中key或value存在null，将抛出NullPointerException<p>
*
* @throws IllegalArgumentException if some property of a key or value in
* the specified map prevents it from being stored in this map<p>
* 如果该map阻止保存指定key或value的某些属性，抛出IllegalArgumentException异常<p>
*/
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.<p>
*
* 删除该map中的所有映射。
* 在调用后该map为空。<p>
*
* @throws UnsupportedOperationException if the <tt>clear</tt> operation
* is not supported by this map<p>
* 如果该map不支持clear操作将抛出异常UnsupportedOperationException<p>
*/
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.<p>
*
* 返回该map中所有key的Set视图。
* 该set是由map支持的，所以对map的更改将影响到set，反之亦然。
* 如果在迭代set的过程中map被修改了(除了迭代器使用自己的remove操作)，那么迭代的结果是未定义的。
* 该set支持删除map中映射的操作，其中方法包括Iterator.remove、Set.remove、removeAll、retainAll及clear。
* 但是不支持add或addAll操作。<p>
*
* @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.<p>
*
* 返回该map中所有value的Collection视图。
* 该collection是由map支持的，所以对map的更改将影响到collection，反之亦然。
* 如果在迭代collection的过程中map被修改了(除了迭代器使用自己的remove操作)，那么迭代的结果是未定义的。
* 该collection支持删除map中映射的操作，其中方法包括Iterator.remove、Collection.remove、removeAll、retainAll及clear。
* 但是不支持add或addAll操作。<p>
*
* @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.<p>
*
* 返回该map中所有映射的Set视图。
* 该set是由map支持的，所以对map的更改将影响到set，反之亦然。
* 如果在迭代set的过程中map被修改了(除了迭代器使用自己的remove操作，或者setValue操作)，那么迭代的结果是未定义的。
* 该set支持删除map中映射的操作，其中方法包括Iterator.remove、Set.remove、removeAll、retainAll及clear。
* 但是不支持add或addAll操作。<p>
*
* @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.<p>
*
* 一条map的记录(一个键值对)。
* Map.entrySet方法返回的collection视图中的元素就是这个类(Entry)。
* 唯一一个获得entry引用的方式，是从collection视图的迭代器中获取。
* 这些Map.Entry对象只在迭代期间有效；
* 更正式的，如果在entry的迭代器返回后，作为支持的map被修改了(除了entry的setValue操作)，那么entry的行为是未定义的。<p>
*
* @see Map#entrySet()
* @since 1.2
*/
interface Entry<K, V> {
/**
* Returns the key corresponding to this entry.<p>
*
* 返回该entry对应的key。<p>
*
* @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.<p>
* 一种实现方式，但是不做要求，如果entry已经被支持的map中删除了，抛出IllegalStateException异常<p>
*/
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.<p>
*
* 返回该entry对应的value。
* 如果在作为支持的map中删除了该映射(用迭代器的remove操作)，那么调用的结果是未定义的。<p>
*
* @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.<p>
* 一种实现方式，但是不做要求，如果entry已经被支持的map中删除了，抛出IllegalStateException异常<p>
*/
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).<p>
*
* 用指定value替换该entry中对应的value(可选的操作)。
* 该操作会影响到map上。
* 如果在map上的映射已经被删除了(使用迭代器的remove方法)，那么这个行为的调用是未定义的。<p>
*
* @param value new value to be stored in this entry
* @return old value corresponding to the entry<p>
* 返回值是先前entry对应的value值<p>
*
* @throws UnsupportedOperationException if the <tt>put</tt> operation
* is not supported by the backing map<p>
* 如果作为支持的map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of the specified value
* prevents it from being stored in the backing map<p>
* 如果指定value的类是被作为支持的map阻止的，那么抛出ClassCastException异常<p>
*
* @throws NullPointerException if the backing map does not permit
* null values, and the specified value is null<p>
* 如果作为支持map不支持value为null，传入null将抛出NullPointerException<p>
*
* @throws IllegalArgumentException if some property of this value
* prevents it from being stored in the backing map<p>
* 如果作为支持的map阻止保存指定value的某些属性，抛出IllegalArgumentException异常<p>
*
* @throws IllegalStateException implementations may, but are not
* required to, throw this exception if the entry has been
* removed from the backing map.<p>
* 一种实现方式，但是不做要求，如果entry已经被支持的map中删除了，抛出IllegalStateException异常<p>
*/
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>
* This ensures that the <tt>equals</tt> method works properly across
* different implementations of the <tt>Map.Entry</tt> interface.<p>
*
* 平等地比较指定object和该entry是否相等。
* 如果指定的object也是一个entry，并且这两个entry表示同一个映射，那么返回true。
* 更正式的，按照如下方式判断两个entry是否相等：
* (e1.getKey()==null ? e2.getKey()==null : e1.getKey().equals(e2.getKey()))
* &&
* (e1.getValue()==null ? e2.getValue()==null : e1.getValue().equals(e2.getValue()))
* 这样确保了equals方法可以在不同的Map.Entry实现类中正常工作。<p>
*
* @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<p>
* 如果指定object和该entry相等，返回true<p>
*/
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>
* 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>.<p>
*
* 返回该entry的哈希码。
* 一个entry的哈希码是按照如下定义的：
* (e.getKey()==null ? 0 : e.getKey().hashCode()) ^ (e.getValue()==null ? 0 : e.getValue().hashCode())
* 这样确保了对于任意两个entry如e1和e2，如果e1.equals(e2)，那么意味着e1.hashCode()==e2.hashCode()，
* 按照一般的要求规定Object.hasCode。<p>
*
* @return the hash code value for this map entry
* @see Object#hashCode()
* @see Object#equals(Object)
* @see #equals(Object)
*/
int hashCode();
/**
* Returns a comparator that compares {@link Map.Entry} in natural order on key.<p>
*
* 返回一个Map.Entry的比较器，按照key的自然排序进行比较。<p>
*
* <p>The returned comparator is serializable and throws {@link
* NullPointerException} when comparing an entry with a null key.<p>
*
* 返回的比较器是可序列化的，当entry与空值进行比较时抛出NullPointerException。<p>
*
* @param <K> the {@link Comparable} type of then map keys<p>
* key的泛型要求实现Comparable接口，因为返回的Comparator接口的compare方法要使用key泛型的compareTo接口进行比较<p>
*
* @param <V> the type of the map values
* @return a comparator that compares {@link Map.Entry} in natural order on key.
* @see Comparable
* @since 1.8
*/
public static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K, V>> comparingByKey() {
// 返回比较器对Map.Entry<K, V>进行比较，比较的方式采用key的自然排序
// &表示返回比较器既要实现Comparator接口，也要实现Serializable接口
// 采用Lambda表达式形式返回函数式接口Comparator
return (Comparator<Map.Entry<K, V>> & Serializable) (c1, c2) -> c1.getKey().compareTo(c2.getKey());
}
/**
* Returns a comparator that compares {@link Map.Entry} in natural order on value.<p>
*
* 返回一个Map.Entry的比较器，按照value的自然排序进行比较。<p>
*
* <p>The returned comparator is serializable and throws {@link
* NullPointerException} when comparing an entry with null values.<p>
*
* 返回的比较器是可序列化的，当entry与空值进行比较时抛出NullPointerException<p>
*
* @param <K> the type of the map keys
* @param <V> the {@link Comparable} type of the map values<p>
* value的泛型要求实现Comparable接口，因为返回的Comparator接口的compare方法要使用value泛型的compareTo接口进行比较<p>
*
* @return a comparator that compares {@link Map.Entry} in natural order on value.
* @see Comparable
* @since 1.8
*/
public static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K, V>> comparingByValue() {
return (Comparator<Map.Entry<K, V>> & Serializable) (c1, c2) -> c1.getValue().compareTo(c2.getValue());
}
/**
* Returns a comparator that compares {@link Map.Entry} by key using the given
* {@link Comparator}.<p>
*
* 返回一个Map.Entry的比较器，使用给定key的比较器进行比较。<p>
*
* <p>The returned comparator is serializable if the specified comparator
* is also serializable.<p>
*
* 如果指定的比较器是可序列化的，那么返回的比较器也要求是可序列化的。<p>
*
* @param <K> the type of the map keys
* @param <V> the type of the map values
* @param cmp the key {@link Comparator}<p>
* 入参cmp是一个比较器<p>
*
* @return a comparator that compares {@link Map.Entry} by the key.
* @since 1.8
*/
public static <K, V> Comparator<Map.Entry<K, V>> comparingByKey(Comparator<? super K> cmp) {
// 判断cmp是否为空，如果为空抛出NullPointerException
Objects.requireNonNull(cmp);
return (Comparator<Map.Entry<K, V>> & Serializable) (c1, c2) -> cmp.compare(c1.getKey(), c2.getKey());
}
/**
* Returns a comparator that compares {@link Map.Entry} by value using the given
* {@link Comparator}.<p>
*
* 返回一个Map.Entry的比较器，使用给定value的比较器进行比较。<p>
*
* <p>The returned comparator is serializable if the specified comparator
* is also serializable.<p>
*
* 如果指定的比较器是可序列化的，那么返回的比较器也要求是可序列化的。<p>
*
* @param <K> the type of the map keys
* @param <V> the type of the map values
* @param cmp the value {@link Comparator}
* @return a comparator that compares {@link Map.Entry} by the value.
* @since 1.8
*/
public static <K, V> Comparator<Map.Entry<K, V>> comparingByValue(Comparator<? super V> cmp) {
Objects.requireNonNull(cmp);
return (Comparator<Map.Entry<K, V>> & Serializable) (c1, c2) -> cmp.compare(c1.getValue(), c2.getValue());
}
}
// 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.<p>
*
* 平等地比较指定object和该map是否相等。
* 如果指定的object也是一个map，并且这两个map表示同一个映射，那么返回true。
* 更正式的，对于两个map如m1和m2，如果m1.entrySet().equals(m2.entrySet())，那么他们代表相同的映射。
* 这样确保了equals方法可以在不同的Map实现类中正常工作。<p>
*
* @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的哈希码。
* 一个map的哈希码被定义为该map的entrySet视图中每个entry的哈希码的和。
* 这样确保了对于任意两个map如m1和m2，如果m1.equals(m2)，那么意味着e1.hashCode()==e2.hashCode()，
* 按照一般的要求规定Object.hasCode。
*
* @return the hash code value for this map
* @see Map.Entry#hashCode()
* @see Object#equals(Object)
* @see #equals(Object)
*/
int hashCode();
// Defaultable methods
/**
* Returns the value to which the specified key is mapped, or
* {@code defaultValue} if this map contains no mapping for the key.<p>
*
* 返回指定的key对应的value，如果map不包含key的映射，那么返回传入的默认值。 <p>
*
* @implSpec
* The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties. <p>
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。 <p>
*
* @param key the key whose associated value is to be returned
* @param defaultValue the default mapping of the key
* @return the value to which the specified key is mapped, or
* {@code defaultValue} if this map contains no mapping for the key
* @throws ClassCastException if the key is of an inappropriate type for
* this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key is null and this map
* does not permit null keys
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持key为null，传入null将抛出NullPointerException<p>
*
* @since 1.8
*/
default V getOrDefault(Object key, V defaultValue) {
V v;
return (((v = get(key)) != null) || containsKey(key)) ? v : defaultValue;
}
/**
* Performs the given action for each entry in this map until all entries
* have been processed or the action throws an exception. Unless
* otherwise specified by the implementing class, actions are performed in
* the order of entry set iteration (if an iteration order is specified.)
* Exceptions thrown by the action are relayed to the caller.<p>
*
* 在此map中对每个entry执行给定的操作，直到所有的entry执行完成或者抛出异常。
* 除非实现类另有规定，否则操作将按照entey set迭代器的顺序执行(如果迭代器指定了顺序)。
* 由操作引发的的异常会传递给调用者。<p>
*
* @implSpec
* The default implementation is equivalent to, for this {@code map}:
* <pre> {@code
* for (Map.Entry<K, V> entry : map.entrySet())
* action.accept(entry.getKey(), entry.getValue());
* }</pre><p>
*
* 默认的实现等价于如下：<p>
* for (Map.Entry<K, V> entry : map.entrySet())
* action.accept(entry.getKey(), entry.getValue());
* }<p>
*
* The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties.
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。 <p>
*
* @param action The action to be performed for each entry
* @throws NullPointerException if the specified action is null
* @throws ConcurrentModificationException if an entry is found to be
* removed during iteration
* @since 1.8
*/
default void forEach(BiConsumer<? super K, ? super V> action) {
Objects.requireNonNull(action);
for (Map.Entry<K, V> entry : entrySet()) {
K k;
V v;
try {
k = entry.getKey();
v = entry.getValue();
} catch (IllegalStateException ise) {
// this usually means the entry is no longer in the map.
throw new ConcurrentModificationException(ise);
}
action.accept(k, v);
}
}
/**
* Replaces each entry's value with the result of invoking the given
* function on that entry until all entries have been processed or the
* function throws an exception. Exceptions thrown by the function are
* relayed to the caller.<p>
*
* 将每个entry的value替换为在该entry上调用给定函数的结果，直到所有的entry执行完成或者抛出异常。
* 由操作引发的的异常会传递给调用者。<p>
*
* @implSpec
* <p>The default implementation is equivalent to, for this {@code map}:
* <pre> {@code
* for (Map.Entry<K, V> entry : map.entrySet())
* entry.setValue(function.apply(entry.getKey(), entry.getValue()));
* }</pre><p>
*
* 默认的实现等价于如下：<p>
* for (Map.Entry<K, V> entry : map.entrySet())
* entry.setValue(function.apply(entry.getKey(), entry.getValue()));
* }<p>
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties.<p>
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。 <p>
*
* @param function the function to apply to each entry
* @throws UnsupportedOperationException if the {@code set} operation
* is not supported by this map's entry set iterator.
* @throws ClassCastException if the class of a replacement value
* prevents it from being stored in this map<p>
*
* 如果key的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified function is null, or the
* specified replacement value is null, and this map does not permit null
* values<p>
*
* 如果该map不支持key为null，传入null将抛出NullPointerException<p>
*
* @throws ClassCastException if a replacement value is of an inappropriate
* type for this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
* @throws NullPointerException if function or a replacement value is null,
* and this map does not permit null keys or values
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
* @throws IllegalArgumentException if some property of a replacement value
* prevents it from being stored in this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
* @throws ConcurrentModificationException if an entry is found to be
* removed during iteration
* @since 1.8
*/
default void replaceAll(BiFunction<? super K, ? super V, ? extends V> function) {
Objects.requireNonNull(function);
for (Map.Entry<K, V> entry : entrySet()) {
K k;
V v;
try {
k = entry.getKey();
v = entry.getValue();
} catch (IllegalStateException ise) {
// this usually means the entry is no longer in the map.
throw new ConcurrentModificationException(ise);
}
// ise thrown from function is not a cme.
v = function.apply(k, v);
try {
entry.setValue(v);
} catch (IllegalStateException ise) {
// this usually means the entry is no longer in the map.
throw new ConcurrentModificationException(ise);
}
}
}
/**
* If the specified key is not already associated with a value (or is mapped
* to {@code null}) associates it with the given value and returns
* {@code null}, else returns the current value.<p>
*
* 如果指定的key没有与一个value关联(或者key的映射值是null)，那么用给定value和key进行关联，
* 并返回null，否则返回当前value。<p>
*
* @implSpec
* The default implementation is equivalent to, for this {@code
* map}:
*
* <pre> {@code
* V v = map.get(key);
* if (v == null)
* v = map.put(key, value);
*
* return v;
* }</pre><p>
*
* 默认的实现等价于如下：<p>
* V v = map.get(key);
* if (v == null)
* v = map.put(key, value);
* return v;<p>
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties.
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。 <p>
*
* @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 the specified key, or
* {@code null} if there was no mapping for the key.
* (A {@code null} return can also indicate that the map
* previously associated {@code null} with the key,
* if the implementation supports null values.)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map<p>
*
* 如果该map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
* @throws ClassCastException if the key or value is of an inappropriate
* type for this map<p>
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key或者value的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key or value is null,
* and this map does not permit null keys or values
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
*
* 如果该map不支持key或value为null，传入null将抛出NullPointerException<p>
*
* @throws IllegalArgumentException if some property of the specified key
* or value prevents it from being stored in this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
*
* 如果该map阻止保存指定key或value的某些属性，抛出IllegalArgumentException异常<p>
*
* @since 1.8
*/
default V putIfAbsent(K key, V value) {
V v = get(key);
if (v == null) {
v = put(key, value);
}
return v;
}
/**
* Removes the entry for the specified key only if it is currently
* mapped to the specified value.<p>
*
* 只有在当前key映射到指定的value时，才会移除指定key对应的entry。<p>
*
* @implSpec
* The default implementation is equivalent to, for this {@code map}:
*
* <pre> {@code
* if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
* map.remove(key);
* return true;
* } else
* return false;
* }</pre>
*
* 默认的实现等价于如下：<p>
* if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
* map.remove(key);
* return true;
* } else
* return false;
* }<p>
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties.<p>
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。 <p>
*
* @param key key with which the specified value is associated
* @param value value expected to be associated with the specified key
* @return {@code true} if the value was removed
* @throws UnsupportedOperationException if the {@code remove} operation
* is not supported by this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持remove操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the key or value is of an inappropriate
* type for this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key或value的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key or value is null,
* and this map does not permit null keys or values
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持key或value为null，传入null将抛出NullPointerException<p>
*
* @since 1.8
*/
default boolean remove(Object key, Object value) {
Object curValue = get(key);
if (!Objects.equals(curValue, value) || (curValue == null && !containsKey(key))) {
return false;
}
remove(key);
return true;
}
/**
* Replaces the entry for the specified key only if currently
* mapped to the specified value.<p>
*
* 只有在当前key映射到指定的value时，才会替换指定key对应的entry。<p>
*
* @implSpec
* The default implementation is equivalent to, for this {@code map}:
*
* <pre> {@code
* if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
* map.put(key, newValue);
* return true;
* } else
* return false;
* }</pre><p>
*
* 默认的实现等价于如下：<p>
* if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
* map.put(key, newValue);
* return true;
* } else
* return false;
* }<p>
*
* The default implementation does not throw NullPointerException
* for maps that do not support null values if oldValue is null unless
* newValue is also null.<p>
*
* 如果oldValue为null，则默认实现不为不支持value为null的map抛出空异常，除非newValue也为null。<p>
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties.<p>
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。 <p>
*
* @param key key with which the specified value is associated
* @param oldValue value expected to be associated with the specified key
* @param newValue value to be associated with the specified key
* @return {@code true} if the value was replaced
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of a specified key or value
* prevents it from being stored in this map<p>
*
* 如果key或者value的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if a specified key or newValue is null,
* and this map does not permit null keys or values<p>
*
* 如果该map不支持key为null，传入指定key为null或者newValue为null将抛出NullPointerException<p>
*
* @throws NullPointerException if oldValue is null and this map does not
* permit null values
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持value为null，并且oldValue为null，将抛出NullPointerException<p>
*
* @throws IllegalArgumentException if some property of a specified key
* or value prevents it from being stored in this map<p>
* 如果该map阻止保存指定key或value的某些属性，抛出IllegalArgumentException异常<p>
*
* @since 1.8
*/
default boolean replace(K key, V oldValue, V newValue) {
Object curValue = get(key);
if (!Objects.equals(curValue, oldValue) || (curValue == null && !containsKey(key))) {
return false;
}
put(key, newValue);
return true;
}
/**
* Replaces the entry for the specified key only if it is
* currently mapped to some value.<p>
*
* 只有在当前key映射到某一个value时，才会替换指定key对应的entry。<p>
*
* @implSpec
* The default implementation is equivalent to, for this {@code map}:
*
* <pre> {@code
* if (map.containsKey(key)) {
* return map.put(key, value);
* } else
* return null;
* }</pre><p>
*
* 默认的实现等价于如下：<p>
* if (map.containsKey(key)) {
* return map.put(key, value);
* } else
* return null;
* }<p>
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties.<p>
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。 <p>
*
* @param key key with which the specified value is associated
* @param value value to be associated with the specified key
* @return the previous value associated with the specified key, or
* {@code null} if there was no mapping for the key.
* (A {@code null} return can also indicate that the map
* previously associated {@code null} with the key,
* if the implementation supports null values.)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key or value is null,
* and this map does not permit null keys or values<p>
*
* 如果该map不支持key或value为null，传入null将抛出NullPointerException<p>
*
* @throws IllegalArgumentException if some property of the specified key
* or value prevents it from being stored in this map<p>
*
* 如果该map阻止保存指定key或value的某些属性，抛出IllegalArgumentException异常<p>
*
* @since 1.8
*/
default V replace(K key, V value) {
V curValue;
if (((curValue = get(key)) != null) || containsKey(key)) {
curValue = put(key, value);
}
return curValue;
}
/**
* If the specified key is not already associated with a value (or is mapped
* to {@code null}), attempts to compute its value using the given mapping
* function and enters it into this map unless {@code null}.<p>
*
* 如果指定的key没有与一个value关联(或者key的映射值是null)，那么尝试使用给定的映射函数计算value值，
* 并将其写入到map中，除非计算出的value值为null。<p>
*
* <p>If the function returns {@code null} no mapping is recorded. If
* the function itself throws an (unchecked) exception, the
* exception is rethrown, and no mapping is recorded. The most
* common usage is to construct a new object serving as an initial
* mapped value or memoized result, as in:
*
* <pre> {@code
* map.computeIfAbsent(key, k -> new Value(f(k)));
* }</pre>
*
* <p>Or to implement a multi-value map, {@code Map<K,Collection<V>>},
* supporting multiple values per key:
*
* <pre> {@code
* map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);
* }</pre><p>
*
* 如果函数返回null，则不记录映射。如果函数本身抛出一个(为检查的)异常，则会重新抛出异常，不记录映射。
* 最常见的用法是构造一个新对象，作为初始映射值或memoized结果，如下：<p>
*
* map.computeIfAbsent(key, k -> new Value(f(k)));<p>
*
* 或者实现多value映射map，Map<K,Collection<V>>，支持一key多value：<p>
*
* map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);<p>
*
* @implSpec
* The default implementation is equivalent to the following steps for this
* {@code map}, then returning the current value or {@code null} if now
* absent:
*
* <pre> {@code
* if (map.get(key) == null) {
* V newValue = mappingFunction.apply(key);
* if (newValue != null)
* map.put(key, newValue);
* }
* }</pre><p>
*
* 默认的实现等价于如下所示，如果没有默认值，则返回当前value或null：<p>
* if (map.get(key) == null) {
* V newValue = mappingFunction.apply(key);
* if (newValue != null)
* map.put(key, newValue);
* }
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties. In particular, all implementations of
* subinterface {@link java.util.concurrent.ConcurrentMap} must document
* whether the function is applied once atomically only if the value is not
* present.<p>
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。
* 特别地，子接口java.util.concurrent.ConcurrentMap的所有实现都必须记录该函数是否仅在原子的情况下才被应用，除非value不存在。<p>
*
* @param key key with which the specified value is to be associated
* @param mappingFunction the function to compute a value
* @return the current (existing or computed) value associated with
* the specified key, or null if the computed value is null
* @throws NullPointerException if the specified key is null and
* this map does not support null keys, or the mappingFunction
* is null<p>
*
* 如果该map不支持keymappingFunction或为null，传入null将抛出NullPointerException<p>
*
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
*
* 如果key或value的类型不符合，抛出ClassCastException异常<p>
*
* @since 1.8
*/
default V computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction) {
Objects.requireNonNull(mappingFunction);
V v;
if ((v = get(key)) == null) {
V newValue;
if ((newValue = mappingFunction.apply(key)) != null) {
put(key, newValue);
return newValue;
}
}
return v;
}
/**
* If the value for the specified key is present and non-null, attempts to
* compute a new mapping given the key and its current mapped value.<p>
*
* 如果指定key对应的value是存在的且不为null，尝试用给定key和当前映射的value计算出一个新的映射关系。<p>
*
* <p>If the function returns {@code null}, the mapping is removed. If the
* function itself throws an (unchecked) exception, the exception is
* rethrown, and the current mapping is left unchanged.<p>
*
* 如果函数返回null，则移除映射。如果函数本身抛出一个(为检查的)异常，则会重新抛出异常，当前映射保持不变。<p>
*
* @implSpec
* The default implementation is equivalent to performing the following
* steps for this {@code map}, then returning the current value or
* {@code null} if now absent:
*
* <pre> {@code
* if (map.get(key) != null) {
* V oldValue = map.get(key);
* V newValue = remappingFunction.apply(key, oldValue);
* if (newValue != null)
* map.put(key, newValue);
* else
* map.remove(key);
* }
* }</pre><p>
*
* 默认的实现等价于如下所示，如果没有默认值，则返回当前value或null：<p>
*
* if (map.get(key) != null) {
* V oldValue = map.get(key);
* V newValue = remappingFunction.apply(key, oldValue);
* if (newValue != null)
* map.put(key, newValue);
* else
* map.remove(key);
* }<p>
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties. In particular, all implementations of
* subinterface {@link java.util.concurrent.ConcurrentMap} must document
* whether the function is applied once atomically only if the value is not
* present.<p>
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。
* 特别地，子接口java.util.concurrent.ConcurrentMap的所有实现都必须记录该函数是否仅在原子的情况下才被应用，除非value不存在。<p>
*
* @param key key with which the specified value is to be associated
* @param remappingFunction the function to compute a value
* @return the new value associated with the specified key, or null if none
* @throws NullPointerException if the specified key is null and
* this map does not support null keys, or the
* remappingFunction is null<p>
*
* 如果该map不支持key为null，传入null将抛出NullPointerException<p>
*
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key或者value的类型不符合，抛出ClassCastException异常<p>
*
* @since 1.8
*/
default V computeIfPresent(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
Objects.requireNonNull(remappingFunction);
V oldValue;
if ((oldValue = get(key)) != null) {
V newValue = remappingFunction.apply(key, oldValue);
if (newValue != null) {
put(key, newValue);
return newValue;
} else {
remove(key);
return null;
}
} else {
return null;
}
}
/**
* Attempts to compute a mapping for the specified key and its current
* mapped value (or {@code null} if there is no current mapping). For
* example, to either create or append a {@code String} msg to a value
* mapping:
*
* <pre> {@code
* map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))}</pre>
* (Method {@link #merge merge()} is often simpler to use for such purposes.)
*
* <p>If the function returns {@code null}, the mapping is removed (or
* remains absent if initially absent). If the function itself throws an
* (unchecked) exception, the exception is rethrown, and the current mapping
* is left unchanged.<p>
*
* 尝试用给定key和当前映射的value(如果没有映射，则为null)计算出一个新的映射关系。
* 例如，要创建或者追加一个String msg到一个value的映射：<p>
*
* map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))
* (通常，merge方法用作这样的目标是比较简单的。)<p>
*
* 如果函数返回null，则移除映射(如果初始就没有值，那么现在仍然没有值)。
* 如果函数本身抛出一个(为检查的)异常，则会重新抛出异常，当前映射保持不变。<p>
*
* @implSpec
* The default implementation is equivalent to performing the following
* steps for this {@code map}, then returning the current value or
* {@code null} if absent:
*
* <pre> {@code
* V oldValue = map.get(key);
* V newValue = remappingFunction.apply(key, oldValue);
* if (oldValue != null ) {
* if (newValue != null)
* map.put(key, newValue);
* else
* map.remove(key);
* } else {
* if (newValue != null)
* map.put(key, newValue);
* else
* return null;
* }
* }</pre><p>
*
* 默认的实现等价于如下所示，如果没有默认值，则返回当前value或null：<p>
*
* V oldValue = map.get(key);
* V newValue = remappingFunction.apply(key, oldValue);
* if (oldValue != null ) {
* if (newValue != null)
* map.put(key, newValue);
* else
* map.remove(key);
* } else {
* if (newValue != null)
* map.put(key, newValue);
* else
* return null;
* }<p>
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties. In particular, all implementations of
* subinterface {@link java.util.concurrent.ConcurrentMap} must document
* whether the function is applied once atomically only if the value is not
* present.<p>
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。
* 特别地，子接口java.util.concurrent.ConcurrentMap的所有实现都必须记录该函数是否仅在原子的情况下才被应用，除非value不存在。<p>
*
* @param key key with which the specified value is to be associated
* @param remappingFunction the function to compute a value
* @return the new value associated with the specified key, or null if none
* @throws NullPointerException if the specified key is null and
* this map does not support null keys, or the
* remappingFunction is null<p>
*
* 如果该map不支持key为null，传入null将抛出NullPointerException<p>
*
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key或value的类型不符合，抛出ClassCastException异常<p>
*
* @since 1.8
*/
default V compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction) {
Objects.requireNonNull(remappingFunction);
V oldValue = get(key);
V newValue = remappingFunction.apply(key, oldValue);
if (newValue == null) {
// delete mapping
if (oldValue != null || containsKey(key)) {
// something to remove
remove(key);
return null;
} else {
// nothing to do. Leave things as they were.
return null;
}
} else {
// add or replace old mapping
put(key, newValue);
return newValue;
}
}
/**
* If the specified key is not already associated with a value or is
* associated with null, associates it with the given non-null value.
* Otherwise, replaces the associated value with the results of the given
* remapping function, or removes if the result is {@code null}. This
* method may be of use when combining multiple mapped values for a key.
* For example, to either create or append a {@code String msg} to a
* value mapping:
*
* <pre> {@code
* map.merge(key, msg, String::concat)
* }</pre>
*
* <p>If the function returns {@code null} the mapping is removed. If the
* function itself throws an (unchecked) exception, the exception is
* rethrown, and the current mapping is left unchanged.<p>
*
* 如果指定的key没有与一个value关联或者key的映射值是null，那么用给定的非空value和key进行关联。
* 否则，使用给定的remapping函数计算结果替换之前关联的value。如果计算结果为null，移除之前关联的value。
* 这个方法可能会用在当将多个映射值组合在一起。例如，要创建或者追加一个String msg到一个value的映射：<p>
*
* @implSpec
* The default implementation is equivalent to performing the following
* steps for this {@code map}, then returning the current value or
* {@code null} if absent:
*
* <pre> {@code
* V oldValue = map.get(key);
* V newValue = (oldValue == null) ? value :
* remappingFunction.apply(oldValue, value);
* if (newValue == null)
* map.remove(key);
* else
* map.put(key, newValue);
* }</pre>
*
* 默认的实现等价于如下所示，如果没有默认值，则返回当前value或null：<p>
* V oldValue = map.get(key);
* V newValue = (oldValue == null) ? value :
* remappingFunction.apply(oldValue, value);
* if (newValue == null)
* map.remove(key);
* else
* map.put(key, newValue);<p>
*
*
* <p>The default implementation makes no guarantees about synchronization
* or atomicity properties of this method. Any implementation providing
* atomicity guarantees must override this method and document its
* concurrency properties. In particular, all implementations of
* subinterface {@link java.util.concurrent.ConcurrentMap} must document
* whether the function is applied once atomically only if the value is not
* present.
*
* 默认实现不保证该方法的同步性或原子性属性。任何提供原子性保证的实现都必须重写此方法并记录其并发性。
* 特别地，子接口java.util.concurrent.ConcurrentMap的所有实现都必须记录该函数是否仅在原子的情况下才被应用，除非value不存在。<p>
*
* @param key key with which the resulting value is to be associated
* @param value the non-null value to be merged with the existing value
* associated with the key or, if no existing value or a null value
* is associated with the key, to be associated with the key
* @param remappingFunction the function to recompute a value if present
* @return the new value associated with the specified key, or null if no
* value is associated with the key
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果该map不支持put操作将抛出异常UnsupportedOperationException<p>
*
* @throws ClassCastException if the class of the specified key or value
* prevents it from being stored in this map
* (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)<p>
*
* 如果key的类型不符合，抛出ClassCastException异常<p>
*
* @throws NullPointerException if the specified key is null and this map
* does not support null keys or the value or remappingFunction is
* null<p>
*
* 如果该map不支持key为null，传入null将抛出NullPointerException<p>
*
* @since 1.8
*/
default V merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction) {
Objects.requireNonNull(remappingFunction);
Objects.requireNonNull(value);
V oldValue = get(key);
V newValue = (oldValue == null) ? value : remappingFunction.apply(oldValue, value);
if (newValue == null) {
remove(key);
} else {
put(key, newValue);
}
return newValue;
}
}
扫一扫
1895
评论
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
查看更多评论
添加红包
