模块  java.base
软件包  java.util

Class AbstractCollection<E>

  • 实现的所有接口
    Iterable<E> ， Collection<E>
    已知直接子类：
    AbstractList ， AbstractQueue ， AbstractSet ， ArrayDeque ， ConcurrentLinkedDeque 
    public abstract class AbstractCollection<E>
extends Object
implements Collection<E>
    此类提供Collection接口的Collection实现，以最大限度地减少实现此接口所需的工作量。

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

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

    根据Collection接口规范中的建议，程序员通常应提供void（无参数）和Collection构造函数。

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

    此类是Java Collections Framework的成员。

    从以下版本开始：
    1.2
    另请参见：
    Collection

    • 构造方法详细信息

      • AbstractCollection

        protected AbstractCollection()
        唯一的构造函数。 （对于子类构造函数的调用，通常是隐式的。）

    • 方法详细信息

      • iterator

        public abstract Iterator<E> iterator()
        返回此collection中包含的元素的迭代器。
        Specified by:
        iterator in interface Collection<E>
        Specified by:
        iterator在界面 Iterable<E>
        结果
        包含在此集合中的元素的迭代器

      • isEmpty

        public boolean isEmpty()
        如果此集合不包含任何元素，则返回 true 。
        Specified by:
        isEmpty in interface Collection<E>
        实现要求：
        此实现返回 size() == 0 。
        结果
        true如果此集合不包含任何元素

      • contains

        public boolean contains​(Object o)
        如果此collection包含指定的元素，则返回true 。 更正式的，返回true当且仅当此集合包含至少一个元素e如Objects.equals(o, e) 。
        Specified by:
        contains ，接口 Collection<E>
        实现要求：
        此实现迭代集合中的元素，依次检查每个元素是否与指定元素相等。
        参数
        o - 要测试其在此集合中的存在的元素
        结果
        true如果此集合包含指定的元素
        异常
        ClassCastException - 如果指定元素的类型与此集合不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此collection不允许null元素（ optional ）

      • toArray

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

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

        Specified by:
        toArray in interface Collection<E>
        实现要求：
        此实现返回一个数组，该数组包含此集合的迭代器返回的所有元素，以相同的顺序存储在数组的连续元素中，从索引0开始。 返回数组的长度等于迭代器返回的元素数，即使此集合的大小在迭代期间发生更改，如果集合允许在迭代期间进行并发修改，也可能发生这种情况。 size方法仅作为优化提示调用; 即使迭代器返回不同数量的元素，也会返回正确的结果。

        这种方法相当于： 

           List<E> list = new ArrayList<E>(size()); for (E e : this) list.add(e); return list.toArray();
        结果
        一个数组，其 runtime component type是 Object ，包含此集合中的所有元素

      • toArray

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

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

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

        Specified by:
        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 - 如果此集合中任何元素的运行时类型不能分配给指定数组的 runtime component type
        NullPointerException - 如果指定的数组为null

      • add

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

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

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

        Specified by:
        add ，界面 Collection<E>
        实现要求：
        这个实现总是抛出 UnsupportedOperationException 。
        参数
        e - 要确保其在此集合中的存在的元素
        结果
        true如果此集合因呼叫而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 add操作
        ClassCastException - 如果指定元素的类阻止将其添加到此集合中
        NullPointerException - 如果指定的元素为null且此collection不允许null元素
        IllegalArgumentException - 如果元素的某些属性阻止将其添加到此集合中
        IllegalStateException - 如果由于插入限制而无法在此时添加元素

      • remove

        public boolean remove​(Object o)
        从此集合中移除指定元素的单个实例（如果存在）（可选操作）。 更正式地，如果此集合包含一个或多个此类元素，则删除元素e ，使其为Objects.equals(o, e) 。 如果此集合包含指定的元素，则返回true （或等效地，如果此集合因调用而更改）。
        Specified by:
        remove接口 Collection<E>
        实现要求：
        此实现迭代集合以查找指定的元素。 如果找到该元素，它将使用迭代器的remove方法从集合中删除该元素。

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

        参数
        o - 要从此集合中删除的元素（如果存在）
        结果
        true如果由于此调用而删除了某个元素
        异常
        UnsupportedOperationException - 如果此集合不支持 remove操作
        ClassCastException - 如果指定元素的类型与此集合不兼容（ optional ）
        NullPointerException - 如果指定的元素为null且此collection不允许null元素（ optional ）

      • containsAll

        public boolean containsAll​(Collection<?> c)
        如果此集合包含指定集合中的所有元素，则返回 true 。
        Specified by:
        containsAll ，界面 Collection<E>
        实现要求：
        此实现迭代指定的集合，依次检查迭代器返回的每个元素以查看它是否包含在此集合中。 如果所有元素都这样包含true返回，否则false 。
        参数
        c - 要检查此集合中的包含的集合
        结果
        true此集合是否包含指定集合中的所有元素
        异常
        ClassCastException - 如果指定集合中的一个或多个元素的类型与此集合不兼容（ optional ）
        NullPointerException - 如果指定的集合包含一个或多个null元素，并且此集合不允许null元素（ optional ），或者指定的集合为null。
        另请参见：
        contains(Object)

      • addAll

        public boolean addAll​(Collection<? extends E> c)
        将指定集合中的所有元素添加到此集合中（可选操作）。 如果在操作正在进行时修改了指定的集合，则此操作的行为是不确定的。 （这意味着如果指定的集合是此集合，则此调用的行为是未定义的，并且此集合是非空的。）
        Specified by:
        addAll在界面 Collection<E>
        实现要求：
        此实现迭代指定的集合，并依次将迭代器返回的每个对象添加到此集合。

        请注意，此实现将抛出UnsupportedOperationException除非add被覆盖（假定指定的collection非空）。

        参数
        c - 包含要添加到此集合的元素的集合
        结果
        true如果此集合因呼叫而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 addAll操作
        ClassCastException - 如果指定集合的元素的类阻止将其添加到此集合中
        NullPointerException - 如果指定的集合包含null元素，并且此集合不允许null元素，或者指定的集合为null
        IllegalArgumentException - 如果指定集合的元素的某些属性阻止将其添加到此集合中
        IllegalStateException - 如果不是因为插入限制，此时可以添加所有元素
        另请参见：
        add(Object)

      • removeAll

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

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

        参数
        c - 包含要从此集合中删除的元素的集合
        结果
        true如果此集合因调用而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 removeAll方法
        ClassCastException - 如果此集合中的一个或多个元素的类型与指定的集合不兼容（ optional ）
        NullPointerException - 如果此集合包含一个或多个null元素且指定的集合不支持null元素（ optional ），或者指定的集合为null
        另请参见：
        remove(Object) ， contains(Object)

      • retainAll

        public boolean retainAll​(Collection<?> c)
        仅保留此集合中包含在指定集合中的元素（可选操作）。 换句话说，从此集合中删除未包含在指定集合中的所有元素。
        Specified by:
        retainAll在界面 Collection<E>
        实现要求：
        此实现迭代此集合，依次检查迭代器返回的每个元素，以查看它是否包含在指定的集合中。 如果它没有包含，则使用迭代器的remove方法将其从此集合中删除。

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

        参数
        c - 包含要在此集合中保留的元素的集合
        结果
        true如果此集合因呼叫而更改
        异常
        UnsupportedOperationException - 如果此集合不支持 retainAll操作
        ClassCastException - 如果此集合中的一个或多个元素的类型与指定的集合不兼容（ optional ）
        NullPointerException - 如果此集合包含一个或多个null元素且指定的集合不允许null元素（ optional ），或者指定的集合为null
        另请参见：
        remove(Object) ， contains(Object)

      • clear

        public void clear()
        从此集合中删除所有元素（可选操作）。 此方法返回后，该集合将为空。
        Specified by:
        clear在接口 Collection<E>
        实现要求：
        此实现迭代此集合，使用Iterator.remove操作删除每个元素。 大多数实现可能会选择覆盖此方法以提高效率。

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

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

      • toString

        public String toString()
        返回此集合的字符串表示形式。 字符串表示由一个集合元素的列表组成，它们的迭代器返回它们的顺序，用方括号括起来（ "[]" ）。 相邻元素由字符", " （逗号和空格）分隔。 元素将转换为字符串，如String.valueOf(Object)所示 。
        重写：
        toString类 Object
        结果
        a string representation of this collection