模块  java.base
软件包  java.util

Interface Collection<E>

  • 参数类型
    E - 此集合中的元素类型
    All Superinterfaces:
    Iterable<E>
    All Known Subinterfaces:
    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>
    集合层次结构中的根接口。 集合表示一组对象，称为其元素 。 有些集合允许重复元素而其他集合则不允许。 有些是订购的，有些是无序的。 JDK不提供此接口的任何直接实现：它提供了更具体的子接口的实现，如Set和List 。 此接口通常用于传递集合并在需要最大通用性的情况下对其进行操作。

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

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

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

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

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

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

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

    View Collections

    大多数集合管理它们包含的元素的存储。 相比之下， 视图集合本身不存储元素，而是依赖于后备集合来存储实际元素。 视图集合本身未处理的操作将委派给后备集合。 视图集合的例子包括通过诸如返回的包装集合Collections.checkedCollection ， Collections.synchronizedCollection ，和Collections.unmodifiableCollection 。 视图集合的其他实例包括提供相同的元件的不同表示，例如，如通过提供集合List.subList ， NavigableSet.subSet ，或Map.entrySet 。 对视图集合所做的任何更改都在视图集合中可见。 相应地，对视图集合所做的任何更改 - 如果允许更改 - 都会写入后备集合。 虽然它们在技术上不是集合，但Iterator和ListIterator的实例也可以允许将修改写入到后备集合中，并且在某些情况下，迭代期间Iterator可以看到对后备集合的修改。

    Unmodifiable Collections

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

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

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

    Unmodifiable View Collections

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

    请注意，可能仍然可以对支持集合进行更改，如果它们发生，则通过不可修改的视图可以看到它们。 因此，不可修改的视图集合不一定是不可变的。 但是，如果不可修改视图的后备集合实际上是不可变的，或者对后备集合的唯一引用是通过不可修改的视图，则视图可以被视为有效不可变。

    此界面是Java Collections Framework的成员。

    实现要求：
    默认方法实现（继承或其他方式）不应用任何同步协议。 如果Collection实现具有特定的同步协议，则它必须覆盖默认实现以应用该协议。
    从以下版本开始：
    1.2
    另请参见：
    Set ， List ， Map ， SortedSet ， SortedMap ， HashSet ， TreeSet ， ArrayList ， LinkedList ， Vector ， Collections ， Arrays ， AbstractCollection

    • 方法摘要

      所有方法  实例方法 抽象方法  Default Methods 
      变量和类型 方法 描述
      boolean add​(E e)
      确保此集合包含指定的元素（可选操作）。
      boolean addAll​(Collection<? extends E> c)
      将指定集合中的所有元素添加到此集合中（可选操作）。
      void clear()
      从此集合中删除所有元素（可选操作）。
      boolean contains​(Object o)
      如果此collection包含指定的元素，则返回 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)
      返回一个包含此collection中所有元素的数组; 返回数组的运行时类型是指定数组的运行时类型。

    • 方法详细信息

      • size

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

      • isEmpty

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

      • contains

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

      • iterator

        Iterator<E> iterator()
        返回此集合中元素的迭代器。 对于返回元素的顺序没有任何保证（除非此集合是某个提供保证的类的实例）。
        Specified by:
        iterator ，界面 Iterable<E>
        结果
        这个集合中的元素是 Iterator

      • toArray

        Object[] toArray()
        返回包含此集合中所有元素的数组。 如果此集合对其迭代器返回的元素的顺序做出任何保证，则此方法必须以相同的顺序返回元素。 返回的数组runtime component type是Object 。

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

        API Note:
        此方法充当基于阵列和基于集合的API之间的桥梁。 它返回一个运行时类型为Object[]的数组。 使用toArray(T[])重用现有阵列，或使用toArray(IntFunction)控制阵列的运行时类型。
        结果
        一个数组，其 runtime component type是 Object ，包含此集合中的所有元素

      • toArray

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

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

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

        API Note:
        此方法充当基于阵列和基于集合的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 - 如果此集合中任何元素的运行时类型不能分配给指定数组的 runtime component type
        NullPointerException - 如果指定的数组为null

      • toArray

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

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

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

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

          String[] y = x.toArray(String[]::new);
        实现要求：
        默认实现调用生成器函数为零，然后将结果数组传递给 toArray(T[]) 。
        参数类型
        T - 包含集合的数组的组件类型
        参数
        generator - 产生所需类型和提供长度的新数组的函数
        结果
        包含此集合中所有元素的数组
        异常
        ArrayStoreException - 如果此集合中任何元素的运行时类型不能分配给生成的数组的 runtime component type
        NullPointerException - 如果生成器函数为null
        从以下版本开始：
        11

      • add

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

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

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

        参数
        e - 要确保其在此集合中的存在的元素
        结果
        true如果此集合因呼叫而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 add操作
        ClassCastException - 如果指定元素的类阻止将其添加到此集合中
        NullPointerException - 如果指定的元素为null且此collection不允许null元素
        IllegalArgumentException - 如果元素的某些属性阻止将其添加到此集合中
        IllegalStateException - 如果由于插入限制而无法在此时添加元素

      • remove

        boolean remove​(Object o)
        从此集合中移除指定元素的单个实例（如果存在）（可选操作）。 更正式地，如果此集合包含一个或多个此类元素，则删除元素e ，使其为Objects.equals(o, e) 。 如果此集合包含指定的元素，则返回true （或等效地，如果此集合因调用而更改）。
        参数
        o - 要从此集合中删除的元素（如果存在）
        结果
        true如果由于此调用而删除了某个元素
        异常
        ClassCastException - 如果指定元素的类型与此集合不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此collection不允许null元素（ optional ）
        UnsupportedOperationException - 如果此集合不支持 remove操作

      • containsAll

        boolean containsAll​(Collection<?> c)
        如果此集合包含指定集合中的所有元素，则返回 true 。
        参数
        c - 要检查此集合中的包含的集合
        结果
        true如果此集合包含指定集合中的所有元素
        异常
        ClassCastException - 如果指定集合中的一个或多个元素的类型与此集合不兼容（ optional ）
        NullPointerException - 如果指定的集合包含一个或多个null元素，并且此集合不允许null元素（ optional ），或者指定的集合为null。
        另请参见：
        contains(Object)

      • addAll

        boolean addAll​(Collection<? extends E> c)
        将指定集合中的所有元素添加到此集合中（可选操作）。 如果在操作正在进行时修改了指定的集合，则此操作的行为是不确定的。 （这意味着如果指定的集合是此集合，则此调用的行为是未定义的，并且此集合是非空的。）
        参数
        c - 包含要添加到此集合的元素的集合
        结果
        true如果此集合因调用而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 addAll操作
        ClassCastException - 如果指定集合的元素的类阻止将其添加到此集合中
        NullPointerException - 如果指定的集合包含null元素，并且此集合不允许null元素，或者指定的集合为null
        IllegalArgumentException - 如果指定集合的某个元素的某些属性阻止将其添加到此集合中
        IllegalStateException - 如果不是因为插入限制，此时可以添加所有元素
        另请参见：
        add(Object)

      • removeAll

        boolean removeAll​(Collection<?> c)
        删除此集合的所有元素，这些元素也包含在指定的集合中（可选操作）。 此调用返回后，此集合将不包含与指定集合相同的元素。
        参数
        c - 包含要从此集合中删除的元素的集合
        结果
        true如果此集合因呼叫而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 removeAll方法
        ClassCastException - 如果此集合中的一个或多个元素的类型与指定的集合不兼容（ optional ）
        NullPointerException - 如果此集合包含一个或多个null元素且指定的集合不支持null元素（ optional ），或者指定的集合为null
        另请参见：
        remove(Object) ， contains(Object)

      • 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 - 如果此集合中的一个或多个元素的类型与指定的集合不兼容（ optional ）
        NullPointerException - 如果此集合包含一个或多个null元素且指定的集合不允许null元素（ optional ），或者指定的集合为null
        另请参见：
        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并且此集合不包含任何元素，则不需要报告此类特征值。

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

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

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

        Specified by:
        spliterator ，界面 Iterable<E>
        实现要求：
        默认实现从集合的Iterator创建late-binding Iterator 。 spliterator继承了集合迭代器的fail-fast属性。

        创建的Spliterator报告Spliterator.SIZED 。

        Implementation Note:
        创建的Spliterator另外报告Spliterator.SUBSIZED 。

        如果分裂器不包含任何元素，那么除了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