[/url] [url=file:///F:/资料/文字资料/j2sdk-1_4_2-doc/docs/api/overview-summary.html]Overview
Class
JavaTM 2 Platform
Std. Ed. v1.4.2
PREV CLASS NEXT CLASS
SUMMARY: NESTED | FIELD | CONSTR | METHOD
DETAIL: FIELD | CONSTR | METHOD
java.util
Interface CollectionAll Known Subinterfaces: BeanContext, BeanContextServices, List, Set, SortedSet All Known Implementing Classes: AbstractCollection, AbstractList, AbstractSet, ArrayList, BeanContextServicesSupport, BeanContextSupport, HashSet, LinkedHashSet, LinkedList, TreeSet, Vector public interface CollectionThe root interface in the collection hierarchy. A collection represents a group of objects, known as its elements. Some collections allow duplicate elements and others do not. Some are ordered and others unordered. The SDK does not provide any direct implementations of this interface: it provides implementations of more specific subinterfaces like Set and List. This interface is typically used to pass collections around and manipulate them where maximum generality is desired. 集合层级的根接口。集合表示一组对象，称为元素。某些集合允许重复的元素，而某些不行。某些是有序的而某些无序。SDK并没有提供该接口的直接实现。它提供了更具体的子接口比如Set和List的实现。该接口通常用于传递集合参数，可以实现最大的通用性。
Bags or multisets (unordered collections that may contain duplicate elements) should implement this interface directly. 包或者多集合（无序集合，可以包含重复元素）应该直接实现该接口。
All general-purpose Collection implementation classes (which typically implement Collection indirectly through one of its subinterfaces) should provide two "standard" constructors: a void (no arguments) constructor, which creates an empty collection, and a constructor with a single argument of type Collection, which creates a new collection with the same elements as its argument. In effect, the latter constructor allows the user to copy any collection, producing an equivalent collection of the desired implementation type. There is no way to enforce this convention (as interfaces cannot contain constructors) but all of the general-purpose Collection implementations in the Java platform libraries comply. 所有一般目的的Collection实现类（通常通过它的子类间接实现Collection） 应该提供两个标准构造函数：一个不含参数的空构造函数，创建一个空集合， 一个单Collection类型参数的构造函数，使用和参数相同的元素创建一个新集合。 实际上，后者允许用户拷贝任何集合来生成一个和期待实现类型相等的集合。 虽然没有办法来强制执行（因为接口不含构造函数）但是Java平台库中的所有一般 的Collection实现均是如此。
The "destructive" methods contained in this interface, that is, the methods that modify the collection on which they operate, are specified to throw UnsupportedOperationException if this collection does not support the operation. If this is the case, these methods may, but are not required to, throw an UnsupportedOperationException if the invocation would have no effect on the collection. For example, invoking the addAll(Collection) method on an unmodifiable collection may, but is not required to, throw the exception if the collection to be added is empty. 该接口包含了一些破坏性的方法，操作的时候修改集合，如果集合不支持这些操作， 规定应该抛出UnsupportedOperationException。如果调用对集合没影响，在这种情况下， 这些方法可以抛出UnsupportedOperationException，但不必须。例如对于一个不可更新的 集合调用addAll(Collection)，而如果要被添加的集合是空的，可以抛出该异常，但不是必须。
Some collection implementations have restrictions on the elements that they may contain. For example, some implementations prohibit null elements, and some have restrictions on the types of their elements. Attempting to add an ineligible element throws an unchecked exception, typically NullPointerException or ClassCastException. Attempting to query the presence of an ineligible element may throw an exception, or it may simply return false; some implementations will exhibit the former behavior and some will exhibit the latter. More generally, attempting an operation on an ineligible element whose completion would not result in the insertion of an ineligible element into the collection may throw an exception or it may succeed, at the option of the implementation. Such exceptions are marked as "optional" in the specification for this interface. 某些集合实现对其包含的元素有限制。比如，某些实现禁止null元素，某些对元素的类型有限制。试图插入一个不合适的元素将抛出非检查异常，通常为NullPointerException或 ClassCastException。试图查询一个不合适的元素可以抛出异常，也可以简单返回false。某些实现表现为前者，某些表现为后者。更一般地讲，试图操作一个不适当的元素，实现不会造成不适当元素插入集合而抛出异常或者成功，这取决于实现的选择。那样的异常在该接口规范中标记为“optional”。
This interface is a member of the Java Collections Framework. 该接口是Java集合框架成员之一。
Since: 1.2 See Also: Set, List, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays, AbstractCollectionMethod Summary
boolean
Ensures that this collection contains the specified element (optional operation). 确保集合包含指定元素（可选操作）。
boolean
addAll(Collection c)
Adds all of the elements in the specified collection to this collection (optional operation). 向集合添加指定集合的所有元素（可选操作）。
void
clear()
Removes all of the elements from this collection (optional operation). 从集合中删除所有元素（可选操作）。
boolean
Returns true if this collection contains the specified element. 如果集合包含指定元素，返回true。
boolean
Returns true if this collection contains all of the elements in the specified collection. 如果集合包含指定集合的所有元素，返回true。
boolean
Compares the specified object with this collection for equality. 将指定对象与集合比较相等性。
int
hashCode()
Returns the hash code value for this collection. 返回集合的哈希码值。
boolean
isEmpty()
Returns true if this collection contains no elements. 如果集合不含元素，返回true。
iterator()
Returns an iterator over the elements in this collection. 返回集合元素的迭代器。
boolean
Removes a single instance of the specified element from this collection, if it is present (optional operation). 删除集合中指定元素的一个实例，若有的话（可选操作）。
boolean
Removes all this collection's elements that are also contained in the specified collection (optional operation). 从当前集合中删除指定集合所含的所有元素（可选操作）。
boolean
Retains only the elements in this collection that are contained in the specified collection (optional operation). 只在当前集合中保留指定集合所含的所有元素（可选操作）。
int
size()
Returns the number of elements in this collection. 返回集合的元素数目。
Object[]
toArray()
Returns an array containing all of the elements in this collection. 返回包含集合所有元素的数组。
Object[]
Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. 返回包含集合所有元素的数组，返回数组的运行时类型由指定数组的运行时类型决定。
Method Detail
sizepublic int size()
Returns the number of elements in this collection. If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE. 返回集合的元素数目。如果集合包含的元素超过了Integer.MAX_VALUE，返回Integer.MAX_VALUE。
Returns: the number of elements in this collection 集合的元素数目isEmptypublic boolean isEmpty()
Returns true if this collection contains no elements. 如果集合不含元素，返回true。
Returns: true if this collection contains no elements 如果集合不含元素，返回truecontainspublic boolean contains(Object o)
Returns true if this collection contains the specified element. More formally, returns true if and only if this collection contains at least one element e such that (o==null ? e==null : o.equals(e)). 如果集合包含指定元素，返回true。正式表述为，只有当集合包含至少一个元素e，使得 (o==null ? e==null : o.equals(e))，返回true。
Parameters: o - element whose presence in this collection is to be tested. 用来测试集合中是否存在的元素。 Returns: true if this collection contains the specified element 如果集合包含指定元素，返回true Throws: ClassCastException - if the type of the specified element is incompatible with this collection (optional). 如果指定元素的类型与集合不相容时抛出（可选）。 NullPointerException - if the specified element is null and this collection does not support null elements (optional). 如果指定元素为null而集合不支持null元素时抛出（可选）。iteratorpublic Iterator iterator()
Returns an iterator over the elements in this collection. There are no guarantees concerning the order in which the elements are returned (unless this collection is an instance of some class that provides a guarantee). 返回集合元素的迭代器。不保证元素返回的顺序（除非集合实例所在的类提供了该保证）。
Returns: an Iterator over the elements in this collection 集合元素的迭代器toArraypublic Object[] toArray()
Returns an array containing all of the elements in this collection. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. 返回包含集合所有元素的数组。如果集合保证它所含元素的顺序为迭代器的顺序， 那么方法必须以相同顺序返回元素。 The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array. 返回的数组是安全的，集合中不会维持对其的引用。（换句话说，即使集合是由数组 得到的，方法也必须创建一个新的数组。）调用者因此可以对返回数组进行修改。
This method acts as bridge between array-based and collection-based APIs. 该方法作为基于数组和基于集合API之间的桥梁。
Returns: an array containing all of the elements in this collection 包含集合所有元素的数组toArraypublic Object[] toArray(Object[] a)
Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection. 返回包含集合所有元素的数组，返回数组的运行时类型由指定数组的运行时类型决定。 如果集合可以填入指定数组，直接返回。否则使用指定数组的运行时类型和当前集合 的大小创建一个新数组。 If this collection fits in the specified array with room to spare (i.e., the array has more elements than this collection), the element in the array immediately following the end of the collection is set to null. This is useful in determining the length of this collection only if the caller knows that this collection does not contain any null elements.) 如果当前集合填入指定数组，空间上还有剩余（也就是数组的元素比集合多）， 那么数组中紧随集合后的元素都被设为null。只有当调用者知道集合不包含null元素时，确定集合的长度才是有用的。
If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. 如果集合保证它所含元素的顺序为迭代器的顺序，那么方法必须以相同顺序返回元素。
Like the toArray method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs 和toArray方法一样，该方法作为基于数组和基于集合API之间的桥梁。 而且，该方法允许精确控制输出数组的运行时类型，某种情况下，用来节省创建开销。
Suppose l is a List known to contain only strings. The following code can be used to dump the list into a newly allocated array of String: 假定l是一个List，已知仅包含字符串。以下代码可以用来将列表数据填充至新创建的String数组。
String[] x = (String[]) v.toArray(new String[0]);
Note that toArray(new Object[0]) is identical in function to toArray(). 注意toArray(new Object[0])功能上和toArray()相同。
Parameters: a - the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose. 存储集合元素的数组，如果它足够大的话；否则为此创建一个运行时类型相同的新数组。 Returns: an array containing the elements of this collection 包含集合元素的数组 Throws: ArrayStoreException - the runtime type of the specified array is not a supertype of the runtime type of every element in this collection. 如果指定数组的运行时类型不是集合中每个元素运行时类型的父一级类型时抛出。 NullPointerException - if the specified array is null. 如果指定数组为null时抛出。addpublic boolean add(Object o)
Ensures that this collection contains the specified element (optional operation). Returns true if this collection changed as a result of the call. (Returns false if this collection does not permit duplicates and already contains the specified element.) 确保集合包含指定元素（可选操作）。如果集合因此而改变，返回true。 （如果集合以及包含了指定元素而不允许重复，返回false。） Collections that support this operation may place limitations on what elements may be added to this collection. In particular, some collections will refuse to add null elements, and others will impose restrictions on the type of elements that may be added. Collection classes should clearly specify in their documentation any restrictions on what elements may be added. 集合支持该操作对加入集合的元素进行限制。特别地，某些集合拒绝加入null元素， 其它一些对加入元素的类型强加限制。集合类应该在文档中明确指出对加入元素的限制。
If a collection refuses to add a particular element for any reason other than that it already contains the element, it must throw an exception (rather than returning false). This preserves the invariant that a collection always contains the specified element after this call returns. 如果集合因为某个理由拒绝加入一个特定元素，而不是因为它已经包含了该元素， 那么它必须抛出异常而不是返回false。这样才能保证调用正常返回后集合必定包含指定元素。
Parameters: o - element whose presence in this collection is to be ensured. 确保集合中存在的元素。 Returns: true if this collection changed as a result of the call 如果集合因调用而改变，返回true Throws: UnsupportedOperationException - add is not supported by this collection. 如果集合不支持add时抛出。 ClassCastException - class of the specified element prevents it from being added to this collection. 如果指定集合的元素类型阻止其加入集合时抛出。 NullPointerException - if the specified element is null and this collection does not support null elements. 如果指定元素为null而集合不支持null元素时抛出。 IllegalArgumentException - some aspect of this element prevents it from being added to this collection. 如果元素的某些方面不允许它加入当前集合则抛出。removepublic boolean remove(Object o)
Removes a single instance of the specified element from this collection, if it is present (optional operation). More formally, removes an element e such that (o==null ? e==null : o.equals(e)), if this collection contains one or more such elements. Returns true if this collection contained the specified element (or equivalently, if this collection changed as a result of the call). 删除集合中指定元素的一个实例，若有的话（可选操作）。正式表述为， 如果集合包含一个或多个元素e，使得(o==null ? e==null : o.equals(e))，那么删除 一个元素e。如果集合包含指定元素（等价于集合因调用而改变），返回true。
Parameters: o - element to be removed from this collection, if present. 要从集合中删除的元素，若有。 Returns: true if this collection changed as a result of the call 如果集合因调用而改变，返回true Throws: ClassCastException - if the type of the specified element is incompatible with this collection (optional). 如果指定元素的类型与集合不相容时抛出（可选）。 NullPointerException - if the specified element is null and this collection does not support null elements (optional). 如果指定元素为null而集合不支持null元素时抛出（可选）。 UnsupportedOperationException - remove is not supported by this collection. 如果集合不支持remove时抛出。containsAllpublic boolean containsAll(Collection c)
Returns true if this collection contains all of the elements in the specified collection. 如果集合包含指定集合的所有元素，返回true。
Parameters: c - collection to be checked for containment in this collection. 检查当前集合是否包含的集合。 Returns: true if this collection contains all of the elements in the specified collection 如果集合包含指定集合的所有元素，返回true Throws: ClassCastException - if the types of one or more elements in the specified collection are incompatible with this collection (optional). 如果指定集合的一个或多个元素的类型与集合不相容时抛出（可选）。 NullPointerException - if the specified collection contains one or more null elements and this collection does not support null elements (optional). 如果指定集合包含一个或多个null元素而当前集合不支持null元素时抛出（可选）。 NullPointerException - if the specified collection is null. 如果指定集合为null时抛出。 See Also: contains(Object)addAllpublic boolean addAll(Collection c)
Adds all of the elements in the specified collection to this collection (optional operation). The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this collection, and this collection is nonempty.) 向集合添加指定集合的所有元素（可选操作）。如果在该操作过程中指定集合被修改， 操作行为无法确定。 （这意味着如果指定集合为当前集合，当前集合不为空，那么 调用的行为无法确定。）
Parameters: c - elements to be inserted into this collection. 要被插如当前集合的元素。 Returns: true if this collection changed as a result of the call 如果集合因调用而改变，返回true Throws: UnsupportedOperationException - if this collection does not support the addAll method. 如果集合不支持addAll方法时抛出。 ClassCastException - if the class of an element of the specified collection prevents it from being added to this collection. 如果指定集合的某个元素类型阻止其加入集合时抛出。 NullPointerException - if the specified collection contains one or more null elements and this collection does not support null elements, or if the specified collection is null. 如果指定集合饱含一个或多个null元素而当前集合不支持null元素，或 指定集合为null时抛出（可选）。 IllegalArgumentException - some aspect of an element of the specified collection prevents it from being added to this collection. 如果指定集合的某个元素的某些方面不允许它加入当前集合则抛出。 See Also: add(Object)removeAllpublic boolean removeAll(Collection c)
Removes all this collection's elements that are also contained in the specified collection (optional operation). After this call returns, this collection will contain no elements in common with the specified collection. 从当前集合中删除指定集合所含的所有元素（可选操作）。调用返回后，集合将不包含 和指定集合中相同的元素。
Parameters: c - elements to be removed from this collection. 要从集合中删除的元素。 Returns: true if this collection changed as a result of the call 如果集合因调用而改变，返回true Throws: UnsupportedOperationException - if the removeAll method is not supported by this collection. 如果集合不支持removeAll方法时抛出。 ClassCastException - if the types of one or more elements in this collection are incompatible with the specified collection (optional). 如果指定集合的一个或多个元素的类型与集合不相容时抛出（可选）。 NullPointerException - if this collection contains one or more null elements and the specified collection does not support null elements (optional). 如果指定集合包含一个或多个null元素而当前集合不支持null元素时抛出（可选）。 NullPointerException - if the specified collection is null. 如果指定集合为null时抛出。 See Also: remove(Object), contains(Object)retainAllpublic boolean retainAll(Collection c)
Retains only the elements in this collection that are contained in the specified collection (optional operation). In other words, removes from this collection all of its elements that are not contained in the specified collection. 只在当前集合中保留指定集合所含的所有元素（可选操作）。换句话说，从当前集合中删除 指定集合中不含的所有元素。
Parameters: c - elements to be retained in this collection. 集合中要保留的元素。 Returns: true if this collection changed as a result of the call 如果集合因调用而改变，返回true Throws: UnsupportedOperationException - if the retainAll method is not supported by this Collection. 如果集合不支持retainAll方法时抛出。 ClassCastException - if the types of one or more elements in this collection are incompatible with the specified collection (optional). 如果指定集合的一个或多个元素的类型与集合不相容时抛出（可选）。 NullPointerException - if this collection contains one or more null elements and the specified collection does not support null elements (optional). 如果指定集合包含一个或多个null元素而当前集合不支持null元素时抛出（可选）。 NullPointerException - if the specified collection is null. 如果指定集合为null时抛出。 See Also: remove(Object), contains(Object)clearpublic void clear()
Removes all of the elements from this collection (optional operation). This collection will be empty after this method returns unless it throws an exception. 从集合中删除所有元素（可选操作）。方法返回后集合将为空除非抛出异常。
Throws: UnsupportedOperationException - if the clear method is not supported by this collection. 如果集合不支持clear方法时抛出。equalspublic boolean equals(Object o)
Compares the specified object with this collection for equality. 将指定对象与集合比较相等性。 While the Collection interface adds no stipulations to the general contract for the Object.equals, programmers who implement the Collection interface "directly" (in other words, create a class that is a Collection but is not a Set or a List) must exercise care if they choose to override the Object.equals. It is not necessary to do so, and the simplest course of action is to rely on Object's implementation, but the implementer may wish to implement a "value comparison" in place of the default "reference comparison." (The List and Set interfaces mandate such value comparisons.) 尽管Collection接口在Object.equals方法的一般约定之外，没有额外约定， 但是直接实现Collection接口（换句话说，创建一个Collection类而不是Set或List） 的程序员们应当注意是否需要重写Object.equals方法。如果不必这样做，最简单的办法 就是依赖于Object的实现，但是实现者们不要指望实现了“值比较”来代替默认的 “引用比较”。（List和Set接口要求值比较）
The general contract for the Object.equals method states that equals must be symmetric (in other words, a.equals(b) if and only if b.equals(a)). The contracts for List.equals and Set.equals state that lists are only equal to other lists, and sets to other sets. Thus, a custom equals method for a collection class that implements neither the List nor Set interface must return false when this collection is compared to any list or set. (By the same logic, it is not possible to write a class that correctly implements both the Set and List interfaces.) Object.equals方法一般约定equals必须是对称的。List.equals和Set.equals 约定为list只能等于其他list，set只能等于其他set。因此，对于没有实现List或Set接口的 collection类，当集合同任何list或set比较时，通常equals方法必须返回false。 （基于相同逻辑，同时正确实现Set和List接口的类是不可能的。）
Overrides: equals in class ObjectParameters: o - Object to be compared for equality with this collection. 同当前集合比较相等性的对象。 Returns: true if the specified object is equal to this collection 如果指定对象等于当前集合，返回true See Also: Object.equals(Object), Set.equals(Object), List.equals(Object)hashCodepublic int hashCode()
Returns the hash code value for this collection. While the Collection interface adds no stipulations to the general contract for the Object.hashCode method, programmers should take note that any class that overrides the Object.equals method must also override the Object.hashCode method in order to satisfy the general contract for the Object.hashCodemethod. In particular, c1.equals(c2) implies that c1.hashCode()==c2.hashCode(). 返回集合的哈希码值。尽管Collection接口在Object.hashCode方法的一般约定 之外，没有额外约定，但是程序员们应当注意任何重写Object.equals方法的类 必须同时重写Object.hashCode方法，以满足Object.hashCode方法的一般约定。 特别地，c1.equals(c2)意味着c1.hashCode()==c2.hashCode()。
Overrides: hashCode in class ObjectReturns: the hash code value for this collection 集合的哈希码值 See Also: Object.hashCode(), Object.equals(Object)[/url][url=file:///F:/资料/文字资料/j2sdk-1_4_2-doc/docs/api/overview-summary.html]Overview
Class
JavaTM 2 Platform
Std. Ed. v1.4.2
PREV CLASS NEXT CLASS
SUMMARY: NESTED | FIELD | CONSTR | METHOD
DETAIL: FIELD | CONSTR | METHOD
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples. Copyright 2003 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
