java.util
介面 Queue<E>

型別參數：

E - collection 中所保存元素的型別。

所有父級介面：

Collection<E>, Iterable<E>

所有已知子介面：

BlockingDeque<E>, BlockingQueue<E>, Deque<E>

所有已知實作類別：

AbstractQueue, ArrayBlockingQueue, ArrayDeque, ConcurrentLinkedQueue, DelayQueue, LinkedBlockingDeque, LinkedBlockingQueue, LinkedList, PriorityBlockingQueue, PriorityQueue, SynchronousQueue

public interface Queue<E>
extends Collection<E>

在處理元素前用於保存元素的 collection。除了基本的 Collection 操作外，佇列還提供其他的插入、提取和檢查操作。每個方法都存在兩種形式：一種拋出異常（操作失敗時），另一種返回一個特殊值（null 或 false，具體取決於操作）。插入操作的後一種形式是用於專門為有容量限制的 Queue 實作設計的；在大多數實作中，插入操作不會失敗。

	拋出異常	返回特殊值
插入	add(e)	offer(e)
移除	remove()	poll()
檢查	element()	peek()

佇列通常（但並非一定）以 FIFO（先進先出）的方式排序各個元素。不過優先級佇列和 LIFO 佇列（或堆疊(stack)空間）例外，前者根據提供的比較器或元素的自然順序對元素進行排序，後者按 LIFO（後進先出）的方式對元素進行排序。無論使用哪種排序方式，佇列的頭 都是調用 remove() 或 poll() 所移除的元素。在 FIFO 佇列中，所有的新元素都插入佇列的末尾。其他種類別的佇列可能使用不同的元素放置規則。每個 Queue 實作必須指定其順序屬性。

如果可能，offer 方法可插入一個元素，否則返回 false。這與 Collection.add 方法不同，該方法只能通過拋出未經檢查的異常使添加元素失敗。offer 方法設計用於正常的失敗情況，而不是出現異常的情況，例如在容量固定（有界）的佇列中。

remove() 和 poll() 方法可移除和返回佇列的頭。到底從佇列中移除哪個元素是佇列排序策略的功能，而該策略在各種實作中是不同的。remove() 和 poll() 方法僅在佇列為空時其行為有所不同：remove() 方法拋出一個異常，而 poll() 方法則返回 null。

element() 和 peek() 返回，但不移除，佇列的頭。

Queue 介面並未定義阻塞佇列的方法，而這在共時程式中是很常見的。BlockingQueue 介面定義了那些等待元素出現或等待佇列中有可用空間的方法，這些方法擴展了此介面。

Queue 實作通常不允許插入 null 元素，儘管某些實作（如 LinkedList）並不禁止插入 null。即使在允許 null 的實作中，也不應該將 null 插入到 Queue 中，因為 null 也用作 poll 方法的一個特殊返回值，表明佇列不包含元素。

Queue 實作通常未定義 equals 和 hashCode 方法的基於元素的版本，而是從 Object 類別繼承了基於身份的版本，因為對於具有相同元素但有不同排序屬性的佇列而言，基於元素的相等性並非總是定義良好的。

此介面是 Java Collections Framework 的成員。

從以下版本開始：

1.5

另請參見：

Collection, LinkedList, PriorityQueue, LinkedBlockingQueue, BlockingQueue, ArrayBlockingQueue, LinkedBlockingQueue, PriorityBlockingQueue

方法摘要

boolean	add(E e) 將指定的元素插入此佇列（如果立即可行且不會違反容量限制），在成功時返回 true，如果當前沒有可用的空間，則拋出 IllegalStateException。
E	element() 獲取，但是不移除此佇列的頭。
boolean	offer(E e) 將指定的元素插入此佇列（如果立即可行且不會違反容量限制），當使用有容量限制的佇列時，此方法通常要優於 add(E)，後者可能無法插入元素，而只是拋出一個異常。
E	peek() 獲取但不移除此佇列的頭；如果此佇列為空，則返回 null。
E	poll() 獲取並移除此佇列的頭，如果此佇列為空，則返回 null。
E	remove() 獲取並移除此佇列的頭。

從介面 java.util.Collection 繼承的方法

addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

方法詳細資訊

add

boolean add(E e)

將指定的元素插入此佇列（如果立即可行且不會違反容量限制），在成功時返回 true，如果當前沒有可用的空間，則拋出 IllegalStateException。

指定者：

介面 Collection<E> 中的 add

參數：

e - 要添加的元素

返回：

true（根據 Collection.add(E) 的規定）

拋出：

IllegalStateException - 如果由於容量的限制此時不能添加該元素

ClassCastException - 如果指定元素的類別不允許將其添加到此佇列

NullPointerException - 如果指定元素為 null 並且此佇列不允許 null 元素

IllegalArgumentException - 如果此元素的某些屬性不允許將其添加到此佇列

offer

boolean offer(E e)

將指定的元素插入此佇列（如果立即可行且不會違反容量限制），當使用有容量限制的佇列時，此方法通常要優於 add(E)，後者可能無法插入元素，而只是拋出一個異常。

參數：

e - 要添加的元素

返回：

如果該元素已添加到此佇列，則返回 true；否則返回 false

拋出：

ClassCastException - 如果指定元素的類別不允許將其添加到此佇列

NullPointerException - 如果指定元素為 null 並且此佇列不允許 null 元素

IllegalArgumentException - 如果此元素的某些屬性不允許將其添加到此佇列

remove

E remove()

獲取並移除此佇列的頭。此方法與 poll 唯一的不同在於：此佇列為空時將拋出一個異常。

返回：

佇列的頭

拋出：

NoSuchElementException - 如果此佇列為空

poll

E poll()

獲取並移除此佇列的頭，如果此佇列為空，則返回 null。

返回：

佇列的頭，如果此佇列為空，則返回 null

element

E element()

獲取，但是不移除此佇列的頭。此方法與 peek 唯一的不同在於：此佇列為空時將拋出一個異常。

返回：

佇列的頭

拋出：

NoSuchElementException - 如果此佇列為空

peek

E peek()

獲取但不移除此佇列的頭；如果此佇列為空，則返回 null。

返回：

此佇列的頭；如果此佇列為空，則返回 null