java.util
介面 Collection<E>

所有父級介面：

Iterable<E>

所有已知子介面：

BeanContext, BeanContextServices, BlockingDeque<E>, BlockingQueue<E>, Deque<E>, List<E>, NavigableSet<E>, Queue<E>, Set<E>, SortedSet<E>

所有已知實作類別：

AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayBlockingQueue, ArrayDeque, ArrayList, AttributeList, BeanContextServicesSupport, BeanContextSupport, ConcurrentLinkedQueue, ConcurrentSkipListSet, CopyOnWriteArrayList, CopyOnWriteArraySet, DelayQueue, EnumSet, HashSet, JobStateReasons, LinkedBlockingDeque, 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 中，將可能拋出一個異常，也可能操作成功，這取決於實作本身。這樣的異常在此介面的規範中標記為「可選」。

由每個 collection 來確定其自身的同步策略。在沒有實作的強烈保證的情況下，調用由另一進程正在更改的 collection 的方法可能會出現不確定行為；這包括直接調用，將 collection 傳遞給可能執行調用的方法，以及使用現有迭代器檢查 collection。

Collections Framework 介面中的很多方法是根據 equals 方法定義的。例如，contains(Object o) 方法的規範宣告：“當且僅當此 collection 套件含至少一個滿足 (o==null ? e==null :o.equals(e)) 的元素 e 時，返回 true。”不 應將此規範理解為它暗指調用具有非空(null)參數 o 的 Collection.contains 方法會導致為任意的 e 元素調用 o.equals(e) 方法。可隨意對各種實作執行優化，只要避免調用 equals 即可，例如，通過首先比較兩個元素的雜湊碼。（Object.hashCode() 規範保證雜湊碼不相等的兩個物件不會相等）。較為常見的是，各種 Collections Framework 介面的實作可隨意利用底層 Object 方法的指定行為，而不管實作程序認為它是否合適。

此介面是 Java Collections Framework 的一個成員。

從以下版本開始：

1.2

另請參見：

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

方法摘要

boolean	add(E e) 確保此 collection 套件含指定的元素（可選操作）。
boolean	addAll(Collection<? extends E> c) 將指定 collection 中的所有元素都添加到此 collection 中（可選操作）。
void	clear() 移除此 collection 中的所有元素（可選操作）。
boolean	contains(Object o) 如果此 collection 套件含指定的元素，則返回 true。
boolean	containsAll(Collection<?> c) 如果此 collection 套件含指定 collection 中的所有元素，則返回 true。
boolean	equals(Object o) 比較此 collection 與指定物件是否相等。
int	hashCode() 返回此 collection 的雜湊碼值。
boolean	isEmpty() 如果此 collection 不包含元素，則返回 true。
Iterator<E>	iterator() 返回在此 collection 的元素上進行迭代的迭代器。
boolean	remove(Object o) 從此 collection 中移除指定元素的單個實例，如果存在的話（可選操作）。
boolean	removeAll(Collection<?> c) 移除此 collection 中那些也包含在指定 collection 中的所有元素（可選操作）。
boolean	retainAll(Collection<?> c) 僅保留此 collection 中那些也包含在指定 collection 的元素（可選操作）。
int	size() 返回此 collection 中的元素數。
Object[]	toArray() 返回包含此 collection 中所有元素的陣列。
<T> T[]	toArray(T[] a) 返回包含此 collection 中所有元素的陣列；返回陣列的運行時型別與指定陣列的運行時型別相同。

方法詳細資訊

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 沒有包含任何 null 元素時才能用此方法確定 collection 的長度。）

如果此 collection 對其迭代器返回的元素順序做出了某些保證，那麼此方法必須以相同的順序返回這些元素。

像 toArray() 方法一樣，此方法充當基於陣列的 API 與基於 collection 的 API 之間的橋樑。更進一步說，此方法允許對輸出陣列的運行時型別進行精確控制，並且在某些情況下，可以用來節省分派開銷。

假定 x 是只包含字元串的一個已知 collection。以下程式碼用來將 collection 轉儲到一個新分派的 String 陣列：

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

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

參數：

a - 存儲此 collection 元素的陣列（如果其足夠大）；否則，將為此分派一個具有相同運行時型別的新陣列。

返回：

包含此 collection 中所有元素的陣列

拋出：

ArrayStoreException - 如果指定陣列的運行時型別不是此 collection 每個元素運行時型別的父級類別型

NullPointerException - 如果指定的陣列為 null

add

boolean add(E e)

確保此 collection 套件含指定的元素（可選操作）。如果此 collection 由於調用而發生更改，則返回 true。（如果此 collection 不允許有重複元素，並且已經包含了指定的元素，則返回 false。）

支持此操作的 collection 可以限制哪些元素能添加到此 collection 中來。需要特別指出的是，一些 collection 拒絕添加 null 元素，其他一些 collection 將對可以添加的元素型別強加限制。Collection 類別應該在其文檔中清楚地指定能添加哪些元素方面的所有限制。

如果 collection 由於某些原因（已經包含該元素的原因除外）拒絕添加特定的元素，那麼它必須 拋出一個異常（而不是返回 false）。這確保了在此調用返回後，collection 總是包含指定的元素。

參數：

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

返回：

如果此 collection 由於調用而發生更改，則返回 true

拋出：

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

ClassCastException - 如果指定元素的類別不允許它添加到此 collection 中

NullPointerException - 如果指定的元素為 null，並且此 collection 不允許 null 元素

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

IllegalStateException - 如果由於插入限制，元素不能在此時間添加

remove

boolean remove(Object o)

從此 collection 中移除指定元素的單個實例，如果存在的話（可選操作）。更確切地講，如果此 collection 套件含一個或多個滿足 (o==null ? e==null : o.equals(e)) 的元素 e，則移除這樣的元素。如果此 collection 套件含指定的元素（或者此 collection 由於調用而發生更改），則返回 true 。

參數：

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

返回：

如果此調用將移除一個元素，則返回 true

拋出：

ClassCastException - 如果指定元素的型別與此 collection 不相容（可選）

NullPointerException - 如果指定的元素為 null，並且此 collection 不允許 null 元素（可選）。

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

containsAll

boolean containsAll(Collection<?> c)

如果此 collection 套件含指定 collection 中的所有元素，則返回 true。

參數：

c - 將檢查是否包含在此 collection 中的 collection

返回：

如果此 collection 套件含指定 collection 中的所有元素，則返回 true

拋出：

ClassCastException - 如果指定 collection 中有一個或多個元素的型別與此 collection 不相容（可選）

NullPointerException - 如果指定 collection 套件含一個或多個 null 元素，並且此 collection 不允許 null 元素（可選），或者指定的 collection 為 null

另請參見：

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

將指定 collection 中的所有元素都添加到此 collection 中（可選操作）。如果在進行此操作的同時修改指定的 collection，那麼此操作行為是不確定的。（這意味著如果指定的 collection 是此 collection，並且此 collection 為非空(null)，那麼此調用的行為是不確定的。）

參數：

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

boolean removeAll(Collection<?> c)

移除此 collection 中那些也包含在指定 collection 中的所有元素（可選操作）。此調用返回後，collection 中將不包含任何與指定 collection 相同的元素。

參數：

c - 辦好要從此 collection 移除的元素的 collection

返回：

如果此 collection 由於調用而發生更改，則返回 true

拋出：

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

ClassCastException - 如果此 collection 中一個或多個元素的型別與指定 collection 不相容（可選）

NullPointerException - 如果此 collection 套件含一個或多個 null 元素，並且指定的 collection 不支持 null 元素（可選），或者指定的 collection 為 null

另請參見：

remove(Object), contains(Object)

retainAll

boolean retainAll(Collection<?> c)

僅保留此 collection 中那些也包含在指定 collection 的元素（可選操作）。換句話說，移除此 collection 中未包含在指定 collection 中的所有元素。

參數：

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

返回：

如果此 collection 由於調用而發生更改，則返回 true

拋出：

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

ClassCastException - 如果此 collection 中一個或多個元素的型別與指定 collection 不相容（可選）

NullPointerException - 如果此 collection 套件含一個或多個 null 元素，並且指定的 collection 不允許 null 元素（可選），或者指定的 collection 為 null

另請參見：

remove(Object), contains(Object)

clear

void clear()

移除此 collection 中的所有元素（可選操作）。此方法返回後，除非拋出一個異常。

拋出：

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

equals

boolean equals(Object o)

比較此 collection 與指定物件是否相等。

當 Collection 介面沒有對 Object.equals 的常規協定添加任何約定時，「直接」實作該 Collection 介面（換句話說，創建一個 Collection，但它不是 Set 或 List 的類別）的開發人員選擇覆寫 Object.equals 方法時必須小心。沒必要這樣做，最簡單的方案是依靠 Object 的實作，然而實作者可能希望實作“值比較”，而不是預設的“參考比較”。（List 和 Set 介面要求進行這樣的值比較。）

Object.equals 方法的常規協定聲稱相等必須是對稱的（換句話說，當且僅當存在 b.equals(a) 時，才存在 a.equals(b)）。List.equals 和 Set.equals 的協定聲稱列表只能與列表相等，set 只能與 set 相等。因此，對於一個既不實作 List 又不實作 Set 介面的 collection 類別，當將此 collection 與任何列表或 set 進行比較時，常規的 equals 方法必須返回 false。（按照相同的邏輯，不可能編寫一個同時正確實作 Set 和 List 介面的類別。）

覆寫：

類別 Object 中的 equals

參數：

o - 要與此 collection 進行相等性比較的物件。

返回：

如果指定對象與此 collection 相等，則返回 true

另請參見：

Object.equals(Object), Set.equals(Object), List.equals(Object)

hashCode

int hashCode()

返回此 collection 的雜湊碼值。當 Collection 介面沒有為 Object.hashCode 方法的常規協定添加任何約束時，為了滿足 Object.hashCode 方法的常規協定，開發人員應該注意任何覆寫 Object.equals 方法的類別必須覆寫 Object.hashCode 方法。需要特別指出的是，c1.equals(c2) 暗示著 c1.hashCode()==c2.hashCode()。

覆寫：

類別 Object 中的 hashCode

返回：

此 collection 的雜湊碼值

另請參見：

Object.hashCode(), Object.equals(Object)