Module java.base
Package java.util

Class AbstractCollection<E>

java.lang.Object
java.util.AbstractCollection<E>
类型参数:
E - 此集合中元素的类型
所有已实现的接口:
Iterable<E>, Collection<E>
直接已知的子类:
AbstractList, AbstractQueue, AbstractSet, ArrayDeque, ConcurrentLinkedDeque
public abstract class AbstractCollection<E> extends Object implements Collection<E>
此类提供了Collection接口的骨架实现，以最小化实现此接口所需的工作量。

要实现一个不可修改的集合，程序员只需扩展此类并为iterator和size方法提供实现即可。（iterator方法返回的迭代器必须实现hasNext和next。）

要实现一个可修改的集合，程序员必须另外覆盖此类的add方法（否则会抛出UnsupportedOperationException），iterator方法返回的迭代器还必须实现其remove方法。

通常，程序员应该提供一个无参数的Collection构造函数，根据Collection接口规范的建议。

此类中每个非抽象方法的文档详细描述了其实现。如果正在实现的集合允许更有效的实现，则可以覆盖这些方法中的每一个。

此类是Java集合框架的成员。

自版本:
1.2
参见:

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AbstractCollection()
    唯一构造函数。

  • 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
    isEmpty()
    如果此集合不包含任何元素，则返回true。
    abstract Iterator<E>
    iterator()
    返回此集合中包含的元素的迭代器。
    boolean
    remove(Object o)
    从此集合中移除指定元素的单个实例（如果存在）（可选操作）。
    boolean
    removeAll(Collection<?> c)
    移除此集合中同时包含在指定集合中的所有元素（可选操作）。
    boolean
    retainAll(Collection<?> c)
    仅保留此集合中包含在指定集合中的元素（可选操作）。
    Object[]
    toArray()
    返回一个包含此集合中所有元素的数组。
    <T> T[]
    toArray(T[] a)
    返回一个包含此集合中所有元素的数组；返回数组的运行时类型与指定数组的类型相同。
    String
    toString()
    返回此集合的字符串表示形式。

    Methods declared in class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods declared in interface java.util.Collection

    equals, hashCode, parallelStream, removeIf, size, spliterator, stream, toArray

    Methods declared in interface java.lang.Iterable

    forEach

  • Constructor Details

    • AbstractCollection

      protected AbstractCollection()
      唯一构造函数。（通常由子类构造函数隐式调用。）

  • Method Details

    • iterator

      public abstract Iterator<E> iterator()
      返回此集合中包含的元素的迭代器。
      指定者:
      iterator 在接口 Collection<E>中
      指定者:
      iterator 在接口 Iterable<E>中
      返回:
      包含此集合中元素的迭代器

    • isEmpty

      public boolean isEmpty()
      如果此集合不包含任何元素，则返回true。
      指定者:
      isEmpty 在接口 Collection<E>中
      实现要求:
      此实现返回size() == 0。
      返回:
      如果此集合不包含任何元素，则返回true

    • contains

      public boolean contains(Object o)
      如果此集合包含指定的元素，则返回true。更正式地说，如果此集合包含至少一个元素e，使得Objects.equals(o, e)，则返回true。
      指定者:
      contains 在接口 Collection<E>中
      实现要求:
      此实现遍历集合中的元素，依次检查每个元素是否与指定元素相等。
      参数:
      o - 要测试其在此集合中存在性的元素
      返回:
      如果此集合包含指定的元素，则返回true
      抛出:
      ClassCastException - 如果指定元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定元素为null且此集合不允许null元素（可选）

    • toArray

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

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

      指定者:
      toArray 在接口 Collection<E>中
      实现要求:
      此实现返回一个包含此集合的迭代器返回的所有元素的数组，顺序相同，存储在数组的连续元素中，从索引0开始。返回的数组的长度等于迭代器返回的元素数，即使在迭代过程中此集合的大小发生变化，例如，如果集合允许在迭代过程中进行并发修改。仅作为优化提示调用size方法；即使迭代器返回不同数量的元素，也会返回正确的结果。

      此方法等效于：

       
 List<E> list = new ArrayList<E>(size());
 for (E e : this)
     list.add(e);
 return list.toArray();
      返回:
      一个数组，其运行时组件类型为Object，包含此集合中的所有元素

    • toArray

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

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

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

      指定由:
      toArray 在接口 Collection<E>
      实现要求:
      此实现返回一个包含此集合迭代器返回的所有元素的数组，顺序相同，存储在数组的连续元素中，从索引0开始。如果迭代器返回的元素数量太大，无法适应指定的数组，则元素将以新分配的数组返回，其长度等于迭代器返回的元素数量，即使在迭代过程中此集合的大小发生更改，如果集合允许在迭代过程中进行并发修改，可能会发生这种情况。 size方法仅作为优化提示调用; 即使迭代器返回不同数量的元素，也会返回正确的结果。

      此方法等效于:

       
 List<E> list = new ArrayList<E>(size());
 for (E e : this)
     list.add(e);
 return list.toArray(a);
      类型参数:
      T - 包含集合的数组的组件类型
      参数:
      a - 如果足够大，则将此集合的元素存储在其中的数组; 否则，将为此目的分配相同运行时类型的新数组。
      返回:
      包含此集合中所有元素的数组
      抛出:
      ArrayStoreException - 如果此集合中任何元素的运行时类型不可分配给指定数组的运行时组件类型
      NullPointerException - 如果指定的数组为null

    • add

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

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

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

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

    • remove

      public boolean remove(Object o)
      从此集合中删除指定元素的单个实例（可选操作）。更正式地，如果此集合包含一个或多个这样的元素，即Objects.equals(o, e)，则删除一个元素e。如果此集合包含指定元素，则返回true（或等效地，如果调用导致此集合更改）。
      指定由:
      remove 在接口 Collection<E>
      实现要求:
      此实现遍历集合，查找指定元素。如果找到元素，则使用迭代器的remove方法从集合中删除元素。

      请注意，如果此集合的迭代器方法返回的迭代器不实现remove方法，并且此集合包含指定对象，则此实现将抛出UnsupportedOperationException。

      参数:
      o - 如果存在，则要从此集合中删除的元素
      返回:
      如果调用导致删除元素，则返回true
      抛出:
      UnsupportedOperationException - 如果此集合不支持remove操作
      ClassCastException - 如果指定元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定元素为null且此集合不允许null元素（可选）

    • containsAll

      public boolean containsAll(Collection<?> c)
      如果此集合包含指定集合中的所有元素，则返回true。
      指定由:
      containsAll 在接口 Collection<E>
      实现要求:
      此实现遍历指定集合，依次检查迭代器返回的每个元素，以查看它是否包含在此集合中。如果所有元素都包含在其中，则返回true，否则返回false。
      参数:
      c - 要在此集合中检查包含性的集合
      返回:
      如果此集合包含指定集合中的所有元素，则返回true
      抛出:
      ClassCastException - 如果指定集合中一个或多个元素的类型与此集合不兼容（可选）
      NullPointerException - 如果指定集合包含一个或多个null元素且此集合不允许null元素（可选），或者指定集合为null。
      参见:

    • addAll

      public boolean addAll(Collection<? extends E> c)
      将指定集合中的所有元素添加到此集合中（可选操作）。如果在操作进行时修改了指定集合，则此操作的行为是未定义的。（这意味着如果指定集合是此集合，并且此集合非空，则此调用的行为是未定义的。）如果指定集合具有定义的遇到顺序，则其元素的处理通常按照该顺序进行。
      指定由:
      addAll 在接口 Collection<E>
      实现要求:
      此实现遍历指定集合，并依次将迭代器返回的每个对象添加到此集合中。

      请注意，除非重写add（假设指定集合非空），否则此实现将抛出UnsupportedOperationException。

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

    • removeAll

      public boolean removeAll(Collection<?> c)
      从指定集合中移除该集合中包含的所有元素（可选操作）。调用此方法后，该集合将不再包含与指定集合相同的任何元素。
      指定者：
      removeAll 在接口 Collection<E>
      实现要求：
      此实现遍历该集合，依次检查迭代器返回的每个元素，看它是否包含在指定集合中。如果包含，则使用迭代器的remove方法从该集合中移除。

      请注意，如果由iterator方法返回的迭代器未实现remove方法，并且该集合包含一个或多个与指定集合相同的元素，则此实现将抛出UnsupportedOperationException异常。

      参数：
      c - 包含要从该集合中移除的元素的集合
      返回值：
      调用后，如果该集合发生更改，则返回true
      抛出：
      UnsupportedOperationException - 如果该集合不支持removeAll方法
      ClassCastException - 如果该集合中一个或多个元素的类型与指定集合不兼容（可选）
      NullPointerException - 如果该集合包含一个或多个空元素，而指定集合不支持空元素（可选），或者指定集合为null
      参见：

    • retainAll

      public boolean retainAll(Collection<?> c)
      仅保留该集合中包含在指定集合中的元素（可选操作）。换句话说，从该集合中移除所有不包含在指定集合中的元素。
      指定者：
      retainAll 在接口 Collection<E>
      实现要求：
      此实现遍历该集合，依次检查迭代器返回的每个元素，看它是否包含在指定集合中。如果不包含，则使用迭代器的remove方法从该集合中移除。

      请注意，如果由该集合的iterator方法返回的迭代器未实现remove方法，并且该集合包含一个或多个不在指定集合中的元素，则此实现将抛出UnsupportedOperationException异常。

      参数：
      c - 包含要在该集合中保留的元素的集合
      返回值：
      调用后，如果该集合发生更改，则返回true
      抛出：
      UnsupportedOperationException - 如果该集合不支持retainAll操作
      ClassCastException - 如果该集合中一个或多个元素的类型与指定集合不兼容（可选）
      NullPointerException - 如果该集合包含一个或多个空元素，而指定集合不允许空元素（可选），或者指定集合为null
      参见：

    • clear

      public void clear()
      从该集合中移除所有元素（可选操作）。此方法返回后，集合将为空。
      指定者：
      clear 在接口 Collection<E>
      实现要求：
      此实现遍历该集合，使用Iterator.remove操作逐个移除每个元素。大多数实现可能会选择重写此方法以提高效率。

      请注意，如果由该集合的iterator方法返回的迭代器未实现remove方法，并且该集合非空，则此实现将抛出UnsupportedOperationException异常。

      抛出：
      UnsupportedOperationException - 如果该集合不支持clear操作

    • toString

      public String toString()
      返回该集合的字符串表示形式。字符串表示形式由集合的元素列表组成，按其迭代器返回的顺序排列，用方括号（"[]"）括起来。相邻元素由字符", "（逗号和空格）分隔。元素将被转换为字符串，如同通过String.valueOf(Object)进行的转换。
      覆盖：
      toString 在类 Object
      返回值：
      该集合的字符串表示形式