模块 java.base
 java.util

接口 Collection<E>

类型参数:
E - 此集合中元素的类型
所有父级接口:
Iterable<E>
所有已知的子接口:
BeanContext , BeanContextServices , BlockingDeque<E> , BlockingQueue<E> , Deque<E> , EventSet , 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>
根接口在集合层次结构.集合代表一组对象,称为它的elements.有些集合允许重复元素,有些则不允许。有些是有序的,有些是无序的。 JDK 不提供任何直接的此接口的实现:它提供更具体的子接口的实现,如 SetList 。此接口通常用于传递集合并在需要最大通用性的地方操作它们。

或者多组(可能包含重复元素的无序集合)应该直接实现这个接口。

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

某些方法被指定为选修的.如果一个集合实现没有实现特定的操作,它应该定义相应的方法来抛出 UnsupportedOperationException 。这些方法在集合接口的方法规范中被标记为“可选操作”。

一些集合实现对它们可能包含的元素有限制。例如,有些实现禁止空元素,有些实现对其元素的类型有限制。尝试添加不合格的元素会引发未经检查的异常,通常是 NullPointerExceptionClassCastException 。尝试查询不合格元素的存在可能会抛出异常,或者可能只是返回 false;有些实现会表现出前者的行为,有些会表现出后者。更一般地,尝试对不合格元素执行操作,其完成不会导致将不合格元素插入集合中可能会抛出异常,也可能会成功,具体取决于实现的选择。此类异常在该接口的规范中被标记为“可选”。

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

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

一些执行集合递归遍历的集合操作可能会失败,但对于集合直接或间接包含自身的自引用实例除外。这包括 clone()equals()hashCode()toString() 方法。实现可以选择处理自引用场景,但是大多数当前实现不这样做。

查看集合

大多数集合管理它们包含的元素的存储。相比之下,查看集合它们本身不存储元素,而是依靠后备集合来存储实际元素。视图集合本身不处理的操作委托给后备集合。视图集合的示例包括由 Collections.checkedCollection Collections.synchronizedCollection Collections.unmodifiableCollection 等方法返回的包装器集合。视图集合的其他示例包括提供相同元素的不同表示的集合,例如,由 List.subList NavigableSet.subSet Map.entrySet 提供。对支持集合所做的任何更改都在视图集合中可见。相应地,对视图集合所做的任何更改(如果允许更改)都将写入后备集合。尽管从技术上讲它们不是集合,Iterator ListIterator 的实例也可以允许将修改写入后备集合,并且在某些情况下,对后备集合的修改将在迭代期间对迭代器可见。

不可修改的集合

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

一个不可修改的集合是一个集合,其所有增变器方法(如上定义)都指定为抛出 UnsupportedOperationException 。因此,不能通过调用其上的任何方法来修改此类集合。为了使集合正确不可修改,从它派生的任何视图集合也必须是不可修改的。例如,如果 List 是不可修改的,则 List.subList 返回的 List 也是不可修改的。

不可修改的集合不一定是不可变的。如果包含的元素是可变的,那么整个集合显然是可变的,即使它可能是不可修改的。例如,考虑两个包含可变元素的不可修改列表。如果元素已发生变化,调用 list1.equals(list2) 的结果可能不同于对下一个调用的结果,即使两个列表都是不可修改的。但是,如果一个不可修改的集合包含所有不可变元素,则可以认为它是有效不可变的。

不可修改的视图集合

一个不可修改的视图集合是一个不可修改的集合,也是一个支持集合的视图。它的 mutator 方法抛出 UnsupportedOperationException ,如上所述,而读取和查询方法被委托给后备集合。效果是提供对后备集合的只读访问。这对于组件向用户提供对内部集合的读取访问权限,同时防止他们意外修改此类集合非常有用。不可修改的视图集合的示例是由 Collections.unmodifiableCollection Collections.unmodifiableList 和相关方法返回的。

请注意,对后备集合的更改可能仍然是可能的,并且如果发生更改,它们通过不可修改的视图是可见的。因此,不可修改的视图集合不一定是不可变的。但是,如果不可修改视图的后备集合实际上是不可变的,或者如果对后备集合的唯一引用是通过不可修改视图,则可以认为该视图是有效不可变的。

集合的序列化

集合的可序列化性是可选的。因此,没有声明任何集合接口来实现 Serializable 接口。然而,可串行化被认为是普遍有用的,因此大多数集合实现都是可串行化的。

作为公共类的集合实现(例如 ArrayListHashMap )被声明为实现 Serializable 接口,如果它们实际上是可序列化的。某些集合实现不是公共类,例如 不可修改的集合。 在这种情况下,此类集合的可序列化性在创建它们的方法的规范中或在其他一些合适的地方进行了描述。在未指定集合的可序列化性的情况下,无法保证此类集合的可序列化性。特别是,许多 查看集合 不可序列化。

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

SortedSet SortedMap 的实例会发生另一种情况。这些集合可以使用 Comparator 创建,它对集合元素或映射键施加排序。仅当提供的 Comparator 也可序列化时,此类集合才可序列化。

此接口是 Java 集合框架 的成员。

实现要求:
默认方法实现(继承或其他方式)不应用任何同步协议。如果 Collection 实现具有特定的同步协议,则它必须覆盖默认实现以应用该协议。
自从:
1.2
参见:
  • 方法总结

    修饰符和类型
    方法
    描述
    boolean
    add(E e)
    确保此集合包含指定的元素(可选操作)。
    boolean
    addAll(Collection<? extends E> c)
    将指定集合中的所有元素添加到此集合(可选操作)。
    void
    从此集合中移除所有元素(可选操作)。
    boolean
    如果此集合包含指定元素,则返回 true
    boolean
    如果此集合包含指定集合中的所有元素,则返回 true
    boolean
    比较指定对象与此集合是否相等。
    int
    返回此集合的哈希码值。
    boolean
    如果此集合不包含任何元素,则返回 true
    返回此集合中元素的迭代器。
    default Stream<E>
    返回可能以此集合为源的并行 Stream
    boolean
    从此集合中移除指定元素的单个实例(如果存在) (可选操作)。
    boolean
    删除此集合的所有也包含在指定集合中的元素(可选操作)。
    default boolean
    removeIf(Predicate<? super E> filter)
    移除此集合中满足给定谓词的所有元素。
    boolean
    仅保留此集合中包含在指定集合中的元素(可选操作)。
    int
    size()
    返回此集合中的元素数。
    default Spliterator<E>
    在此集合中的元素上创建一个 Spliterator
    default Stream<E>
    返回以此集合为源的顺序 Stream
    返回包含此集合中所有元素的数组。
    default <T> T[]
    toArray(IntFunction<T[]> generator)
    返回包含此集合中所有元素的数组,使用提供的 generator 函数分配返回的数组。
    <T> T[]
    toArray(T[] a)
    返回包含此集合中所有元素的数组;返回数组的运行时类型是指定数组的类型。

    在接口 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 使得 Objects.equals(o, e)
      参数:
      o - 要测试其在此集合中是否存在的元素
      返回:
      true 如果这个集合包含指定的元素
      抛出:
      ClassCastException - 如果指定元素的类型与此集合不兼容 (optional)
      NullPointerException - 如果指定元素为空且此集合不允许空元素 (optional)
    • 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 - 如果指定数组为空
    • 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 - 如果生成器函数为空
      自从:
      11
    • add

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

      支持此操作的集合可能会限制可以添加到此集合的元素。特别是,一些馆藏会拒绝添加null个元素,而另一些馆藏会限制可以添加的元素类型。集合类应在其文档中明确指定对可以添加的元素的任何限制。

      如果集合出于任何原因拒绝添加特定元素,而不是因为它已经包含该元素,则它必须抛出异常(而不是返回 false )。这保留了此调用返回后集合始终包含指定元素的不变性。

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

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

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

      boolean addAll(Collection <? extends E > c)
      将指定集合中的所有元素添加到此集合(可选操作)。如果在操作进行时修改了指定的集合,则此操作的行为是未定义的。 (这意味着如果指定的集合是这个集合并且这个集合是非空的,那么这个调用的行为是未定义的。)
      参数:
      c - 包含要添加到此集合的元素的集合
      返回:
      true 如果此集合因调用而更改
      抛出:
      UnsupportedOperationException - 如果此集合不支持 addAll 操作
      ClassCastException - 如果指定集合的元素的类阻止将其添加到此集合
      NullPointerException - 如果指定的集合包含空元素并且此集合不允许空元素,或者如果指定的集合为空
      IllegalArgumentException - 如果指定集合的元素的某些属性阻止将其添加到此集合
      IllegalStateException - 如果由于插入限制此时不能添加所有元素
      参见:
    • removeAll

      boolean removeAll(Collection <?> c)
      删除此集合的所有也包含在指定集合中的元素(可选操作)。此调用返回后,此集合将不包含与指定集合共有的元素。
      参数:
      c - 包含要从此集合中删除的元素的集合
      返回:
      true 如果此集合因调用而更改
      抛出:
      UnsupportedOperationException - 如果此集合不支持 removeAll 方法
      ClassCastException - 如果此集合中的一个或多个元素的类型与指定集合不兼容 (optional)
      NullPointerException - 如果此集合包含一个或多个空元素并且指定的集合不支持空元素 (optional),或者如果指定的集合为空
      参见:
    • 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),或者如果指定的集合为空
      参见:
    • clear

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

      boolean equals(Object  o)
      比较指定对象与此集合是否相等。

      虽然 Collection 接口没有为 Object.equals 的通用契约添加规定,但“直接”实现 Collection 接口的程序员(换句话说,创建一个 Collection 但不是 SetList 的类)必须小心,如果他们选择覆盖 Object.equals 。没有必要这样做,最简单的做法是依赖 Object 的实现,但实现者可能希望实现“值比较”来代替默认的“参考比较”。 (ListSet 接口要求进行此类值比较。)

      Object.equals 方法的一般契约声明 equals 必须是对称的(换句话说, a.equals(b) 当且仅当 b.equals(a) )。 List.equalsSet.equals 的合同声明列表只等于其他列表,集合等于其他集合。因此,当此集合与任何列表或集合进行比较时,既不实现 List 也不实现 Set 接口的集合类的自定义 equals 方法必须返回 false。 (按照同样的逻辑,不可能编写一个正确实现 SetList 接口的类。)

      重写:
      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.SIZED 并且此集合不包含任何元素,则不需要报告此类特征值。

      默认实现应该被可以返回更高效的拆分器的子类覆盖。为了保留 stream() parallelStream() 方法的预期惰性行为,拆分器应该具有 IMMUTABLECONCURRENT 的特征,或者是 late-binding 。如果这些都不可行,覆盖类应该描述拆分器的绑定和结构干扰的记录策略,并且应该覆盖 stream() parallelStream() 方法以使用拆分器的 Supplier 创建流,如下所示:

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

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

      指定者:
      spliterator 在接口 Iterable<E>
      实现要求:
      默认实现从集合的 Iterator 创建一个 late-binding 拆分器。拆分器继承了集合迭代器的 fail-fast 属性。

      创建的 Spliterator 报告 Spliterator.SIZED

      实现注意事项:
      创建的 Spliterator 还报告 Spliterator.SUBSIZED

      如果拆分器不包含任何元素,则除了 SIZEDSUBSIZED 之外的其他特征值的报告不会帮助客户控制、专门化或简化计算。但是,这确实可以为空集合共享不可变的空拆分器实例(请参阅 Spliterators.emptySpliterator() ),并使客户端能够确定这样的拆分器是否不包含任何元素。

      返回:
      a Spliterator 覆盖此集合中的元素
      自从:
      1.8
    • stream

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

      spliterator() 方法不能返回 IMMUTABLECONCURRENTlate-binding 的拆分器时,应覆盖此方法。 (有关详细信息,请参阅 spliterator() 。)

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

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

      spliterator() 方法不能返回 IMMUTABLECONCURRENTlate-binding 的拆分器时,应覆盖此方法。 (有关详细信息,请参阅 spliterator() 。)

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