源码学习之Collection

以下源码摘自JDK8

package java.util;

import java.util.function.Predicate;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;

/**
 * 集合里的根接口。集合是一组元素。有些集合允许重复的值，有些集合不允许。有些集合是顺序的，
 * 有些则不是。JDK里，Collection接口没有任何直接实现，需要通过其子接口List和Set来实现。
 *
 * 所有通用Collection实现类(即从Collection的子接口实现)需提供两个标准的构造器，一个空参
 * 构造器和一个带有Collection类入参的构造器，Collection入参构造器会根据入参的元素来创建集合。
 *
 * 每个collection可以自己定义自己的同步策略。collection类的default方法不包含任何
 * synchronization策略。实现类需重写default方法来实现同步。
 *
 * @param <E> the type of elements in this collection
 *
 * @author  Josh Bloch
 * @author  Neal Gafter
 * @see     Set
 * @see     List
 * @see     Map
 * @see     SortedSet
 * @see     SortedMap
 * @see     HashSet
 * @see     TreeSet
 * @see     ArrayList
 * @see     LinkedList
 * @see     Vector
 * @see     Collections
 * @see     Arrays
 * @see     AbstractCollection
 * @since 1.2
 */

public interface Collection<E> extends Iterable<E> {
    // Query Operations 查询操作
    /**
     * 返回Collection中元素的个数，如果个数大于Integer的最大值，则返回MAX_INT
     */
    int size();

    /**
     * 为空返回true，否则返回false
     */
    boolean isEmpty();

    /**
     * 判断元素是否存在集合中，可能抛出类型转换异常或空指针异常。
     */
    boolean contains(Object o);

    /**
     * 继承于Iterable接口
     */
    Iterator<E> iterator();

    /**
     * 返回一个包含所有元素的数组。如果collection是有序的，则数组的顺序必须与之相同。
     * 该方法会创建一个新的数组，是数组与集合之间的桥梁。
     */
    Object[] toArray();

    /**
     * 支持泛型的toArray();
     */
    <T> T[] toArray(T[] a);

    // Modification Operations 修改操作

    /**
     * 将元素添加进collection，成功返回true，失败返回false。失败的原因可能是collection
     * 不允许添加重复的元素，可能是不允许添加null值。如果不是因为已经包含元素的原因添加失败，
     * 必须抛出异常。这保证了这常调用该函数后，collectin必然包含需要添加的值。
     * @throws UnsupportedOperationException 如果集合不支持add操作。
     * @throws ClassCastException 转换类型失败
     * @throws NullPointerException 集合
     * @throws IllegalArgumentException 元素不允许被添加
     * @throws IllegalStateException
     */
    boolean add(E e);

    /**
     * 删除入参元素，如果有多个则删除多个。正常运行后，collection必然不含入参元素。
     * @throws ClassCastException
     * @throws NullPointerException 如果入参为null，且集合不允许null
     * @throws UnsupportedOperationException 集合不允许remove()操作
     */
    boolean remove(Object o);


    // Bulk Operations 块操作

    /**
     * 如果包含入参中所有的元素则返回true，否则false。
     * @throws ClassCastException
     * @throws NullPointerException
     */
    boolean containsAll(Collection<?> c);

    /**
     * 添加所有元素。
     * @throws UnsupportedOperationException collection不支持此方法。
     * @throws ClassCastException
     * @throws NullPointerException
     * @throws IllegalArgumentException 入参的元素不支持被添加
     * @throws IllegalStateException
     */
    boolean addAll(Collection<? extends E> c);

    /**
     * 删除所有元素。
     * @throws UnsupportedOperationException
     * @throws ClassCastException
     * @throws NullPointerException
     */
    boolean removeAll(Collection<?> c);

    /**
     * 移除集合里所有满足条件的元素。
     * 默认实现使用其迭代器遍历所有元素，对于满足条件的的元素，使用迭代器的remove操作。如果迭代器
     * 不支持删除操作，遇到第一个满足条件的元素抛出UnsupportedOperationException异常。
     * @throws NullPointerException filter为null
     * @throws UnsupportedOperationException
     */
    default boolean removeIf(Predicate<? super E> filter) {
        Objects.requireNonNull(filter);
        boolean removed = false;
        final Iterator<E> each = iterator();
        while (each.hasNext()) {
            if (filter.test(each.next())) {
                each.remove();
                removed = true;
            }
        }
        return removed;
    }

    /**
     * 保留包含在给定collection里的元素。等同于移除所有不在入参集合里的元素。
     * @throws UnsupportedOperationException
     * @throws ClassCastException
     * @throws NullPointerException
     */
    boolean retainAll(Collection<?> c);

    /**
     * 移除所有元素，collection为empty
     * @throws UnsupportedOperationException
     */
    void clear();


    // Comparison and hashing

    boolean equals(Object o);

    int hashCode();

    /**
     * 新建Spliterator，基于collection的元素。
     * @since 1.8
     */
    @Override
    default Spliterator<E> spliterator() {
        return Spliterators.spliterator(this, 0);
    }

    /**
     * @since 1.8
     */
    default Stream<E> stream() {
        return StreamSupport.stream(spliterator(), false);
    }

    /**
     * @since 1.8
     */
    default Stream<E> parallelStream() {
        return StreamSupport.stream(spliterator(), true);
    }
}