java.util.concurrent

接口
异常
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 的值时,将发生到期。即使无法使用 takepoll 移除未到期的元素,也不会将这些元素作为正常元素对待。例如,size 方法同时返回到期和未到期元素的计数。此队列不允许使用 null 元素。

此类及其迭代器实现了 CollectionIterator 接口的所有可选 方法。

此类是 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
返回:
在此队列元素上进行迭代的迭代器