java.util.concurrent
类 DelayQueue

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

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

返回：

在此队列元素上进行迭代的迭代器