compact1, compact2, compact3

java.util

Interface Collection<E>

参数类型

E - 此集合中元素的类型

All Superinterfaces:

Iterable <E>

All Known Subinterfaces:

BeanContext ， BeanContextServices ， BlockingDeque <E>， BlockingQueue <E>， Deque <E>， List <E>， NavigableSet <E>， Queue <E>， Set <E>， SortedSet <E>， TransferQueue <E>

所有已知实现类：

AbstractCollection ， AbstractList ， AbstractQueue ， AbstractSequentialList ， AbstractSet ， ArrayBlockingQueue ， ArrayDeque ， ArrayList ， AttributeList ， BeanContextServicesSupport ， BeanContextSupport ， ConcurrentHashMap.KeySetView ， ConcurrentLinkedDeque ， ConcurrentLinkedQueue ， ConcurrentSkipListSet ， CopyOnWriteArrayList ， CopyOnWriteArraySet ， DelayQueue ， EnumSet ， HashSet ， JobStateReasons ， LinkedBlockingDeque ， LinkedBlockingQueue ， LinkedHashSet ， LinkedList ， LinkedTransferQueue ， PriorityBlockingQueue ， PriorityQueue ， RoleList ， RoleUnresolvedList ， Stack ， SynchronousQueue ， TreeSet ， Vector

public interface Collection<E>
extends Iterable<E>

集合层次结构中的根界面 。 集合表示一组被称为其元素的对象。 一些集合允许重复元素，而其他集合不允许。 有些被命令和其他无序。 JDK不提供此接口的任何直接实现：它提供了更具体的子接口的实现，如Set和List 。 该界面通常用于传递集合，并在需要最大的通用性的情况下对其进行操作。

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

所有通用的Collection实现类（通常通过其子接口间接实现88446144404803）应提供两个“标准”构造函数：一个void（无参数）构造函数，它创建一个空集合，以及一个构造函数， Collection ，它创建一个与其参数相同的元素的新集合。 实际上，后一个构造函数允许用户复制任何集合，生成所需实现类型的等效集合。 没有办法强制执行此约定（因为接口不能包含构造函数），而是所有Java平台库中的通用Collection实现。

包含在该界面中的“破坏性”的方法，即，修改其经营的收集方法，被指定抛出UnsupportedOperationException如果此collection不支持该操作。 如果是这样的话，可能会，但不要求这些方法，抛出一个UnsupportedOperationException如果调用会对收集没有影响。 例如，如果要添加的集合为空，则可以在不可修改的集合上调用addAll(Collection)方法，但不是必须抛出该异常。

Some collection implementations have restrictions on the elements that they may contain.例如，一些实现禁止空元素，有些对它们的元素的类型有限制。 尝试添加不合格元素会引发未经检查的异常，通常为NullPointerException或ClassCastException 。 尝试查询不合格元素的存在可能会引发异常，或者可能只是返回false; 一些实现将展现出前者的行为，一些实现将展现出后者。 更一般来说，尝试对不符合条件的元素进行操作，其完成不会导致将不合格元素插入到集合中可能会导致异常，或者可能会成功执行该选项。 此异常在此接口的规范中标记为“可选”。

每个集合决定自己的同步策略。 在没有实现的更强保证的情况下，未定义的行为可能是由于对由另一个线程进行突变的集合的任何方法的调用而导致的; 这包括直接调用，将集合传递给可能执行调用的方法，并使用现有的迭代器来检查集合。

在集合框架接口的许多方法在来定义equals方法。 例如，对于在本说明书contains(Object o)方法表示：“返回true当且仅当这个集合包含至少一个元素e使得(o==null ? e==null : o.equals(e))”。 该规范不应该被解释为意味着具有非空参数调用o Collection.contains会导致o.equals(e)被调用任何元素e。 实现可以自由地实现优化，从而避免equals调用，例如，首先比较两个元素的哈希码。 （ Object.hashCode()规范保证具有不等的哈希码的两个对象不能相等。）更一般地，各种Collections Framework接口的实现可以随意使用底层Object方法的指定行为，无论执行者认为合适。

执行递归遍历集合的一些集合操作可能会失败，而自引用实例的异常会导致集合直接或间接包含其自身。 这包括clone() ， equals() ， hashCode()和toString()方法。 实现可以可选地处理自引用场景，然而大多数当前实现不这样做。

此接口是成员Java Collections Framework 。

实现要求：

默认方法实现（继承或其他）不应用任何同步协议。 如果Collection实现具有特定的同步协议，那么它必须覆盖默认实现以应用该协议。

从以下版本开始：

1.2

另请参见：

Set ， List ， Map ， SortedSet ， SortedMap ， HashSet ， TreeSet ， ArrayList ， LinkedList ， Vector ， Collections ， Arrays ， AbstractCollection

方法摘要

Modifier and Type	Method and Description
boolean	add(E e) 确保此集合包含指定的元素（可选操作）。
boolean	addAll(Collection<? extends E> c) 将指定集合中的所有元素添加到此集合（可选操作）。
void	clear() 从此集合中删除所有元素（可选操作）。
boolean	contains(Object o) 如果此集合包含指定的元素，则返回 true 。
boolean	containsAll(Collection<?> c) 如果此集合包含指定 集合中的所有元素，则返回true。
boolean	equals(Object o) 将指定的对象与此集合进行比较以获得相等性。
int	hashCode() 返回此集合的哈希码值。
boolean	isEmpty() 如果此集合不包含元素，则返回 true 。
Iterator<E>	iterator() 返回此集合中的元素的迭代器。
default Stream<E>	parallelStream() 返回可能并行的 Stream与此集合作为其来源。
boolean	remove(Object o) 从该集合中删除指定元素的单个实例（如果存在）（可选操作）。
boolean	removeAll(Collection<?> c) 删除指定集合中包含的所有此集合的元素（可选操作）。
default boolean	removeIf(Predicate<? super E> filter) 删除满足给定谓词的此集合的所有元素。
boolean	retainAll(Collection<?> c) 仅保留此集合中包含在指定集合中的元素（可选操作）。
int	size() 返回此集合中的元素数。
default Spliterator<E>	spliterator() 创建一个Spliterator在这个集合中的元素。
default Stream<E>	stream() 返回以此集合作为源的顺序 Stream 。
Object[]	toArray() 返回一个包含此集合中所有元素的数组。
<T> T[]	toArray(T[] a) 返回包含此集合中所有元素的数组; 返回的数组的运行时类型是指定数组的运行时类型。

Methods inherited from interface java.lang.Iterable

forEach

方法详细信息

size

int size()

返回此集合中的元素数。 如果此收藏包含超过Integer.MAX_VALUE个元素，则返回Integer.MAX_VALUE 。

结果

此集合中的元素数

isEmpty

boolean isEmpty()

如果此集合不包含元素，则返回 true 。

结果

true如果此集合不包含元素

contains

boolean contains(Object o)

如果此集合包含指定的元素，则返回true 。 更正式地，返回true如果且仅当该集合至少包含一个元素e使得(o==null ? e==null : o.equals(e)) 。

参数

o - 要在此集合中存在的元素要进行测试

结果

true如果此集合包含指定的元素

异常

ClassCastException - 如果指定元素的类型与此集合不兼容（ optional ）

NullPointerException - 如果指定的元素为空，并且此集合不允许空元素（ optional ）

iterator

Iterator<E> iterator()

返回此集合中的元素的迭代器。 没有关于元素返回顺序的保证（除非这个集合是提供保证的某个类的实例）。

Specified by:

iterator在接口 Iterable<E>

结果

一个 Iterator在这个集合中的元素

toArray

Object[] toArray()

返回一个包含此集合中所有元素的数组。 如果此集合对其迭代器返回的元素的顺序做出任何保证，则此方法必须以相同的顺序返回元素。

返回的数组将是“安全的”，因为该集合不保留对它的引用。 （换句话说，这个方法必须分配一个新的数组，即使这个集合是由数组支持的）。 因此，调用者可以自由地修改返回的数组。

此方法充当基于阵列和基于集合的API之间的桥梁。

结果

一个包含此集合中所有元素的数组

toArray

<T> T[] toArray(T[] a)

返回包含此集合中所有元素的数组; 返回的数组的运行时类型是指定数组的运行时类型。 如果集合适合指定的数组，则返回其中。 否则，将为指定数组的运行时类型和此集合的大小分配一个新数组。

如果此集合适合指定的数组，并具有剩余空间（即，该数组具有比此集合更多的元素），则紧跟在集合结束后的数组中的元素将设置为null 。 （ 仅当调用者知道此集合不包含任何null元素时，这才有助于确定此集合的长度。）

如果此集合对其迭代器返回的元素的顺序做出任何保证，则此方法必须以相同的顺序返回元素。

像toArray()方法一样，此方法充当基于数组和基于集合的API之间的桥梁。 此外，该方法允许精确地控制输出阵列的运行时类型，并且在某些情况下可以用于节省分配成本。

假设x是一个已知只包含字符串的集合。 以下代码可用于将集合转储到新分配的数组中： String ：

  String[] y = x.toArray(new String[0]); 

请注意， toArray(new Object[0])的功能与toArray()相同 。

参数类型

T - 包含集合的数组的运行时类型

参数

a - 要存储此集合的元素的数组，如果它足够大; 否则，为此目的分配相同运行时类型的新数组。

结果

一个包含此集合中所有元素的数组

异常

ArrayStoreException - 如果指定数组的运行时类型不是此集合中每个元素的运行时类型的超类型

NullPointerException - 如果指定的数组为空

add

boolean add(E e)

确保此集合包含指定的元素（可选操作）。 如果此集合由于调用而更改，则返回true 。 （如果此集合不允许重复，并且已包含指定的元素，则返回false。 ）

支持此操作的集合可能会限制可能添加到此集合的元素。 特别是一些集合拒绝添加null种元素，和其他人将强加可添加元素的类型限制。 收集类应在其文档中明确说明可能添加哪些元素的限制。

如果一个集合拒绝添加一个特定的元素，除了它已经包含该元素之外，它必须抛出异常（而不是返回false ）。 这保留了一个集合在此调用返回后始终包含指定元素的不变量。

参数

e - 要确保在此集合中的存在的元素

结果

true如果此集合由于调用而更改

异常

UnsupportedOperationException - 如果此 集合不支持add操作

ClassCastException - 如果指定元素的类阻止将其添加到此集合

NullPointerException - 如果指定的元素为空，并且该集合不允许空元素

IllegalArgumentException - 如果元素的某些属性阻止其添加到此集合

IllegalStateException - 如果由于插入限制，此时无法添加该元素

remove

boolean remove(Object o)

从该集合中删除指定元素的单个实例（如果存在）（可选操作）。 更正式地，删除元素e ，使得(o==null ? e==null : o.equals(e)) ，如果该集合包含一个或多个这样的元素。 如果此集合包含指定的元素（或等效地，如果此集合由于调用而更改），则返回true 。

参数

o - 要从此集合中删除的元素（如果存在）

结果

true如果一个元素因此调用而被删除

异常

ClassCastException - 如果指定元素的类型与此集合不兼容（ optional ）

NullPointerException - 如果指定的元素为空，并且此集合不允许空元素（ optional ）

UnsupportedOperationException - 如果此 集合不支持remove操作

containsAll

boolean containsAll(Collection<?> c)

如果此集合包含指定 集合中的所有元素，则返回true。

参数

c - 要在此集合中检查遏制的集合

结果

true如果此集合包含指定集合中的所有元素

异常

ClassCastException - 如果指定集合中的一个或多个元素的类型与此集合不兼容（ optional ）

NullPointerException - 如果指定的集合包含一个或多个空元素，并且此集合不允许空元素（ optional ），或者指定的集合为空。

另请参见：

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

将指定集合中的所有元素添加到此集合（可选操作）。 如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。 （这意味着如果指定的集合是此集合，此调用的行为是未定义的，并且此集合是非空的。）

参数

c - 包含要添加到此集合的元素的集合

结果

true如果此收集因呼叫而更改

异常

UnsupportedOperationException - 如果此 集合不支持addAll操作

ClassCastException - 如果指定集合的元素的类阻止将其添加到此集合

NullPointerException - 如果指定的集合包含一个空元素，并且此集合不允许空元素，或者如果指定的集合为空

IllegalArgumentException - 如果指定集合的元素的某些属性阻止其添加到此集合

IllegalStateException - 如果不是所有的元素可以在此时由于插入限制添加

另请参见：

add(Object)

removeAll

boolean removeAll(Collection<?> c)

删除指定集合中包含的所有此集合的元素（可选操作）。 此调用返回后，此集合将不包含与指定集合相同的元素。

参数

c - 包含要从此集合中删除的元素的集合

结果

true如果此集合由于调用而更改

异常

UnsupportedOperationException - 如果此 集合不支持 removeAll方法

ClassCastException - 如果此集合中的一个或多个元素的类型与指定的集合不兼容（ optional ）

NullPointerException - 如果此集合包含一个或多个空元素，并且指定的集合不支持空元素（ optional ），或者如果指定的集合为空

另请参见：

remove(Object) ， contains(Object)

removeIf

default boolean removeIf(Predicate<? super E> filter)

删除满足给定谓词的此集合的所有元素。 在迭代或谓词中抛出的错误或运行时异常被转发给调用者。

实现要求：

默认实现使用其iterator()遍历集合的所有元素。 使用Iterator.remove()删除每个匹配元素。 如果集合的迭代器不支持删除，那么UnsupportedOperationException将被抛出第一个匹配元素。

参数

filter - 对要删除的元素返回 true

结果

true如果有任何元素被删除

异常

NullPointerException - 如果指定的过滤器为空

UnsupportedOperationException - 如果元素无法从此集合中删除。 如果不能删除匹配的元素，或者一般来说，不支持删除，则实现可能会抛出此异常。

从以下版本开始：

1.8

retainAll

boolean retainAll(Collection<?> c)

仅保留此集合中包含在指定集合中的元素（可选操作）。 换句话说，从该集合中删除所有不包含在指定集合中的元素。

参数

c - 包含要保留在此集合中的元素的集合

结果

true如果此收集因呼叫而更改

异常

UnsupportedOperationException - 如果此 集合不支持retainAll操作

ClassCastException - 如果此集合中的一个或多个元素的类型与指定的集合不兼容（ optional ）

NullPointerException - 如果此集合包含一个或多个空元素，并且指定的集合不允许空元素（ optional ），或者如果指定的集合为空

另请参见：

remove(Object) ， contains(Object)

clear

void clear()

从此集合中删除所有元素（可选操作）。 此方法返回后，集合将为空。

异常

UnsupportedOperationException - 如果此 集合不支持clear操作

equals

boolean equals(Object o)

将指定的对象与此集合进行比较以获得相等性。

虽然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，当该集合与任何列表或集合进行比较时。 （通过相同的逻辑，不可能编写一个正确实现Set和List接口的类。）

重写：

equals在类别 Object

参数

o - 要与此集合相等的对象进行比较

结果

true如果指定的对象等于此集合

另请参见：

Object.equals(Object) ， Set.equals(Object) ， List.equals(Object)

hashCode

int hashCode()

返回此集合的哈希码值。 虽然Collection接口不会增加规定为Object.hashCode方法的常规协定，程序员应该注意的是，它覆盖Object.equals方法也必须重写Object.hashCode方法，以满足为Object.hashCode方法一般合同中的任何类。 特别是c1.equals(c2)意味着c1.hashCode()==c2.hashCode() 。

重写：

hashCode在类别 Object

结果

该集合的哈希码值

另请参见：

Object.hashCode() ， Object.equals(Object)

spliterator

default Spliterator<E> spliterator()

创建一个Spliterator在这个集合中的元素。 实现应该记录分配器报告的特征值。 如果拼接器报告Spliterator.SIZED并且此集合不包含元素，则不需要报告此类特征值。

应该通过可以返回更高效的拼接器的子类覆盖默认实现。 为了保持stream()和parallelStream() }方法的预期懒惰行为，分频器应具有IMMUTABLE或CONCURRENT ，或者为late-binding 。 如果这些都不实际，那么首要的类应该是描述绑定者所记录的绑定和结构性干扰的策略，并且应该覆盖stream()和parallelStream()方法以使用Supplier的Supplier创建流，如下所示：

   Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)  

这些要求确保由stream()和parallelStream()方法生成的流将反映终端流操作启动时集合的内容。

Specified by:

spliterator在界面 Iterable<E>

实现要求：

默认实现从集合的Iterator创建一个late-binding拼接Iterator 。 分割器继承集合的迭代器的故障快速属性。

创建的Spliterator报告Spliterator.SIZED 。

Implementation Note:

创建的Spliterator另外报告Spliterator.SUBSIZED 。

如果spliterator涵盖任何元素，然后附加特性值的报表，超出的SIZED和SUBSIZED ，不帮助客户控制，专业或简化计算。 但是，这样做可以使空集合能够共享使用一个不变的和空的Spliterator实例（参见Spliterators.emptySpliterator() ），并且允许客户端确定这样一个分割器是否不覆盖任何元素。

结果

一个 Spliterator在这个集合中的元素

从以下版本开始：

1.8

stream

default Stream<E> stream()

返回一个顺序Stream与此集合作为其来源。

当此方法应该重写spliterator()方法不能返回spliterator是IMMUTABLE ， CONCURRENT ，或后期绑定 。 （详见spliterator() ）

实现要求：

默认的实现创建顺序 Stream从收集的 Spliterator 。

结果

连续 Stream在这个集合中的元素

从以下版本开始：

1.8

parallelStream

default Stream<E> parallelStream()

返回可能并行的Stream与此集合作为其来源。 该方法允许返回顺序流。

当此方法应该重写spliterator()方法不能返回spliterator是IMMUTABLE ， CONCURRENT ，或后期绑定 。 （详见spliterator() ）

实现要求：

默认的实现创建了一个平行 Stream从收集的 Spliterator 。

结果

一个可能平行 Stream移到该集合中的元素

从以下版本开始：

1.8