Java java.util 接口 Collection<E>（JDK5）

所有类

java.util
接口 Collection<E>

所有超级接口：

Iterable<E>

所有已知子接口：

BeanContext, BeanContextServices, BlockingQueue<E>, List<E>, Queue<E>, Set<E>, SortedSet<E>

所有已知实现类：

AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayBlockingQueue, ArrayList, AttributeList, BeanContextServicesSupport, BeanContextSupport, ConcurrentLinkedQueue, CopyOnWriteArrayList, CopyOnWriteArraySet, DelayQueue, EnumSet, HashSet, JobStateReasons, LinkedBlockingQueue, LinkedHashSet, LinkedList, PriorityBlockingQueue, PriorityQueue, RoleList, RoleUnresolvedList, Stack, SynchronousQueue, TreeSet, Vector

public interface Collection<E>
   
   
   
   
   
extends Iterable<E>
   
   
   
   
   

Collection 层次结构 中的根接口。Collection 表示一组对象，这些对象也称为 collection 的元素。一些 collection 允许有重复的元素，而另一些则不允许。一些 collection 是有序的，而另一些则是无序的。JDK 不提供此接口的任何直接 实现：它提供更具体的子接口（如 Set 和 List）实现。此接口通常用来传递 collection，并在需要最大普遍性的地方操作这些 collection。

包 (bag) 或多集合 (multiset)（可能包含重复元素的无序 collection）应该直接实现此接口。

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

此接口中包含的“破坏性”方法，是指可修改其所操作的 collection 的那些方法，如果此 collection 不支持该操作，则指定这些方法抛出 UnsupportedOperationException。如果是这样，那么在调用对该 collection 无效时，这些方法可能，但并不一定抛出 UnsupportedOperationException。例如，如果要添加的 collection 为空且不可修改，则对该 collection 调用 addAll(Collection) 方法时，可能但并不一定抛出异常。

一些 collection 实现对它们可能包含的元素有所限制。例如，某些实现禁止 null 元素，而某些实现则对元素的类型有限制。试图添加不合格的元素将抛出一个未经检查的异常，通常是 NullPointerException 或 ClassCastException。试图查询是否存在不合格的元素可能抛出一个异常，或者只是简单地返回 false；某些实现将表现出前一种行为，而某些实现则表现后一种。较为常见的是，试图对某个不合格的元素执行操作且该操作的完成不会导致将不合格的元素插入 collection 中，将可能抛出一个异常，也可能操作成功，这取决于实现本身。这样的异常在此接口的规范中标记为“可选”。

此接口是 Java Collections Framework 的成员。

Collections Framework 接口中的很多方法是根据 equals 方法定义的。例如，contains(Object o) 方法的规范声明：“当且仅当此 collection 包含至少一个满足 (o==null ? e==null :o.equals(e)) 的元素 e 时，才返回 true。”不 应将此规范理解为它暗指调用具有非空参数 o 的 Collection.contains 方法会导致为任意的 e 元素调用 o.equals(e) 方法。可随意对各种实现执行优化，只要避免调用 equals 即可，例如，通过首先比较两个元素的哈希码。（Object.hashCode() 规范保证哈希码不相等的两个对象不会相等）。较为常见的是，各种 Collections Framework 接口的实现可随意利用基础 Object 方法的指定行为，而不管实现程序认为它是否合适。

从以下版本开始：

1.2

另请参见：

Set, List, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays, AbstractCollection

size

int size()

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

返回：

此 collection 中的元素数

isEmpty

boolean isEmpty()

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

返回：

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

contains

boolean contains(Object o)

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

参数：

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

返回：

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

抛出：

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

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

iterator

Iterator<E> iterator()

返回在此 collection 的元素上进行迭代的迭代器。关于元素返回的顺序没有任何保证（除非此 collection 是某个能提供保证顺序的类实例）。

指定者：

接口 Iterable<E> 中的 iterator

返回：

在此 collection 的元素上进行迭代的 Iterator

toArray

Object[] toArray()

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

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

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

返回：

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

toArray

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

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

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

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

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

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

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

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

参数：

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

返回：

包含此 collection 元素的数组

抛出：

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

NullPointerException - 如果指定的数组为 null。

add

boolean add(E o)

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

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

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

参数：

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

返回：

如果此 collection 随调用的结果而发生改变，则返回 true

抛出：

UnsupportedOperationException - 此 collection 不支持 add 操作。

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

NullPointerException - 如果指定的元素为 null，并且此 collection 不支持 null 元素。

IllegalArgumentException - 此元素的某方面不允许它添加到此 collection 中。