Java Collection源码总结 Collection源码注释翻译和解析中英文对照版

版本
JDK8(JDK1.8)

Collection接口源码重点
1.集合层次结构中的根接口，集合表示一组对象，称为其元素，某些集合允许重复元素，而其他集合则不允许，有些是有序的，有些是无序的。

2.该接口类定义了各种规范包括方法规范和抛出异常的规范，还有比较和哈希操作，以及分离器spliterator和流stream，方法主要有三类查询、修改、批量，如contains(Object o)、add(E e)、addAll(Collection<? extends E> c)分别对应查询、修改、批量

3.接口定义的部分集合操作方法

方法名	作用
boolean isEmpty()	判断集合是否为空
Object[] toArray()	按照迭代器迭代顺序返回元素数组
boolean add(E e)	添加元素
boolean addAll(Collection<? extends E> c)	将c中所有元素添加进集合
boolean remove(Object o)	移除元素
boolean removeAll(Collection<?> c)	从集合中移除c中的元素
boolean contains(Object o)	判断o是否在集合中
boolean containsAll(Collection<?> c)	c中所有元素都在集合中返回true否则false
boolean retainAll(Collection<?> c)	删除集合中元素，只保留c中也有的元素
void clear()	删除集合中所有元素

remove(.)方法还有一个变种 boolean removeIf(Predicate<? super E> filter)，
根据Predicate定义的规则来删除集合的元素，可以看我这篇文章 Predicate

4.接口定义的部分其他方法

方法名	作用
boolean equals(Object o)	Object.equals实现是引用比较，可以重写为值比较
int hashCode()	应满足c1.equals(c2)表示c1.hashCode()==c2.hashCode()
Iterator iterator()	返回迭代器
Stream stream()	返回流
Stream parallelStream()	返回并行流
Spliterator spliterator()	返回分离器

5.接口定义的抛出异常

异常名	意义
UnsupportedOperationException	此集合不支持添加操作
ClassCastException	传入元素的类与该集合不兼容
NullPointerException	传入的元素为null，并且此集合不允许null元素
IllegalArgumentException	元素的某些属性阻止将其添加到此集合
IllegalStateException	由于插入限制，此时无法添加元素（容器已满）

Collection接口源码

package java.util;

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

/**
 * The root interface in the <i>collection hierarchy</i>.  A collection
 * represents a group of objects, known as its <i>elements</i>.  Some
 * collections allow duplicate elements and others do not.  Some are ordered
 * and others unordered.  The JDK does not provide any <i>direct</i>
 * implementations of this interface: it provides implementations of more
 * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>.  This interface
 * is typically used to pass collections around and manipulate them where
 * maximum generality is desired.
 * 集合层次结构中的根接口。集合表示一组对象，称为其元素。
 * 某些集合允许重复元素，而其他集合则不允许。
 * 有些是有序的，有些是无序的。JDK不提供此接口的任何直接实现：
 * 它提供更具体的子接口（如Set和List）的实现。
 * 此接口通常用于传递集合，并在需要最大通用性的地方对其进行操作。
 * 
 *
 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
 * duplicate elements) should implement this interface directly.
 * 包或多集（可能包含重复元素的无序集合）应直接实现此接口
 *
 * 
 * 
 * <p>All general-purpose <tt>Collection</tt> implementation classes (which
 * typically implement <tt>Collection</tt> indirectly through one of its
 * subinterfaces) should provide two "standard" constructors: a void (no
 * arguments) constructor, which creates an empty collection, and a
 * constructor with a single argument of type <tt>Collection</tt>, which
 * creates a new collection with the same elements as its argument.  In
 * effect, the latter constructor allows the user to copy any collection,
 * producing an equivalent collection of the desired implementation type.
 * There is no way to enforce this convention (as interfaces cannot contain
 * constructors) but all of the general-purpose <tt>Collection</tt>
 * implementations in the Java platform libraries comply.
 * 所有通用集合实现类（通常通过其子接口之一间接实现集合）都应提供两个“标准”构造函数：
 * 一个创建空集合的void（无参数）构造函数和一个具有Collection类型的单个参数的构造函数，
 * 它创建一个新集合，该集合的元素与其参数相同。
 * 实际上，后一个构造函数允许用户复制任何集合，从而生成所需实现类型的等效集合。
 * 无法强制执行此约定（因为接口不能包含构造函数），但Java平台库中的所有通用集合实现都符合此约定。
 * 
 * 
 * 
 * 
 *
 * <p>The "destructive" methods contained in this interface, that is, the
 * methods that modify the collection on which they operate, are specified to
 * throw <tt>UnsupportedOperationException</tt> if this collection does not
 * support the operation.  If this is the case, these methods may, but are not
 * required to, throw an <tt>UnsupportedOperationException</tt> if the
 * invocation would have no effect on the collection.  For example, invoking
 * the {@link #addAll(Collection)} method on an unmodifiable collection may,
 * but is not required to, throw the exception if the collection to be added
 * is empty.
 * 
 * 此接口中包含的“破坏性”方法，即修改其操作的集合的方法，
 * 指定在该集合不支持该操作时引发UnsupportedOperationException。
 * 如果是这种情况，如果调用对集合没有影响，则这些方法可能（但不是必需）
 * 抛出UnsupportedOperationException。例如，如果要添加的集合为空，
 * 则对不可修改的集合调用addAll(Collection)方法可能（但不是必需）引发异常。
 * 
 * 
 * 
 * 
 * <p><a name="optional-restrictions">
 * Some collection implementations have restrictions on the elements that
 * they may contain.</a>  For example, some implementations prohibit null elements,
 * and some have restrictions on the types of their elements.  Attempting to
 * add an ineligible element throws an unchecked exception, typically
 * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>.  Attempting
 * to query the presence of an ineligible element may throw an exception,
 * or it may simply return false; some implementations will exhibit the former
 * behavior and some will exhibit the latter.  More generally, attempting an
 * operation on an ineligible element whose completion would not result in
 * the insertion of an ineligible element into the collection may throw an
 * exception or it may succeed, at the option of the implementation.
 * Such exceptions are marked as "optional" in the specification for this
 * interface.
 * 某些集合实现对它们可能包含的元素有限制。
 * 例如，有些实现禁止空元素，有些实现对其元素的类型有限制。
 * 尝试添加不合格的元素会引发未经检查的异常，通常为NullPointerException或ClassCastException。
 * 试图查询不合格元素的存在可能会引发异常，或者只返回false；
 * 有些实现将展示前一种行为，有些实现将展示后一种行为。
 * 更一般地说，在不合格元素上尝试操作（其完成不会导致将不合格元素插入到集合中）可能会引发异常，
 * 或者可能会成功（由实现选择）。此类异常在该接口规范中标记为“可选”。
 * 
 * 
 * 
 * 
 * 
 * <p>It is up to each collection to determine its own synchronization
 * policy.  In the absence of a stronger guarantee by the
 * implementation, undefined behavior may result from the invocation
 * of any method on a collection that is being mutated by another
 * thread; this includes direct invocations, passing the collection to
 * a method that might perform invocations, and using an existing
 * iterator to examine the collection.
 * 由每个集合决定其自己的同步策略。在实现没有更强有力的保证的情况下，
 * 未定义的行为可能是由于调用另一个线程正在变异的集合上的任何方法而导致的；
 * 这包括直接调用、将集合传递给可能执行调用的方法以及使用现有迭代器检查集合。
 * 
 * 
 * 
 * 
 *
 * <p>Many methods in Collections Framework interfaces are defined in
 * terms of the {@link Object#equals(Object) equals} method.  For example,
 * the specification for the {@link #contains(Object) contains(Object o)}
 * method says: "returns <tt>true</tt> if and only if this collection
 * contains at least one element <tt>e</tt> such that
 * <tt>(o==null ? e==null : o.equ