Module java.base
Package java.util

Interface Collection<E>

类型参数:
E - 此集合中元素的类型
所有超级接口:
Iterable<E>
所有已知子接口:
BeanContext, BeanContextServices, BlockingDeque<E>, BlockingQueue<E>, Deque<E>, EventSet, List<E>, NavigableSet<E>, Queue<E>, SequencedCollection<E>, SequencedSet<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>
在集合层次结构中的根接口。集合表示一组对象，称为其元素。一些集合允许重复元素，而另一些则不允许。有些是有序的，而另一些是无序的。具有定义的遇到顺序的集合通常是SequencedCollection接口的子类型。JDK没有提供此接口的任何直接实现：它提供更具体的子接口的实现，如Set和List。此接口通常用于传递集合并在需要最大通用性时操作它们。

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

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

某些方法被指定为可选。如果集合实现不实现特定操作，则应定义相应的方法以抛出UnsupportedOperationException。这些方法在集合接口的方法规范中标记为“可选操作”。

某些集合实现对它们可以包含的元素有限制。例如，某些实现禁止空元素，并且某些对其元素类型有限制。尝试添加不合格元素会引发未经检查的异常，通常是NullPointerException或ClassCastException。尝试查询不合格元素的存在可能会引发异常，或者可能只会返回false；某些实现将表现出前一种行为，而某些将表现出后一种行为。更一般地，尝试对不合格元素执行操作，其完成不会导致将不合格元素插入集合中，可能会引发异常，也可能会成功，由实现者选择。此类异常在此接口的规范中标记为“可选”。

集合框架接口中的许多方法都是根据equals方法定义的。例如，contains(Object o)方法的规范表示：“仅当此集合包含至少一个元素e，使得(o==null ? e==null : o.equals(e))”时返回true。此规范不应被解释为调用Collection.contains与非空参数o将导致为任何元素e调用o.equals(e)。实现可以自由实现优化，避免调用equals，例如，通过首先比较两个元素的哈希码。 （Object.hashCode()规范保证具有不相等哈希码的两个对象不能相等。）更一般地，各种集合框架接口的实现可以自由利用底层Object方法的指定行为，无论实现者认为适当。

一些执行递归遍历集合的集合操作可能对直接或间接包含自身的实例失败并引发异常。这包括clone()、equals()、hashCode()和toString()方法。实现可以选择处理自引用情况，但目前大多数实现不这样做。

视图集合

大多数集合管理它们包含的元素的存储。相比之下，视图集合本身不存储元素，而是依赖于支持集合来存储实际元素。视图集合本身不处理的操作将委托给支持集合。视图集合的示例包括通过方法返回的包装集合，如Collections.checkedCollection、Collections.synchronizedCollection和Collections.unmodifiableCollection。其他视图集合的示例包括提供相同元素的不同表示形式的集合，例如由List.subList、NavigableSet.subSet、Map.entrySet或SequencedCollection.reversed提供的。对支持集合进行的任何更改都会在视图集合中可见。相应地，对视图集合进行的任何更改（如果允许更改）都会写入支持集合。尽管它们在技术上不是集合，但Iterator和ListIterator的实例也可以允许修改写入到支持集合中，并且在某些情况下，对支持集合的修改将在迭代期间对迭代器可见。

不可修改集合

此接口的某些方法被认为是“破坏性的”，被称为“变异器”方法，因为它们修改其操作的集合中包含的对象组。如果此集合实现不支持操作，则可以指定抛出UnsupportedOperationException。如果调用对集合没有影响，则应（但不是必须）抛出UnsupportedOperationException。例如，考虑一个不支持add操作的集合。如果对该集合调用addAll方法，并将空集合作为参数，会发生什么？添加零个元素没有影响，因此允许该集合什么也不做而不抛出异常。但是，建议在所有情况下无条件抛出异常，因为仅在某些情况下抛出异常可能会导致编程错误。

一个不可修改集合是一个集合，其所有变异器方法（如上所定义）被指定为抛出UnsupportedOperationException。因此，通过调用其上的任何方法，无法修改此集合。为了使集合正确不可修改，从中派生的任何视图集合也必须是不可修改的。例如，如果一个List是不可修改的，则由List.subList返回的List也是不可修改的。

不可修改集合不一定是不可变的。如果包含的元素是可变的，则整个集合显然是可变的，即使它可能是不可修改的。例如，考虑包含可变元素的两个不可修改列表。如果元素已被改变，则调用list1.equals(list2)的结果可能会因为元素已被改变而在不同调用之间不同，即使两个列表都是不可修改的。但是，如果不可修改集合包含所有不可变元素，则可以认为它是有效不可变的。

不可修改视图集合

一个不可修改视图集合是一个不可修改的集合，也是对支持集合的视图。其变异器方法抛出UnsupportedOperationException，如上所述，而读取和查询方法被委托给支持集合。其效果是为支持集合提供只读访问。这对于组件向用户提供对内部集合的只读访问，同时防止他们意外修改这些集合是有用的。不可修改视图集合的示例包括由Collections.unmodifiableCollection、Collections.unmodifiableList等方法返回的集合。

请注意，对支持集合的更改仍然可能是可能的，如果发生这种情况，它们将通过不可修改视图可见。因此，不可修改视图集合不一定是不可变的。但是，如果不可修改视图的支持集合是有效不可变的，或者如果对支持集合的唯一引用是通过不可修改视图，则可以认为该视图是有效不可变的。

集合的可序列化性

集合的可序列化性是可选的。因此，没有任何集合接口声明实现Serializable接口。但是，可序列化被认为通常是有用的，因此大多数集合实现都是可序列化的。

那些是公共类的集合实现（如ArrayList或HashMap）如果实际上是可序列化的，则声明实现Serializable接口。一些集合实现不是公共类，例如不可修改集合。在这种情况下，这些集合的可序列化性在创建它们的方法的规范中描述，或者在其他适当的地方描述。在未指定集合的可序列化性的情况下，不能保证这些集合的可序列化性。特别是，许多视图集合不可序列化，即使原始集合是可序列化的。

实现Serializable接口的集合实现不能保证是可序列化的。原因是一般来说，集合包含其他类型的元素，无法静态确定某些元素类型的实例是否实际上是可序列化的。例如，考虑一个可序列化的Collection<E>，其中E没有实现Serializable接口。如果集合只包含某个E的可序列化子类型的元素，或者集合为空，则集合可能是可序列化的。因此，集合被称为有条件可序列化的，因为集合作为整体的可序列化性取决于集合本身是否可序列化以及所有包含的元素是否也可序列化。

另一个情况发生在SortedSet和SortedMap的实例上。这些集合可以使用Comparator创建，该Comparator对集合元素或映射键施加排序。只有提供的Comparator也是可序列化的情况下，这样的集合才是可序列化的。

此接口是Java集合框架的成员之一。
实现要求:
默认方法实现（继承的或其他方式）不适用任何同步协议。如果一个Collection实现有特定的同步协议，则必须覆盖默认实现以应用该协议。
自版本:
1.2
参见:

  • Method Summary

    Modifier and Type
    Method
    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()
    返回一个包含此集合中所有元素的数组。
    default <T> T[]
    toArray(IntFunction<T[]> generator)
    返回一个包含此集合中所有元素的数组，使用提供的generator函数来分配返回的数组。
    <T> T[]
    toArray(T[] a)
    返回一个包含此集合中所有元素的数组；返回的数组的运行时类型是指定数组的类型。

    Methods declared in interface java.lang.Iterable

    forEach

  • Method Details

    • size

      int size()
      返回此集合中的元素数量。如果此集合包含的元素超过Integer.MAX_VALUE个，则返回Integer.MAX_VALUE。
      返回:
      此集合中的元素数量

    • isEmpty

      boolean isEmpty()
      如果此集合不包含任何元素，则返回true。
      返回:
      如果此集合不包含任何元素，则返回true

    • contains

      boolean contains(Object o)
      如果此集合包含指定元素，则返回true。更正式地说，如果此集合包含至少一个元素e，使得Objects.equals(o, e)，则返回true。
      参数:
      o - 要测试其在此集合中是否存在的元素
      返回:
      如果此集合包含指定元素，则返回true
      抛出:
      ClassCastException - 如果指定元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定元素为null且此集合不允许null元素（可选）

    • iterator

      Iterator<E> iterator()
      返回此集合中元素的迭代器。对于返回元素的顺序没有任何保证（除非此集合是某个提供保证的类的实例）。
      指定者:
      iterator 在接口 Iterable<E>中
      返回值:
      返回此集合中所有元素的Iterator

    • toArray

      Object[] toArray()
      返回一个包含此集合中所有元素的数组。如果此集合对其元素由其迭代器返回的顺序有任何保证，此方法必须以相同顺序返回元素。返回的数组的运行时组件类型为Object。

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

      API 注意:
      此方法充当基于数组和基于集合的API之间的桥梁。它返回一个运行时类型为Object[]的数组。使用toArray(T[])来重用现有数组，或使用toArray(IntFunction)来控制数组的运行时类型。
      返回值:
      一个数组，其运行时组件类型为Object，包含此集合中的所有元素

    • toArray

      <T> T[] toArray(T[] a)
      返回一个包含此集合中所有元素的数组；返回的数组的运行时类型与指定数组相同。如果集合适合于指定数组，则将其返回。否则，将分配一个具有指定数组的运行时类型和此集合大小的新数组。

      如果此集合适合于指定数组且有多余空间（即，数组的元素多于此集合），则紧随集合末尾的数组元素将设置为null。（如果调用者知道此集合不包含任何null元素，则此功能仅用于确定此集合的长度。）

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

      API 注意:
      此方法充当基于数组和基于集合的API之间的桥梁。它允许在某些情况下重用现有数组。使用toArray()创建一个运行时类型为Object[]的数组，或使用toArray(IntFunction)来控制数组的运行时类型。

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

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

      返回值重新分配给变量y，因为如果集合x的元素太多而无法适应现有数组y，则将分配并返回一个新数组。

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

      类型参数:
      T - 包含集合的数组的组件类型
      参数:
      a - 如果足够大，则将此集合的元素存储到其中的数组；否则，将为此目的分配相同运行时类型的新数组。
      返回值:
      包含此集合中所有元素的数组
      抛出:
      ArrayStoreException - 如果此集合中任何元素的运行时类型不可分配给指定数组的运行时组件类型
      NullPointerException - 如果指定的数组为null

    • toArray

      default <T> T[] toArray(IntFunction<T[]> generator)
      使用提供的generator函数分配返回的数组，返回包含此集合中所有元素的数组。

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

      API 注意:
      此方法充当基于数组和基于集合的API之间的桥梁。它允许创建特定运行时类型的数组。使用toArray()创建一个运行时类型为Object[]的数组，或使用toArray(T[])重用现有数组。

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

           String[] y = x.toArray(String[]::new);
      实现要求:
      默认实现使用零调用生成函数，然后将生成的数组传递给toArray(T[])。
      类型参数:
      T - 包含集合的数组的组件类型
      参数:
      generator - 生成所需类型和提供长度的新数组的函数
      返回值:
      包含此集合中所有元素的数组
      抛出:
      ArrayStoreException - 如果此集合中任何元素的运行时类型不可分配给生成的数组的运行时组件类型
      NullPointerException - 如果生成函数为null
      自 JDK 版本:
      11

    • add

      boolean add(E e)
      确保此集合包含指定元素（可选操作）。如果调用导致此集合更改，则返回true。（如果此集合不允许重复并且已包含指定元素，则返回false。）

      支持此操作的集合可能会对可以添加到此集合的元素施加限制。特别是，某些集合将拒绝添加null元素，而其他集合将对可添加的元素类型施加限制。集合类应在其文档中明确指定可以添加哪些元素的任何限制。

      如果集合拒绝添加特定元素的原因不是因为已包含该元素，则必须抛出异常（而不是返回false）。这样可以保持不变性，即在此调用返回后，集合始终包含指定元素。

      参数:
      e - 要确保其在此集合中的存在的元素
      返回值:
      调用导致此集合更改，则返回true
      抛出:
      UnsupportedOperationException - 如果不支持add操作
      ClassCastException - 如果指定元素的类阻止将其添加到此集合
      NullPointerException - 如果指定元素为null且此集合不允许null元素
      IllegalArgumentException - 如果元素的某些属性阻止将其添加到此集合
      IllegalStateException - 如果由于插入限制，此时无法添加元素

    • remove

      boolean remove(Object o)
      从此集合中删除指定元素的单个实例（可选操作）。更正式地，如果此集合包含一个或多个这样的元素，使得Objects.equals(o, e)，则删除一个元素e。如果此集合包含指定元素，则返回true（或者等效地，如果此集合由于调用而更改）。
      参数:
      o - 如果存在，则从此集合中删除的元素
      返回值:
      如果调用导致删除一个元素，则返回true
      抛出:
      ClassCastException - 如果指定元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定元素为null且此集合不允许null元素（可选）
      UnsupportedOperationException - 如果不支持remove操作

    • containsAll

      boolean containsAll(Collection<?> c)
      如果此集合包含指定集合中的所有元素，则返回true。
      参数:
      c - 要检查其是否包含在此集合中的集合
      返回值:
      如果此集合包含指定集合中的所有元素，则返回true
      抛出:
      ClassCastException - 如果指定集合中一个或多个元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定集合包含一个或多个null元素且此集合不允许null元素（可选）或者指定集合为null。
      参见:

    • addAll

      boolean addAll(Collection<? extends E> c)
      将指定集合中的所有元素添加到此集合中（可选操作）。如果在操作进行时修改了指定集合，则此操作的行为是未定义的。（这意味着如果指定集合是此集合，并且此集合非空，则调用的行为是未定义的。）如果指定集合具有定义的遇到顺序，则通常按照该顺序处理其元素。
      参数：
      c - 包含要添加到此集合中的元素的集合
      返回：
      true 如果调用导致此集合发生更改
      抛出：
      UnsupportedOperationException - 如果此集合不支持addAll操作
      ClassCastException - 如果指定集合中的一个元素的类别阻止将其添加到此集合中
      NullPointerException - 如果指定集合包含空元素且此集合不允许空元素，或者指定集合为null
      IllegalArgumentException - 如果指定集合中的一个元素的某些属性阻止将其添加到此集合中
      IllegalStateException - 如果由于插入限制，此时无法添加所有元素
      参见：

    • removeAll

      boolean removeAll(Collection<?> c)
      从此集合中删除指定集合中也包含的所有元素（可选操作）。调用返回后，此集合将不包含与指定集合中的元素相同的任何元素。
      参数：
      c - 包含要从此集合中删除的元素的集合
      返回：
      true 如果调用导致此集合发生更改
      抛出：
      UnsupportedOperationException - 如果此集合不支持removeAll方法
      ClassCastException - 如果此集合中一个或多个元素的类型与指定集合不兼容（可选）
      NullPointerException - 如果此集合包含一个或多个空元素且指定集合不支持空元素（可选），或者指定集合为null
      参见：

    • removeIf

      default boolean removeIf(Predicate<? super E> filter)
      删除满足给定断言的此集合的所有元素。在迭代期间或由断言引发的错误或运行时异常将被传递给调用者。
      实现要求：
      默认实现使用其iterator()遍历集合的所有元素。使用Iterator.remove()删除每个匹配的元素。如果集合的迭代器不支持删除，则在第一个匹配元素上将抛出UnsupportedOperationException。
      参数：
      filter - 返回true以删除元素的断言
      返回：
      true 如果有任何元素被删除
      抛出：
      NullPointerException - 如果指定的过滤器为null
      UnsupportedOperationException - 如果无法从此集合中删除元素。如果无法删除匹配元素或者总体上不支持删除，实现可能会抛出此异常。
      自：
      1.8

    • retainAll

      boolean retainAll(Collection<?> c)
      仅保留此集合中包含在指定集合中的元素（可选操作）。换句话说，从此集合中删除不包含在指定集合中的所有元素。
      参数：
      c - 包含要在此集合中保留的元素的集合
      返回：
      true 如果调用导致此集合发生更改
      抛出：
      UnsupportedOperationException - 如果此集合不支持retainAll操作
      ClassCastException - 如果此集合中一个或多个元素的类型与指定集合不兼容（可选）
      NullPointerException - 如果此集合包含一个或多个空元素且指定集合不允许空元素（可选），或者指定集合为null
      参见：

    • clear

      void clear()
      从此集合中删除所有元素（可选操作）。此方法返回后，集合将为空。
      抛出：
      UnsupportedOperationException - 如果此集合不支持clear操作

    • equals

      boolean equals(Object o)
      将指定对象与此集合进行比较以确定它们是否相等。

      虽然Collection接口对Object.equals的一般契约没有规定，但是如果程序员直接实现Collection接口（换句话说，创建一个是Collection但不是Set或List的类），如果选择重写Object.equals，则必须谨慎。这并非必须这样做，最简单的做法是依赖于Object的实现，但实现者可能希望实现“值比较”来代替默认的“引用比较”。（List和Set接口规定了这样的值比较。）

      Object.equals方法的一般契约规定equals必须是对称的（换句话说，如果且仅如果a.equals(b)，则b.equals(a)）。List.equals和Set.equals的契约规定列表仅等于其他列表，集合仅等于其他集合。因此，对于实现既不实现List也不实现Set接口的集合类的自定义equals方法，在将此集合与任何列表或集合进行比较时必须返回false。（按照相同的逻辑，不可能编写一个正确实现Set和List接口的类。）

      覆盖：
      equals 在类 Object中
      参数：
      o - 用于与此集合比较相等性的对象
      返回：
      true 如果指定对象等于此集合
      参见：

    • hashCode

      int hashCode()
      返回此集合的哈希码值。虽然Collection接口对Object.hashCode方法的一般契约没有规定，但程序员应注意，任何重写Object.equals方法的类也必须重写Object.hashCode方法，以满足Object.hashCode方法的一般契约。特别是，c1.equals(c2)意味着c1.hashCode()==c2.hashCode()。
      覆盖：
      hashCode 在类 Object中
      返回：
      此集合的哈希码值
      参见：

    • spliterator

      default Spliterator<E> spliterator()
      创建一个Spliterator，用于遍历此集合中的元素。实现应该记录spliterator报告的特征值。如果spliterator报告了Spliterator.SIZED，并且此集合不包含任何元素，则不需要报告这些特征值。

      默认实现应该被子类重写，以返回一个更高效的spliterator。为了保持对于stream()和parallelStream()方法的预期惰性行为，spliterators应该具有IMMUTABLE或CONCURRENT的特征，或者是延迟绑定的。如果这些都不可行，重写的类应该描述spliterator的绑定和结构干扰的文档化策略，并且应该重写stream()和parallelStream()方法，使用spliterator的Supplier创建流，如下所示：

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

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

      指定者：
      spliterator 在接口 Iterable<E>
      实现要求：
      默认实现从集合的Iterator创建一个延迟绑定的spliterator。spliterator继承集合的iterator的快速失败属性。

      创建的Spliterator报告Spliterator.SIZED。

      实现说明：
      创建的Spliterator另外报告Spliterator.SUBSIZED。

      如果spliterator不包含任何元素，则报告额外特征值的报告，超出SIZED和SUBSIZED，不会帮助客户端控制、专门化或简化计算。然而，这使得可以共享使用一个不可变且空的spliterator实例（参见Spliterators.emptySpliterator()）用于空集合，并使客户端能够确定这样的spliterator是否不包含任何元素。

      返回值：
      此集合中的元素的Spliterator
      自：
      1.8

    • stream

      default Stream<E> stream()
      返回一个以此集合为源的顺序Stream。

      当spliterator()方法无法返回一个IMMUTABLE、CONCURRENT或延迟绑定的spliterator时，应该重写此方法。（详见spliterator()）

      实现要求：
      默认实现从集合的Spliterator创建一个顺序Stream。
      返回值：
      此集合中的元素的顺序Stream
      自：
      1.8

    • parallelStream

      default Stream<E> parallelStream()
      返回一个可能并行的以此集合为源的Stream。此方法可以返回一个顺序流。

      当spliterator()方法无法返回一个IMMUTABLE、CONCURRENT或延迟绑定的spliterator时，应该重写此方法。（详见spliterator()）

      实现要求：
      默认实现从集合的Spliterator创建一个并行Stream。
      返回值：
      可能并行的此集合中的元素的Stream
      自：
      1.8