Java8 Collection接口源码阅读

jdk1.6对Collection接口的描述

    Collection 层次结构中的根接口。Collection 表示一组对象，这些对象也称为collection 的元素。一些 collection 允许有重复的元素，而另一些则不允许。一些 collection 是有序的，而另一些则是无序的。JDK 不提供此接口的任何直接实现：它提供更具体的子接口（如 Set 和 List）实现。此接口通常用来传递 collection，并在需要最大普遍性的地方操作这些 collection。

    包 (bag) 或多集合 (multiset)（可能包含重复元素的无序 collection）应该直接实现此接口。

    所有通用的 Collection 实现类（通常通过它的一个子接口间接实现Collection）应该提供两个“标准”构造方法：一个是 void（无参数）构造方法，用于创建空 collection；另一个是带有 Collection 类型单参数的构造方法，用于创建一个具有与其参数相同元素新的 collection。实际上，后者允许用户复制任何 collection，以生成所需实现类型的一个等效 collection。尽管无法强制执行此约定（因为接口不能包含构造方法），但是Java 平台库中所有通用的 Collection 实现都遵从它。

    此接口中包含的“破坏性”方法，是指可修改其所操作的 collection 的那些方法，如果此 collection 不支持该操作，则指定这些方法抛出 UnsupportedOperationException。如果是这样，那么在调用对该 collection 无效时，这些方法可能，但并不一定抛出 UnsupportedOperationException。例如，如果要添加的 collection 为空且不可修改，则对该 collection 调用addAll(Collection) 方法时，可能但并不一定抛出异常。

    一些 collection实现对它们可能包含的元素有所限制。例如，某些实现禁止 null 元素，而某些实现则对元素的类型有限制。试图添加不合格的元素将抛出一个未经检查的异常，通常是NullPointerException 或 ClassCastException。试图查询是否存在不合格的元素可能抛出一个异常，或者只是简单地返回false；某些实现将表现出前一种行为，而某些实现则表现后一种。较为常见的是，试图对某个不合格的元素执行操作且该操作的完成不会导致将不合格的元素插入 collection 中，将可能抛出一个异常，也可能操作成功，这取决于实现本身。这样的异常在此接口的规范中标记为“可选”。

    由每个collection 来确定其自身的同步策略。在没有实现的强烈保证的情况下，调用由另一进程正在更改的collection 的方法可能会出现不确定行为；这包括直接调用，将 collection 传递给可能执行调用的方法，以及使用现有迭代器检查 collection。

    CollectionsFramework 接口中的很多方法是根据 equals 方法定义的。例如，contains(Object o) 方法的规范声明：“当且仅当此 collection 包含至少一个满足 (o==null ? e==null :o.equals(e)) 的元素e 时，返回true。”不 应将此规范理解为它暗指调用具有非空参数 o 的 Collection.contains 方法会导致为任意的e 元素调用o.equals(e) 方法。可随意对各种实现执行优化，只要避免调用 equals 即可，例如，通过首先比较两个元素的哈希码。（Object.hashCode() 规范保证哈希码不相等的两个对象不会相等）。较为常见的是，各种 Collections Framework 接口的实现可随意利用底层 Object 方法的指定行为，而不管实现程序认为它是否合适。

    此接口是 JavaCollections Framework 的一个成员。

    
// 继承Iterable接口  
    public interface Collection<E> extends Iterable<E> {  
        // 查询操作  
      
        /** 
         * 返回collection中元素的数目。如果元素数目大于Integer.MAX_VALUE， 
         * 就返回Integer.MAX_VALUE 
         */  
        int size();  
      
        /** 
         * 如果collection中没有元素就返回true 
         */  
        boolean isEmpty();  
      
        /** 
         * 如果collection包含指定的元素，就返回true。 
         * 更形式化的描述是，当且仅当collection包含至少一个元素e，e满足条件： 
         * (o==null?e==null:o.equals(e)) 
         */  
        boolean contains(Object o);  
      
        /** 
         * 返回一个在这个collection的元素上的迭代器。不保证collection中元素以什么顺序返回 
         * （除非这个collection是某个提供了保证的类的实例） 
         */  
        Iterator<E> iterator();  
      
        /** 
         * 返回一个包含这个collection中所有元素的数组。 
         * 如果这个collection做出保证，元素将以什么顺序被迭代器返回， 
         * 那么这个方法必须以相同的顺序返回这些元素 
         * 
         * 返回的数组是安全的，因为这个collection并不维护对这个数组的任何引用。（换句话说， 
         * 这个方法必须分配一个新的数组，即使这个collection被一个数组支持。）所以，调用者可以 
         * 随意修改返回的数组 
         *  
         * 这个方法就像基于数组和基于collection的API的桥梁 
         * <p>This method acts as bridge between array-based and collection-based 
         * APIs. 
         */  
        Object[] toArray();  
      
        /** 
         * 返回一个包含这个collection中所有元素的数组。返回数组的运行时类型就是指定数组的类型。 
         * 如果指定的数组能容纳这个collection，就返回包含此collection元素的数组。否则， 
         * 就分配一个具有指定数组的运行时类型和这个collection的大小的新数组。 
         * 
         * 如果指定的数组不仅能容纳这个collection，并且还有剩余空间（这个数组拥有比这个 
         * collection更多的元素），数组中跟随在collection的最后一个元素后面的元素 
         * 就会被设置为null。（只有调用者知道这collection没有包含任何null元素，才能通过 
         * 这个方法获得这个collection的长度） 
         *  
         * 如果这个collection做出保证，它的元素将会以什么顺序被迭代器返回，这个方法必须 
         * 以相同的顺序返回这些元素。 
         * 
         * 
         * 就像toArray()方法，这个方法就像基于数组和基于collection的API的桥梁。此外， 
         * 这个方法提供对输出数组的运行时类型更精确的控制，而且，在某些情况下，被用来节省 
         * 分配开销。 
         * 
         *假设x是一个只包含字符串的collection。下面的代码能够用来把collection中的元素装进 
         *一个新分配的字符串数组中。 
         *     String[] y = x.toArray(new String[0]); 
         * 注意，toArray(new Object[0])和toArray()在功能上是一样的 
         */  
        <T> T[] toArray(T[] a);  
      
        // Modification Operations  
      
        /** 
         * 确保这个collection包含指定的元素（可选的操作）。如果调用这个方法使collection改变了， 
         * 就返回true。（如果这个collection不允许重复的元素，且已经包含了指定的元素，就返回 
         * false。） 
         *  
         * 支持这个操作的集合可能针对哪些元素能被添加进来设置限制。特别的，有些collection拒绝添加 
         * null元素，而另一些限制被添加进来的元素的类型。collection类应该在它们的文档中清晰地 
         * 指定什么样的元素能被添加进来。 
         *  
         * 如果一个collection拒绝添加一个元素，而且不是因为该collection已经包含这个元素，它 
         * 必须抛出异常（而不是返回false）。这保证这个函数返回后collection总是包含指定元素。 
         */  
        boolean add(E e);  
      
        /** 
         * 从这个collection中删除指定元素的单个实例，如果存在这样的一个实例的话。更形像的 
         * 说法是，删除元素e, e满足条件o==null?e==null:o.equals(e),如果这个 
         * collection包含一个或者多个这样的元素。如果这个collection包含这个元素，返回true（ 
         * 或者这样说，如果调用这个方法之后collection改变了，就返回true） 
         */  
        boolean remove(Object o);  
      
      
        // 批量操作  
      
        /** 
         * 如果这个collection包含指定collection中的所有元素就返回true。 
         * Returns <tt>true</tt> if this collection contains all of the elements 
         * in the specified collection. 
         */  
        boolean containsAll(Collection<?> c);  
      
        /** 
         * 把指定collection中的所有元素添加进这个collection（可选的操作）。如果在这个操作正在 
         * 进行的时候，指定的collection被更改了，这个操作的行为是未定义的。（这意味着，如果被指定 
         * 的collection就是这个collection，并且这个collection非空，那么这个调用的行为是 
         * 未定义的。） 
         */  
        boolean addAll(Collection<? extends E> c);  
      
        /** 
         * 删除被包含在指定collection中德所有元素（可选的操作）。在这个调用返回后，这个collection 
         * 和指定的collection没有相同的元素。 
         */  
        boolean removeAll(Collection<?> c);  
      
        /** 
         * 删除collection中所有满足给定断言的元素。在迭代或者被断言抛出的错误或者运行时异常被传递 
         * 给调用者。 
         * 
         *这个默认的实现用collection的迭代器遍历它的所有元素。所有匹配的元素用Iterator的 
         *remove（）方法删除。如果这个collection的迭代器不支持删除操作，在遇到第一个匹配的元素的 
         *时候，抛出UnsupportedOperationException 
         */  
        default boolean removeIf(Predicate<? super E> filter) {  
            // 验证filter是否null，如果为null，抛出NullPointerException  
            Objects.requireNonNull(filter);  
            boolean removed = false;  
            final Iterator<E> each = iterator();  
            while (each.hasNext()) {  
                if (filter.test(each.next())) {  
                    each.remove();  
                    // 只要有一个元素被删除，就返回true  
                    removed = true;  
                }  
            }  
            return removed;  
        }  
      
        /** 
         * 保持被包含在指定collection中的元素（可选的操作）。换句话说，从这个collection中删除 
         * 所有不被指定collection包含的元素。 
         */  
        boolean retainAll(Collection<?> c);  
      
        /** 
         * 从这个collection中删除所有的元素（可选的操作）。在这个返回后，这个collection将会 
         * 是空的。 
         */  
        void clear();  
      
      
        // 比较和哈希  
      
        /** 
         * 比较指定的对象和这个collection是否相等。 
         *  
         * 当Collection接口没有对Object.equals添加任何条款到常规约定上时，直接实现Collection 
         * 接口（换句话说，创建一个是Collection但不是Set或者List的类）的程序员必须非常小心，如果 
         * 他们选择重写Object.equals。没有必要这样做，最简单的方案是依赖Object的实现，但是实现着 
         * 可能希望实现值比较来代替默认的引用比较。（List和Set接口要求这样的值比较） 
         * 
         * 对Object.equals方法的一般约定是，相等必须是对称的。（换句话说，a.equals(b)，当且仅当 
         * b.equals(a)）。对List.equals和Set.equals的约定是，列表只能和列表相等，集合只能和集 
         * 合相等。因此，一个既没有实现List接口，也没有实现Set接口的类的equals方法必须返回false， 
         * 当这个collection和任何列表和集合比较的时候。（按照同样的逻辑，不可能写出一个类，这个类同时 
         * 正确实现Set接口和List接口） 
         */  
        boolean equals(Object o);  
      
        /** 
         * 返回这个collection的hash码。为了满足Object.hashCode的常规约定， 
         * 当Collection接口没有对Object.hashCode 
         * 添加任何约束到常规上时，程序员应该注意任何重写Object.equals方法类也必须重写 
         * Object.hashCode方法。特别的，c1.equals(c2)暗示着， 
         * c1.hashCode()==c2.hashCode() 
         */  
        int hashCode();  
      
        /** 
         * 创建一个在这个collection的元素上的Spliterator。 
         * 
         * 实现应该证明被spliterator报告的特征值。如果spliterator报告SIZED或者这个collection 
         * 没有包含任何元素。 
         * 
         * 默认实现应该被能够返回更有效的spliterator的字类重写。为了保护stream()和parallelStream() 
         * 方法的懒散行为，spliterator应该拥有IMMUTABLE或者CONCURRENT的特征，或者晚绑定。 
         * 如果没有一个是可用的，重写的类应该描述绑定和结构障碍的spliterator的策略，而且应该重写 
         * stream()和parallelStream()方法来用spliterator的Supplier来创建stream。就像 
         * Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics) 
         * 这些需求保证被stream()和parallelStream()方法stream将会反应这个collection 
         * 的内容，在终端stream操作初始化时。 
         *  
         * 默认实现从collection的迭代器中创建一个晚绑定的spliterator。这个spliterator继承 
         * collection的迭代器的fail-fast特性。 
         *  
         * 创建的Spliterator报告SIZED。 
         * 
         * 创建的Spliterator额外报告SUBSIZED。 
         * 
         * 如果一个spliterator没有覆盖任何元素，额外特征值的报告，不会帮助客户去控制，指定或者简化 
         * 计算。然后，这确实是不可变或者空spliterator实例对空collection可以公用，而且使客户去 
         * 决定这样一个spliterator是否包含元素。 
         */  
        @Override  
        default Spliterator<E> spliterator() {  
            return Spliterators.spliterator(this, 0);  
        }  
      
        /** 
         * 以这个collection作为它的源返回一个序列Stream。 
         *  
         * 当spliterator()方法不能返回一个IMMUTABLE，或者CONCURRENT，或者晚绑定的spliterator 
         * 时，这个方法应该重写。 
         * 
         * 这个默认实现从collection的Spliterator中创建一个序列Stream。 
         */  
        default Stream<E> stream() {  
            return StreamSupport.stream(spliterator(), false);  
        }  
      
        /** 
         * 以这个collection作为源返回一个可能的并行Stream。这个方法返回一个序列stream是允许的。 
         *  
         * 当spliterator()方法不能返回一个IMMUTABLE，或者CONCURRENT，或者晚绑定的spliterator 
         * 时，这个方法应该重写。 
         *  
         * 这个默认实现从collection的Spliterator中返回一个并行Stream。 
         */  
        default Stream<E> parallelStream() {  
            return StreamSupport.stream(spliterator(), true);  
        }  
    }