java.util.concurrent
類別 DelayQueue<E extends Delayed>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractQueue<E>
          java.util.concurrent.DelayQueue<E>

型別參數：

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

所有已實作的介面：

Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>

public class DelayQueue<E extends Delayed>
extends AbstractQueue<E>
implements BlockingQueue<E>

Delayed 元素的一個無界阻塞佇列，只有在延遲期滿時才能從中提取元素。該佇列的頭部 是延遲期滿後保存時間最長的 Delayed 元素。如果延遲都還沒有期滿，則佇列沒有頭部，並且 poll 將返回 null。當一個元素的 getDelay(TimeUnit.NANOSECONDS) 方法返回一個小於等於 0 的值時，將發生到期。即使無法使用 take 或 poll 移除未到期的元素，也不會將這些元素作為正常元素對待。例如，size 方法同時返回到期和未到期元素的計數。此佇列不允許使用 null 元素。

此類別及其迭代器實作了 Collection 和 Iterator 介面的所有可選 方法。

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.5

建構子摘要

DelayQueue()
創建一個最初為空的新 DelayQueue。

DelayQueue(Collection<? extends E> c)
創建一個最初包含 Delayed 實例的給定 collection 元素的 DelayQueue。

方法摘要

boolean	add(E e) 將指定元素插入此延遲佇列中。
void	clear() 自動移除此延遲佇列的所有元素。
int	drainTo(Collection<? super E> c) 移除此佇列中所有可用的元素，並將它們添加到給定 collection 中。
int	drainTo(Collection<? super E> c, int maxElements) 最多從此佇列中移除給定數量的可用元素，並將這些元素添加到給定 collection 中。
Iterator<E>	iterator() 返回在此佇列所有元素（既包括到期的，也包括未到期的）上進行迭代的迭代器。
boolean	offer(E e) 將指定元素插入此延遲佇列。
boolean	offer(E e, long timeout, TimeUnit unit) 將指定元素插入此延遲佇列中。
E	peek() 獲取但不移除此佇列的頭部；如果此佇列為空，則返回 null。
E	poll() 獲取並移除此佇列的頭，如果此佇列不包含具有已到期延遲時間的元素，則返回 null。
E	poll(long timeout, TimeUnit unit) 獲取並移除此佇列的頭部，在可從此佇列獲得到期延遲的元素，或者到達指定的等待時間之前一直等待（如有必要）。
void	put(E e) 將指定元素插入此延遲佇列。
int	remainingCapacity() 因為 DelayQueue 沒有容量限制，所以它總是返回 Integer.MAX_VALUE。
boolean	remove(Object o) 從此佇列中移除指定元素的單個實例（如果存在），無論它是否到期。
int	size() 返回此 collection 中的元素數。
E	take() 獲取並移除此佇列的頭部，在可從此佇列獲得到期延遲的元素之前一直等待（如有必要）。
Object[]	toArray() 返回包含此佇列所有元素的陣列。
<T> T[]	toArray(T[] a) 返回一個套件含此佇列所有元素的陣列；返回陣列的運行時型別是指定陣列的型別。

從類別 java.util.AbstractQueue 繼承的方法

addAll, element, remove

從類別 java.util.AbstractCollection 繼承的方法

contains, containsAll, isEmpty, removeAll, retainAll, toString

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

從介面 java.util.concurrent.BlockingQueue 繼承的方法

contains

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

element, remove

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

addAll, containsAll, equals, hashCode, isEmpty, removeAll, retainAll

建構子詳細資訊

DelayQueue

public DelayQueue()

創建一個最初為空的新 DelayQueue。

DelayQueue

public DelayQueue(Collection<? extends E> c)

創建一個最初包含 Delayed 實例的給定 collection 元素的 DelayQueue。

參數：

c - 最初包含元素的 collection

拋出：

NullPointerException - 如果指定 collection 或其任意元素為 null

方法詳細資訊

add

public boolean add(E e)

將指定元素插入此延遲佇列中。

指定者：

介面 Collection<E extends Delayed> 中的 add

指定者：

介面 BlockingQueue<E extends Delayed> 中的 add

指定者：

介面 Queue<E extends Delayed> 中的 add

覆寫：

類別 AbstractQueue<E extends Delayed> 中的 add

參數：

e - 要添加的元素

返回：

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

拋出：

NullPointerException - 如果指定元素為 null

offer

public boolean offer(E e)

將指定元素插入此延遲佇列。

指定者：

介面 BlockingQueue<E extends Delayed> 中的 offer

指定者：

介面 Queue<E extends Delayed> 中的 offer

參數：

e - 要添加的元素

返回：

true

拋出：

NullPointerException - 如果指定的元素為 null

put

public void put(E e)

將指定元素插入此延遲佇列。由於該佇列是無界的，所以此方法不會阻塞。

指定者：

介面 BlockingQueue<E extends Delayed> 中的 put

參數：

e - 要添加的元素

拋出：

NullPointerException - 如果指定元素為 null

offer

public boolean offer(E e,
                     long timeout,
                     TimeUnit unit)

將指定元素插入此延遲佇列中。由於該佇列是無界的，所以此方法不會阻塞。

指定者：

介面 BlockingQueue<E extends Delayed> 中的 offer

參數：

e - 要添加的元素

timeout - 忽略此參數，因為此方法不會阻塞

unit - 忽略此參數，因為此方法不會阻塞

返回：

true

拋出：

NullPointerException - 如果指定元素為 null

poll

public E poll()

獲取並移除此佇列的頭，如果此佇列不包含具有已到期延遲時間的元素，則返回 null。

指定者：

介面 Queue<E extends Delayed> 中的 poll

返回：

此佇列的頭；如果此佇列不包含任何具有已到期延遲時間的元素，則返回 null

take

public E take()
                       throws InterruptedException

獲取並移除此佇列的頭部，在可從此佇列獲得到期延遲的元素之前一直等待（如有必要）。

指定者：

介面 BlockingQueue<E extends Delayed> 中的 take

返回：

此佇列的頭部

拋出：

InterruptedException - 如果在等待時被中斷

poll

public E poll(long timeout,
              TimeUnit unit)
                       throws InterruptedException

獲取並移除此佇列的頭部，在可從此佇列獲得到期延遲的元素，或者到達指定的等待時間之前一直等待（如有必要）。

指定者：

介面 BlockingQueue<E extends Delayed> 中的 poll

參數：

timeout - 放棄之前要等待的時間長度，用 unit 的時間單位表示

unit - 確定如何解釋 timeout 參數的 TimeUnit

返回：

此佇列的頭部；如果在可獲得到期延遲的元素之前超出了指定的等待時間，則返回 null

拋出：

InterruptedException - 如果在等待時被中斷

peek

public E peek()

獲取但不移除此佇列的頭部；如果此佇列為空，則返回 null。與 poll 不同，如果佇列中沒有到期元素可用，則此方法返回下一個將到期的元素（如果存在一個這樣的元素）。

指定者：

介面 Queue<E extends Delayed> 中的 peek

返回：

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

size

public int size()

從介面 Collection 複製的描述

返回此 collection 中的元素數。如果此 collection 套件含的元素大於 Integer.MAX_VALUE，則返回 Integer.MAX_VALUE。

指定者：

介面 Collection<E extends Delayed> 中的 size

指定者：

類別 AbstractCollection<E extends Delayed> 中的 size

返回：

此 collection 中的元素數

drainTo

public int drainTo(Collection<? super E> c)

從介面 BlockingQueue 複製的描述

移除此佇列中所有可用的元素，並將它們添加到給定 collection 中。此操作可能比反覆輪詢此佇列更有效。在試圖向 collection c 中添加元素沒有成功時，可能導致在拋出相關異常時，元素會同時在兩個 collection 中出現，或者在其中一個 collection 中出現，也可能在兩個 collection 中都不出現。如果試圖將一個佇列放入自身佇列中，則會導致 IllegalArgumentException 異常。此外，如果正在進行此操作時修改指定的 collection，則此操作行為是不確定的。

指定者：

介面 BlockingQueue<E extends Delayed> 中的 drainTo

參數：

c - 接收傳輸元素的 collection

返回：

傳輸元素的數量

拋出：

UnsupportedOperationException - 如果指定 collection 不支持添加元素

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

NullPointerException - 如果指定 collection 為 null

IllegalArgumentException - 如果指定 collection 是此佇列，或者此佇列元素的某些屬性不允許將其添加到指定 collection

drainTo

public int drainTo(Collection<? super E> c,
                   int maxElements)

從介面 BlockingQueue 複製的描述

最多從此佇列中移除給定數量的可用元素，並將這些元素添加到給定 collection 中。在試圖向 collection c 中添加元素沒有成功時，可能導致在拋出相關異常時，元素會同時在兩個 collection 中出現，或者在其中一個 collection 中出現，也可能在兩個 collection 中都不出現。如果試圖將一個佇列放入自身佇列中，則會導致 IllegalArgumentException 異常。此外，如果正在進行此操作時修改指定的 collection，則此操作行為是不確定的。

指定者：

介面 BlockingQueue<E extends Delayed> 中的 drainTo

參數：

c - 接收傳輸元素的 collection

maxElements - 傳輸元素的最大數量

返回：

傳輸元素的數量

拋出：

UnsupportedOperationException - 如果指定 collection 不支持添加元素

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

NullPointerException - 如果指定 collection 為 null

IllegalArgumentException - 如果指定 collection 是此佇列，或者此佇列元素的某些屬性不允許將其添加到指定 collection

clear

public void clear()

自動移除此延遲佇列的所有元素。此調用返回後，佇列將為空。不等待未到期延遲的元素；只是從佇列中丟棄它們。

指定者：

介面 Collection<E extends Delayed> 中的 clear

覆寫：

類別 AbstractQueue<E extends Delayed> 中的 clear

remainingCapacity

public int remainingCapacity()

因為 DelayQueue 沒有容量限制，所以它總是返回 Integer.MAX_VALUE。

指定者：

介面 BlockingQueue<E extends Delayed> 中的 remainingCapacity

返回：

Integer.MAX_VALUE

toArray

public Object[] toArray()

返回包含此佇列所有元素的陣列。所返回陣列的元素沒有特定的順序。

由於此佇列並不維護對返回陣列的任何參考，因而它將是「安全的」。（換句話說，此方法必須分派一個新陣列）。因此，調用者可以隨意修改返回的陣列。

此方法充當基於陣列的 API 與基於 collection 的 API 之間的橋樑。

指定者：

介面 Collection<E extends Delayed> 中的 toArray

覆寫：

類別 AbstractCollection<E extends Delayed> 中的 toArray

返回：

包含此佇列所有元素的陣列

toArray

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

返回一個套件含此佇列所有元素的陣列；返回陣列的運行時型別是指定陣列的型別。所返回陣列的元素沒有特定的順序。如果指定的陣列能容納佇列，則將該佇列返回此處。否則，將分派一個具有指定陣列的運行時型別和此佇列大小的新陣列。

如果指定的陣列能容納佇列，並有剩餘的空間（即陣列的元素比佇列多），那麼會將緊接佇列尾部的元素設置為 null。

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

以下程式碼用來將延遲佇列轉儲到一個新分派的 Delayed 陣列：

     Delayed[] a = q.toArray(new Delayed[0]);

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

指定者：

介面 Collection<E extends Delayed> 中的 toArray

覆寫：

類別 AbstractCollection<E extends Delayed> 中的 toArray

參數：

a - 用來存儲佇列元素的陣列（如果該陣列足夠大）；否則為此分派一個具有相同運行時型別的新陣列

返回：

包含此佇列所有元素的陣列

拋出：

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

NullPointerException - 如果指定陣列為 null

remove

public boolean remove(Object o)

從此佇列中移除指定元素的單個實例（如果存在），無論它是否到期。

指定者：

介面 Collection<E extends Delayed> 中的 remove

指定者：

介面 BlockingQueue<E extends Delayed> 中的 remove

覆寫：

類別 AbstractCollection<E extends Delayed> 中的 remove

參數：

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

返回：

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

iterator

public Iterator<E> iterator()

返回在此佇列所有元素（既包括到期的，也包括未到期的）上進行迭代的迭代器。迭代器不以任何特定的順序返回元素。返回的 Iterator 是一個「弱一致」迭代器，不會拋出 ConcurrentModificationException，並且可確保遍歷迭代器建構後所存在的所有元素，並且可能（但並不保證）反映建構後的所有修改。

指定者：

介面 Iterable<E extends Delayed> 中的 iterator

指定者：

介面 Collection<E extends Delayed> 中的 iterator

指定者：

類別 AbstractCollection<E extends Delayed> 中的 iterator

返回：

在此佇列元素上進行迭代的迭代器