Map接口源码分析

矫情吗；* 2022-12-23 11:11 274阅读 0赞

package java.util;
    
    import java.util.function.BiConsumer;
    import java.util.function.BiFunction;
    import java.util.function.Function;
    import java.io.Serializable;
    
    /**
     * 1.概述
     *   (1) 实现键值对映射的对象。Map存放的键值对（key-value）中，不能包含重复的键（键可以为null）；每个键最多只能映射到一个值。
     *   (2) Map接口替换了Dictionary虚类。映射的顺序定义为映射集合视图上的迭代器返回其元素的顺序。
     *   (3) 尝试查询是否存在不合格的键或值可能会引发异常，而该操作的完成不会导致将不合格元素插入映射中，则可能会引发异常，
     *       也可能会成功（由实现选择），此类异常在该接口的规范中标记为“可选”。
     * 2.构造方法： 所有通用的映射实现类都应该提供两个“标准”构造函数：
     *   (1) 一个是void（无参数）构造函数，它创建一个空映射；
     *   (2) 另一个是具有一个类型为map的参数的构造函数，它创建一个新的映射，其键值映射与其参数相同。
     *      此构造函数允许用户复制任何映射，从而生成所需类的等效映射。
     *      没有办法强制执行这个建议（因为接口不能包含构造函数），但是JDK中的所有通用映射实现都符合。
     * 3.实现类
     *   HashMap：不保证插入元素的顺序
     *   TreeMap：插入时可以依旧key进行排序
     * 4.异常
     *   UnsupportedOperationException：该操作不被支持时抛出此异常；
     *   NullPointerException：
     *   ClassCastException：插入的key的类型不符合当前map上定义的泛型；
     * 注意点：
     * （1）不允许Map自身作为一个key来使用；
     * （2）每个key有且只映射一个value，key唯一且可以为空；
     *
     * @param <K> 此Map维护的Key的类型
     * @param <V> 此Map维护的Value的类型
     *
     * @author  Josh Bloch
     * @see HashMap
     * @see TreeMap
     * @see Hashtable
     * @see SortedMap
     * @see Collection
     * @see Set
     * @since 1.2
     */
    public interface Map<K,V> {
        // 查询操作
        int size();         //返回键值对映射的个数。如果键值对个数超过Integer.MAX_VALUE，则返回Integer.MAX_VALUE。
        boolean isEmpty();  //如果此映射不包含任何键值映射，则返回true；否则返回false。
    
        /**
         * @param  key 需要测试的键
         * @return 如果映射包含key，则返回true；否则返回false。更标准的判断条件是：(key==null ? k==null : key.equals(k))
         * @throws ClassCastException 如果key的类型不符合map的类型
         * @throws NullPointerException 如果指定的键为null并且此映射不允许空键
         */
        boolean containsKey(Object key);
    
        /**
         * @param  value 需要测试的值
         * @return 如果映射包含一个或多个value，则返回true；否则返回false。更标准的判断条件是：(value==null ? v==null : value.equals(v))
         * @throws ClassCastException 如果key的类型不符合map的类型
         *         NullPointerException 如果指定的键为null并且此映射不允许空键
         */
        boolean containsValue(Object value);
    
        /**
         * @param  key 映射的key
         * @return 返回映射中key对应的value值。如果value不存在则返回空。另外，如果key对应的value为空时，也会返回空。
         * @throws ClassCastException 如果key的类型不符合map的类型
         * @throws NullPointerException 如果指定的键为null并且此映射不允许空键
         */
        V get(Object key);
    
        // 修改操作
    
        /**
         * 存放一对key-value映射，如果key已存在(当且仅当map.containsKey(key)==true)，则覆盖旧的value
         * @param key   映射的key
         * @param value 映射的value
         * @return 如果该key已在map中存在，则返回以前与此key关联的值，否则返回null。如果以前存储的value是空，也可能会返回空
         * @throws UnsupportedOperationException 如果map不支持put操作
         * @throws ClassCastException 如果key或value的类型不符合map的类型
         * @throws NullPointerException 如果指定的键或值为null并且此映射不允许空键和空值
         * @throws IllegalArgumentException 如果指定键或值的某些属性不允许它存储在此映射中
         */
        V put(K key, V value);
    
        /**
         * 根据key移除map中的此key的映射
         * @param key 映射的key
         * @return 返回以前与此key关联的value，如果map中不存在此key或者此key以前对应的value是空，则返回空
         * @throws UnsupportedOperationException 如果此映射不支持 remove 操作
         * @throws ClassCastException 如果该键对于此映射是不合适的类型（可选）
         * @throws NullPointerException 如果指定键为 null 并且此映射不允许 null 键（可选）
         */
        V remove(Object key);
    
    
        // 批量数据操作
        /**
         * 从指定映射中将所有映射关系复制到此映射中（可选操作）。
         * 对于指定映射中的每个键k到值v的映射关系，此调用等效于对此映射调用一次put(k, v)。
         * 如果正在进行此操作的同时修改了指定的映射，则此操作的行为是不确定的。
         * @param m 要存储在此映射中的映射关系
         * @throws UnsupportedOperationException 如果此映射不支持 putAll 操作
         * @throws ClassCastException 如果指定映射中的键或值的类不允许将其存储在此映射中
         * @throws NullPointerException 如果指定映射为null，或者此映射不允许null键或值，并且指定的映射包含null键或值
         * @throws IllegalArgumentException 如果指定映射中的键或值的某些属性不允许将其存储在此映射中
         */
        void putAll(Map<? extends K, ? extends V> m);
    
        void clear();   // 移除map中所有的键值对映射，这个map的大小将会变成0；@throws UnsupportedOperationException：如果此映射不支持清除操作
    
    
        // 视图（查询操作）
        /**
         * 返回此映射中包含的键的Set视图。
         * 该set受映射支持，所以对映射的更改可在此 set 中反映出来，反之亦然。
         * 如果对该set进行迭代的同时修改了映射（通过迭代器自己的 remove 操作除外），则迭代结果是不确定的。
         * set支持元素移除，通过 Iterator.remove、 Set.remove、 removeAll、 retainAll 和 clear 操作可从映射中移除相应的映射关系。
         * 它不支持 add 或 addAll 操作。
         * @return 此映射中包含的所有键的set视图
         */
        Set<K> keySet();
    
        /**
         * 返回此映射中包含的值的 Collection 视图。
         * 该 collection 受映射支持，所以对映射的更改可在此collection 中反映出来，反之亦然。
         * 如果对该 collection 进行迭代的同时修改了映射（通过迭代器自己的 remove 操作除外），则迭代结果是不确定的。collection 支持元素移除，通过 Iterator.remove、 Collection.remove、 removeAll、 retainAll 和 clear 操作可从映射中移除相应的映射关系。它不支持 add 或 addAll 操作。
         * @return 此映射中包含的值的 collection 视图
         */
        Collection<V> values();
    
        /**
         * 返回此映射中包含的映射关系的 Set 视图。
         * 该 set 受映射支持，所以对映射的更改可在此 set 中反映出来，反之亦然。
         * 如果对该 set 进行迭代的同时修改了映射（通过迭代器自己的 remove 操作，或者通过对迭代器返回的映射项执行 setValue 操作除外），则迭代结果是不确定的。
         * set 支持元素移除，通过 Iterator.remove、 Set.remove、 removeAll、 retainAll 和 clear 操作可从映射中移除相应的映射关系。
         * 它不支持 add 或 addAll 操作。
         * @return 此映射中包含的映射关系的 set 视图
         */
        Set<Map.Entry<K, V>> entrySet();
    
        /**
         * 映射项（键-值对）。
         * Map.entrySet 方法返回映射的 collection 视图，其中的元素属于此类。
         * 获得映射项引用的唯一 方法是通过此 collection 视图的迭代器来实现。
         * 这些 Map.Entry 对象仅 在迭代期间有效；
         * 更确切地讲，如果在迭代器返回项之后修改了底层映射，则某些映射项的行为是不确定的，除了通过 setValue 在映射项上执行操作之外。
         * @see Map#entrySet()
         * @since 1.2
         */
        interface Entry<K,V> {
            /**
             * 返回与此项对应的键。
             * @return 与此项对应的键
             * @throws IllegalStateException 如果已经从底层映射中移除了该项，则实现可能（但不要求）抛出此异常。
             */
            K getKey();
    
            /**
             * 返回与此项对应的值。如果已经从底层映射中移除了映射关系（通过迭代器的 remove 操作），则此调用的结果是不确定的。
             * @return 与此项对应的值
             * @throws IllegalStateException 如果已经从底层映射中移除了该项，则实现可能，但不要求，抛出此异常。
             */
            V getValue();
    
            /**
             * 用指定的值替换与此项对应的值（可选操作）写入该映射。
             * 如果已经从映射中移除了映射关系（通过迭代器的 remove 操作），则此调用的行为是不确定的。
             * @param value 要存储在此项中的新值
             * @return 与此项对应的旧值
             * @throws UnsupportedOperationException 如果底层映射不支持 put 操作
             * @throws ClassCastException 如果指定值的类不允许将该值存储在底层映射中
             * @throws NullPointerException 如果底层映射不允许 null 值，并且指定的值为 null
             * @throws IllegalArgumentException 如果此值的某些方面不允许将其存储在底层映射中
             * @throws IllegalStateException 如果已经从底层映射中移除了该项，则实现可能，但不要求，抛出此异常.
             */
            V setValue(V value);
    
            /**
             * 比较指定对象与此项的相等性。如果给定对象也是一个映射项，并且两个项表示相同的映射关系，则返回 true。
             * 更确切地讲，如果满足以下条件，则两个项 e1 和 e2 才表示相同的映射关系
             *     (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 接口实现间可正确地工作。
             * @param o  要与此映射项进行相等性比较的对象
             * @return 如果指定的对象等于此映射项，则返回 true
             */
            boolean equals(Object o);
    
            /**
             * 返回此映射项的哈希码值。映射项 e 的哈希码定义如下：
             *     (e.getKey()==null   ? 0 : e.getKey().hashCode()) ^
             *      (e.getValue()==null ? 0 : e.getValue().hashCode())
             * 这确保 e1.equals(e2) 意味着对于任意两个项 e1 和 e2 而言， e1.hashCode()==e2.hashCode()，这正是 Object.hashCode 的常规协定所要求的。
             * @return 映射项的哈希码值
             * @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>The returned comparator is serializable and throws {@link
             * NullPointerException} when comparing an entry with a null key.
             *
             * @param  <K> the {@link Comparable} type of then map keys
             * @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() {
                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>The returned comparator is serializable and throws {@link
             * NullPointerException} when comparing an entry with null values.
             *
             * @param <K> the type of the map keys
             * @param <V> the {@link Comparable} type of the map values
             * @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>The returned comparator is serializable if the specified comparator
             * is also serializable.
             *
             * @param  <K> the type of the map keys
             * @param  <V> the type of the map values
             * @param  cmp the key {@link Comparator}
             * @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) {
                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>The returned comparator is serializable if the specified comparator
             * is also serializable.
             *
             * @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());
            }
        }
    
        // 比较和哈希
        /**
         * 比较指定的对象与此映射是否相等。
         * 如果给定的对象也是一个映射，并且这两个映射表示相同的映射关系，则返回 true。
         * 更确切地讲，如果 m1.entrySet().equals(m2.entrySet())，则两个映射 m1 和 m2 表示相同的映射关系。
         * 这可以确保 equals 方法在不同的 Map 接口实现间运行正常。
         * @param o 要与此映射进行相等性比较的对象
         * @return 如果指定的对象等于此映射，则返回 true
         */
        boolean equals(Object o);
    
        /**
         * 返回此映射的哈希码值。
         * 映射的哈希码定义为此映射 entrySet() 视图中每个项的哈希码之和。
         * 这确保 m1.equals(m2) 对于任意两个映射 m1 和 m2 而言，都意味着 m1.hashCode()==m2.hashCode()，正如 Object.hashCode() 常规协定的要求。
         * @return 返回map的hashCode值
         * @see Map.Entry#hashCode()
         * @see Object#equals(Object)
         * @see #equals(Object)
         */
        int hashCode();
    
        // 默认方法，其具体用法可以参考这篇博客：https://geek-docs.com/java/java-examples/the-default-method-of-java-map-interface.html
        // 1.8新特性：如果key存在则返回value，否则返回传递的defaultValue
        default V getOrDefault(Object key, V defaultValue) {
            V v;
            return (((v = get(key)) != null) || containsKey(key))
                    ? v
                    : defaultValue;
        }
    
        // 1.8新特性：对 Map 进行迭代，将所有键和值传递给 Consumer
        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);
            }
        }
    
        // 1.8新特性：将 Map 中每个条目的值替换为对当前条目调用给定函数后的结果
        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);
                }
            }
        }
    
        // 1.8新特性：如果value为空，则存放此映射；否则不存放
        default V putIfAbsent(K key, V value) {
            V v = get(key);
            if (v == null) {
                v = put(key, value);
            }
    
            return v;
        }
    
        // 1.8新特性：如果此映射存在（key-value和映射中的相同）则移除此映射
        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;
        }
    
        // 1.8新特性：如果此映射存在（key-value和映射中的相同）则使用新value值替换此映射的旧的value
        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;
        }
    
        // 1.8新特性：如果key存在或者(value存在且不为空)，则替换此映射value
        default V replace(K key, V value) {
            V curValue;
            if (((curValue = get(key)) != null) || containsKey(key)) {
                curValue = put(key, value);
            }
            return curValue;
        }
    
        // 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;
        }
    
        // 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;
            }
        }
    
        // 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;
            }
        }
    
        // 1.8新特性：如果键在 Map 中不存在，返回提供的值，否则计算新的值
        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;
        }
    }