java.util
类 AbstractCollection

java.lang.Object
  java.util.AbstractCollection<E>

所有已实现的接口：

Iterable<E>, Collection<E>

直接已知子类：

AbstractList, AbstractQueue, AbstractSet, ArrayDeque

public abstract class AbstractCollection<E>
     

      extends 
      Object
     
     

      implements 
      Collection<E>
     

此类提供 Collection 接口的骨干实现，以最大限度地减少了实现此接口所需的工作。

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

要实现可修改的 collection，编程人员必须另外重写此类的 add 方法（否则，会抛出 UnsupportedOperationException），iterator 方法返回的迭代器还必须另外实现其 remove 方法。

按照 Collection 接口规范中的建议，编程人员通常应提供一个 void （无参数）和 Collection 构造方法。

此类中每个非抽象方法的文档详细描述了其实现。如果要实现的 collection 允许更有效的实现，则可以重写这些方法中的每个方法。

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.2

另请参见：

Collection

AbstractCollection

protected AbstractCollection()

唯一的构造方法。（由子类构造方法调用，通常是隐式的。）

iterator

public abstract Iterator<E> iterator()

返回在此 collection 中的元素上进行迭代的迭代器。

指定者：

接口 Iterable<E> 中的 iterator

指定者：

接口 Collection<E> 中的 iterator

返回：

在此 collection 中的元素上进行迭代的迭代器。

size

public abstract int size()

从接口 Collection 复制的描述

返回此 collection 中的元素数。如果此 collection 包含的元素大于 Integer.MAX_VALUE，则返回 Integer.MAX_VALUE。

指定者：

接口 Collection<E> 中的 size

返回：

此 collection 中的元素数

isEmpty

public boolean isEmpty()

如果此 collection 不包含元素，则返回 true。

此实现返回 size() == 0。

指定者：

接口 Collection<E> 中的 isEmpty

返回：

如果此 collection 不包含元素，则返回 true

contains

public boolean contains(Object o)

如果此 collection 包含指定的元素，则返回 true。更确切地讲，当且仅当此 collection 至少包含一个满足 (o==null ? e==null : o.equals(e)) 的元素 e 时，返回 true。

此实现在 collection 中的元素上进行迭代，并依次检查每个元素以确定其是否与指定的元素相等。

指定者：

接口 Collection<E> 中的 contains

参数：

o - 测试在此 collection 中是否存在的元素。

返回：

如果此 collection 包含指定的元素，则返回 true

抛出：

ClassCastException - 如果指定元素的类型与此 collection 不兼容（可选）。

NullPointerException - 如果指定的元素为 null，并且此 collection 不允许 null 元素（可选）。

toArray

public Object[] toArray()

返回包含此 collection 中所有元素的数组。如果 collection 对其迭代器返回的元素顺序做出了某些保证，那么此方法必须以相同的顺序返回这些元素。

返回的数组将是“安全的”，因为此 collection 并不维护对返回数组的任何引用。（换句话说，即使 collection 受到数组的支持，此方法也必须分配一个新的数组）。因此，调用者可以随意修改返回的数组。

此方法充当了基于数组的 API 与基于 collection 的 API 之间的桥梁。

此实现返回一个数组，它包含此 collection 的迭代器返回的所有元素，这些元素的排列顺序与数组的连续元素存储顺序相同，都是从索引 0 开始。返回数组的长度等于迭代器返回的元素数，即使此 collection 的大小发生更改也是如此，这种情况可能发生在 collection 允许在迭代期间进行并发修改时。size 方法只是作为一个优化提示被调用；即使迭代器返回不同的元素数，也会返回正确的结果。

此方法等效于：

 List<E> list = new ArrayList<E>(size());
 for (E e : this)
     list.add(e);
 return list.toArray();
 

指定者：

接口 Collection<E> 中的 toArray

返回：

包含此 collection 中所有元素的数组

toArray

public <T> T[] toArray(T[] a)

返回包含此 collection 中所有元素的数组；返回数组的运行时类型与指定数组的运行时类型相同。如果指定的数组能容纳该 collection，则返回包含此 collection 元素的数组。否则，将分配一个具有指定数组的运行时类型和此 collection 大小的新数组。

如果指定的数组能容纳 collection，并有剩余空间（即数组的元素比 collection 的元素多），那么会将数组中紧接 collection 尾部的元素设置为 null。（只有 在调用者知道此 collection 没有包含任何 null 元素时才能用此方法确定 collection 的长度。）

如果此 collection 对其迭代器返回的元素顺序做出了某些保证，那么此方法必须以相同的顺序返回这些元素。

像 Collection.toArray() 方法一样，此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。更进一步说，此方法允许对输出数组的运行时类型进行精确控制，并且在某些情况下，可以用来节省分配开销。

假定 x 是只包含字符串的一个已知 collection。以下代码用来将 collection 转储到一个新分配的 String 数组：

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

注意， toArray(new Object[0]) 和 toArray() 在功能上是相同的。

此实现返回一个数组，它包含此 collection 的迭代器返回的所有元素，这些元素的排列顺序与数组的连续元素存储顺序相同，都是从索引 0 开始。如果迭代器返回的元素数太大，不适合指定数组，则在新分配的数组中返回这些元素，该数组的长度等于迭代器返回的元素数，即使此 collection 的大小在进行迭代期间发生更改也是如此，这种情况可能发生在 collection 允许在迭代期间进行并发修改时。size 方法只是作为一个优化提示被调用；即使迭代器返回不同的元素数，也会返回正确的结果。

此方法等效于：

 List<E> list = new ArrayList<E>(size());
 for (E e : this)
     list.add(e);
 return list.toArray(a);
 

指定者：

接口 Collection<E> 中的 toArray

参数：

a - 存储此 collection 元素的数组（如果其足够大）；否则，将为此分配一个具有相同运行时类型的新数组。

返回：

包含此 collection 中所有元素的数组

抛出：

ArrayStoreException - 如果指定数组的运行时类型不是此 collection 每个元素运行时类型的超类型

NullPointerException - 如果指定的数组为 null

add

public boolean add(E e)

确保此 collection 包含指定的元素（可选操作）。如果此 collection 由于调用而发生更改，则返回 true。（如果此 collection 不允许有重复元素，并且已经包含了指定的元素，则返回 false。）

支持此操作的 collection 可以限制哪些元素能添加到此 collection 中来。需要特别指出的是，一些 collection 拒绝添加 null 元素，其他一些 collection 将对可以添加的元素类型强加限制。Collection 类应该在其文档中清楚地指定能添加哪些元素方面的所有限制。

如果 collection 由于某些原因（已经包含该元素的原因除外）拒绝添加特定的元素，那么它必须 抛出一个异常（而不是返回 false）。这确保了在此调用返回后，collection 总是包含指定的元素。

此实现总是抛出一个 UnsupportedOperationException。

指定者：

接口 Collection<E> 中的 add

参数：

e - 确定此 collection 中是否存在的元素。

返回：

如果此 collection 由于调用而发生更改，则返回 true

抛出：

UnsupportedOperationException - 如果此 collection 不支持 add 操作

ClassCastException - 如果指定元素的类不允许它添加到此 collection 中

NullPointerException - 如果指定的元素为 null，并且此 collection 不允许 null 元素

IllegalArgumentException - 如果元素的某属性不允许它添加到此 collection 中

IllegalStateException - 如果由于插入限制，元素不能在此时间添加

remove

public boolean remove(Object o)

从此 collection 中移除指定元素的单个实例，如果存在的话（可选操作）。更确切地讲，如果此 collection 包含一个或多个满足 (o==null ? e==null : o.equals(e)) 的元素 e，则移除这样的元素。如果此 collection 包含指定的元素（或者此 collection 由于调用而发生更改），则返回 true 。

此实现在该 collection 上进行迭代，查找指定的元素。如果找到该元素，那么它会使用迭代器的 remove 方法从该 collection 中移除该元素。

注意，如果此 collection 的 iterator 方法所返回的迭代器无法实现 remove 方法，并且此 collection 包含指定的对象，那么此实现将抛出 UnsupportedOperationException。

指定者：

接口 Collection<E> 中的 remove

参数：

o - 要从此 collection 中移除的元素（如果存在）。

返回：

如果此调用将移除一个元素，则返回 true

抛出：

UnsupportedOperationException - 如果此 collection 不支持 remove 操作

ClassCastException - 如果指定元素的类型与此 collection 不兼容（可选）

NullPointerException - 如果指定的元素为 null，并且此 collection 不允许 null 元素（可选）。

containsAll

public boolean containsAll(Collection<?> c)

如果此 collection 包含指定 collection 中的所有元素，则返回 true。

此实现在指定的 collection 上进行迭代，依次检查该迭代器返回的每个元素，查看其是否包含在此 collection 中。如果是，则返回 true；否则返回 false。

指定者：

接口 Collection<E> 中的 containsAll

参数：

c - 将检查是否包含在此 collection 中的 collection

返回：

如果此 collection 包含指定 collection 中的所有元素，则返回 true

抛出：

ClassCastException - 如果指定 collection 中有一个或多个元素的类型与此 collection 不兼容（可选）

NullPointerException - 如果指定 collection 包含一个或多个 null 元素，并且此 collection 不允许 null 元素（可选），或者指定的 collection 为 null

另请参见：

contains(Object)

addAll

public boolean addAll(Collection<? extends E> c)

将指定 collection 中的所有元素都添加到此 collection 中（可选操作）。如果在进行此操作的同时修改指定的 collection，那么此操作行为是不确定的。（这意味着如果指定的 collection 是此 collection，并且此 collection 为非空，那么此调用的行为是不确定的。）

此实现在指定的 collection 上进行迭代，并依次将迭代器返回的每个对象添加到此 collection 中。

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

指定者：

接口 Collection<E> 中的 addAll

参数：

c - 包含要添加到此 collection 的元素的 collection

返回：

如果此 collection 由于调用而发生更改，则返回 true

抛出：

UnsupportedOperationException - 如果此 collection 不支持 addAll 方法

ClassCastException - 如果指定 collection 中某个元素的类不允许它添加到此 collection 中

NullPointerException - 如果指定 collection 包含 null 元素，并且此 collection 不支持 null 元素，或者指定的 collection 为 null

IllegalArgumentException - 如果指定 collection 的元素的某属性不允许它添加到此 collection 中

IllegalStateException - 如果由于插入限制，不是所有的元素都能在此时间添加

另请参见：

add(Object)

removeAll

public boolean removeAll(Collection<?> c)

移除此 collection 中那些也包含在指定 collection 中的所有元素（可选操作）。此调用返回后，collection 中将不包含任何与指定 collection 相同的元素。

此实现在此 collection 上进行迭代，依次检查该迭代器返回的每个元素，以查看其是否包含在指定的 collection 中。如果是，则使用迭代器的 remove 方法将其从此 collection 中移除。

注意，如果 iterator 方法返回的迭代器无法实现 remove 方法，并且此 collection 包含一个或多个与指定 collection 共有的元素，那么此实现将抛出 UnsupportedOperationException。

指定者：

接口 Collection<E> 中的 removeAll

参数：

c - 办好要从此 collection 移除的元素的 collection

返回：

如果此 collection 由于调用而发生更改，则返回 true

抛出：

UnsupportedOperationException - 如果此 collection 不支持 removeAll 方法

ClassCastException - 如果此 collection 中一个或多个元素的类型与指定 collection 不兼容（可选）

NullPointerException - 如果此 collection 包含一个或多个 null 元素，并且指定的 collection 不支持 null 元素（可选），或者指定的 collection 为 null

另请参见：

remove(Object), contains(Object)

retainAll

public boolean retainAll(Collection<?> c)

仅保留此 collection 中那些也包含在指定 collection 的元素（可选操作）。换句话说，移除此 collection 中未包含在指定 collection 中的所有元素。

此实现在此 collection 上进行迭代，依次检查该迭代器返回的每个元素，以查看其是否包含在指定的 collection 中。如果不是，则使用迭代器的 remove 方法将其从此 collection 中移除。

注意，如果 iterator 方法返回的迭代器无法实现 remove 方法，并且此 collection 包含一个或多个在指定 collection 中不存在的元素，那么此实现将抛出 UnsupportedOperationException。

指定者：

接口 Collection<E> 中的 retainAll

参数：

c - 包含保留在此 collection 中的元素的 collection

返回：

如果此 collection 由于调用而发生更改，则返回 true

抛出：

UnsupportedOperationException - 如果此 collection 不支持 retainAll 操作

ClassCastException - 如果此 collection 中一个或多个元素的类型与指定 collection 不兼容（可选）

NullPointerException - 如果此 collection 包含一个或多个 null 元素，并且指定的 collection 不允许 null 元素（可选），或者指定的 collection 为 null

另请参见：

remove(Object), contains(Object)

clear

public void clear()

移除此 collection 中的所有元素（可选操作）。此方法返回后，除非抛出一个异常。

此实现在此 collection 上进行迭代，并使用 Iterator.remove 操作移除每个元素。为了提高效率，多数实现可能会选择重写此方法。

注意，如果此 collection 的 iterator 方法所返回的迭代器无法实现 remove 方法，并且此 collection 非空，那么此实现将抛出 UnsupportedOperationException。

指定者：

接口 Collection<E> 中的 clear

抛出：

UnsupportedOperationException - 如果此 collection 不支持 clear 操作

toString

public String toString()

返回此 collection 的字符串表示形式。该字符串表示形式由 collection 元素的列表组成，这些元素按其迭代器返回的顺序排列，并用方括号 ( "[]") 括起来。相邻元素由字符 ", "（逗号加空格）分隔。通过 String.valueOf(Object) 可以将元素转换成字符串。

覆盖：

类 Object 中的 toString

返回：

此 collection 的字符串表示形式