Java8 Collection接口源码阅读（二）

接口中全是方法声明，故本文基本上只是对源码里的注释进行了翻译，除了对默认方法的几句解释外。

// 继承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);
    }
}