JavaTM Platform
Standard Ed. 6

java.util.concurrent
接口 BlockingDeque<E>

类型参数:
E - 保存在此 collection 中的元素类型
所有超级接口:
BlockingQueue<E>, Collection<E>, Deque<E>, Iterable<E>, Queue<E>
所有已知实现类:
LinkedBlockingDeque

public interface BlockingDeque<E>
extends BlockingQueue<E>, Deque<E>

支持两个附加操作的 Queue,这两个操作是:获取元素时等待双端队列变为非空;存储元素时等待双端队列中的空间变得可用。

BlockingDeque 方法有四种形式,使用不同的方式处理无法立即满足但在将来某一时刻可能满足的操作:第一种方式抛出异常;第二种返回一个特殊值(nullfalse,具体取决于操作);第三种无限期阻塞当前线程,直至操作成功;第四种只阻塞给定的最大时间,然后放弃。下表中总结了这些方法:

第一个元素(头部)
抛出异常 特殊值 阻塞 超时期
插入 addFirst(e) offerFirst(e) putFirst(e) offerFirst(e, time, unit)
移除 removeFirst() pollFirst() takeFirst() pollFirst(time, unit)
检查 getFirst() peekFirst() 不适用 不适用
最后一个元素(尾部)
抛出异常 特殊值 阻塞 超时期
插入 addLast(e) offerLast(e) putLast(e) offerLast(e, time, unit)
移除 removeLast() pollLast() takeLast() pollLast(time, unit)
检查 getLast() peekLast() 不适用 不适用

像所有 BlockingQueue 一样,BlockingDeque 是线程安全的,但不允许 null 元素,并且可能有(也可能没有)容量限制。

BlockingDeque 实现可以直接用作 FIFO BlockingQueue。继承自 BlockingQueue 接口的方法精确地等效于下表中描述的 BlockingDeque 方法:

BlockingQueue 方法 等效的 BlockingDeque 方法
插入
add(e) addLast(e)
offer(e) offerLast(e)
put(e) putLast(e)
offer(e, time, unit) offerLast(e, time, unit)
移除
remove() removeFirst()
poll() pollFirst()
take() takeFirst()
poll(time, unit) pollFirst(time, unit)
检查
element() getFirst()
peek() peekFirst()

内存一致性效果:当存在其他并发 collection 时,将对象放入 BlockingDeque 之前的线程中的操作 happen-before 随后通过另一线程从 BlockingDeque 中访问或移除该元素的操作。

此接口是 Java Collections Framework 的成员。

从以下版本开始:
1.6

方法摘要
 boolean add(E e)
          Inserts the 如果立即可行且不违反容量限制,则将指定的元素插入此双端队列表示的队列中(即此双端队列的尾部),并在成功时返回 true;如果当前没有空间可用,则抛出 IllegalStateException
 void addFirst(E e)
          如果立即可行且不违反容量限制,则将指定的元素插入此双端队列的开头;如果当前没有空间可用,则抛出 IllegalStateException
 void addLast(E e)
          如果立即可行且不违反容量限制,则将指定的元素插入此双端队列的末尾;如果当前没有空间可用,则抛出 IllegalStateException
 boolean contains(Object o)
          如果此双端队列包含指定的元素,则返回 true
 E element()
          获取但不移除此双端队列表示的队列的头部(即此双端队列的第一个元素)。
 Iterator<E> iterator()
          返回在此双端队列中的元素上以恰当顺序进行迭代的迭代器。
 boolean offer(E e)
          如果立即可行且不违反容量限制,则将指定的元素插入此双端队列表示的队列中(即此双端队列的尾部),并在成功时返回 true;如果当前没有空间可用,则返回 false
 boolean offer(E e, long timeout, TimeUnit unit)
          将指定的元素插入此双端队列表示的队列中(即此双端队列的尾部),必要时将在指定的等待时间内一直等待可用空间。
 boolean offerFirst(E e)
          如果立即可行且不违反容量限制,则将指定的元素插入此双端队列的开头,并在成功时返回 true;如果当前没有空间可用,则返回 false
 boolean offerFirst(E e, long timeout, TimeUnit unit)
          将指定的元素插入此双端队列的开头,必要时将在指定的等待时间内等待可用空间。
 boolean offerLast(E e)
          如果立即可行且不违反容量限制,则将指定的元素插入此双端队列的末尾,并在成功时返回 true;如果当前没有空间可用,则返回 false
 boolean offerLast(E e, long timeout, TimeUnit unit)
          将指定的元素插入此双端队列的末尾,必要时将在指定的等待时间内等待可用空间。
 E peek()
          获取但不移除此双端队列表示的队列的头部(即此双端队列的第一个元素);如果此双端队列为空,则返回 null
 E poll()
          获取并移除此双端队列表示的队列的头部(即此双端队列的第一个元素);如果此双端队列为空,则返回 null
 E poll(long timeout, TimeUnit unit)
          获取并移除此双端队列表示的队列的头部(即此双端队列的第一个元素),如有必要将在指定的等待时间内等待可用元素。
 E pollFirst(long timeout, TimeUnit unit)
          获取并移除此双端队列的第一个元素,必要时将在指定的等待时间等待可用元素。
 E pollLast(long timeout, TimeUnit unit)
          获取并移除此双端队列的最后一个元素,必要时将在指定的等待时间内等待可用元素。
 void push(E e)
          将元素推入此双端队列表示的栈。
 void put(E e)
          将指定的元素插入此双端队列表示的队列中(即此双端队列的尾部),必要时将一直等待可用空间。
 void putFirst(E e)
          将指定的元素插入此双端队列的开头,必要时将一直等待可用空间。
 void putLast(E e)
          将指定的元素插入此双端队列的末尾,必要时将一直等待可用空间。
 E remove()
          获取并移除此双端队列表示的队列的头部(即此双端队列的第一个元素)。
 boolean remove(Object o)
          从此双端队列移除第一次出现的指定元素。
 boolean removeFirstOccurrence(Object o)
          从此双端队列移除第一次出现的指定元素。
 boolean removeLastOccurrence(Object o)
          从此双端队列移除最后一次出现的指定元素。
 int size()
          返回此双端队列中的元素数。
 E take()
          获取并移除此双端队列表示的队列的头部(即此双端队列的第一个元素),必要时将一直等待可用元素。
 E takeFirst()
          获取并移除此双端队列的第一个元素,必要时将一直等待可用元素。
 E takeLast()
          获取并移除此双端队列的最后一个元素,必要时将一直等待可用元素。
 
从接口 java.util.concurrent.BlockingQueue 继承的方法
drainTo, drainTo, remainingCapacity
 
从接口 java.util.Deque 继承的方法
descendingIterator, getFirst, getLast, peekFirst, peekLast, pollFirst, pollLast, pop, removeFirst, removeLast
 
从接口 java.util.Collection 继承的方法
addAll, clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray
 

方法详细信息

addFirst

void addFirst(E e)
如果立即可行且不违反容量限制,则将指定的元素插入此双端队列的开头;如果当前没有空间可用,则抛出 IllegalStateException。当使用有容量限制的双端队列时,通常首选 offerFirst

指定者:
接口 Deque<E> 中的 addFirst
参数:
e - 要添加的元素
抛出:
IllegalStateException - 如果此时由于容量限制而无法添加元素
ClassCastException - 如果指定元素的类不允许将它添加此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

addLast

void addLast(E e)
如果立即可行且不违反容量限制,则将指定的元素插入此双端队列的末尾;如果当前没有空间可用,则抛出 IllegalStateException。当使用有容量限制的双端队列时,通常首选 offerLast

指定者:
接口 Deque<E> 中的 addLast
参数:
e - 要添加的元素
抛出:
IllegalStateException - 如果此时由于容量限制而无法添加元素
ClassCastException - 如果指定元素的类不允许将它添加此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

offerFirst

boolean offerFirst(E e)
如果立即可行且不违反容量限制,则将指定的元素插入此双端队列的开头,并在成功时返回 true;如果当前没有空间可用,则返回 false。当使用有容量限制的双端队列时,此方法通常优于 addFirst 方法,后者可能无法插入元素,而只是抛出一个异常。

指定者:
接口 Deque<E> 中的 offerFirst
参数:
e - 要添加的元素
返回:
如果元素被添加到此双端队列,则返回 true,否则返回 false
抛出:
ClassCastException - 如果指定元素的类不允许将它添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

offerLast

boolean offerLast(E e)
如果立即可行且不违反容量限制,则将指定的元素插入此双端队列的末尾,并在成功时返回 true;如果当前没有空间可用,则返回 false。当使用有容量限制的双端队列时,该方法通常优于 addLast 方法,后者可能无法插入元素,而只是抛出一个异常。

指定者:
接口 Deque<E> 中的 offerLast
参数:
e - 要添加的元素
返回:
如果元素被添加到此双端队列,则返回 true,否则返回 false
抛出:
ClassCastException - 如果指定元素的类不允许将它添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

putFirst

void putFirst(E e)
              throws InterruptedException
将指定的元素插入此双端队列的开头,必要时将一直等待可用空间。

参数:
e - 要添加的元素
抛出:
InterruptedException - 如果在等待时被中断
ClassCastException - 如果指定元素的类不允许它被添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

putLast

void putLast(E e)
             throws InterruptedException
将指定的元素插入此双端队列的末尾,必要时将一直等待可用空间。

参数:
e - 要添加的元素
抛出:
InterruptedException - 如果在等待时被中断
ClassCastException - 如果指定元素的类不允许它被添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

offerFirst

boolean offerFirst(E e,
                   long timeout,
                   TimeUnit unit)
                   throws InterruptedException
将指定的元素插入此双端队列的开头,必要时将在指定的等待时间内等待可用空间。

参数:
e - 要添加的元素
timeout - 放弃之前等待的时间长度,以 unit 为时间单位
unit - 确定如何解释 timeout 参数的 TimeUnit
返回:
如果成功,则返回 true;如果在空间可用前超过了指定的等待时间,则返回 false
抛出:
InterruptedException - 如果在等待时被中断
ClassCastException - 如果指定元素的类不允许它被添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

offerLast

boolean offerLast(E e,
                  long timeout,
                  TimeUnit unit)
                  throws InterruptedException
将指定的元素插入此双端队列的末尾,必要时将在指定的等待时间内等待可用空间。

参数:
e - 要添加的元素
timeout - 放弃之前等待的时间长度,以 unit 为时间单位
unit - 确定如何解释 timeout 参数的 TimeUnit
返回:
如果成功,则返回 true;如果在空间可用前超过了指定的等待时间,则返回 false
抛出:
InterruptedException - 如果在等待时被中断
ClassCastException - 如果指定元素的类不允许它被添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

takeFirst

E takeFirst()
            throws InterruptedException
获取并移除此双端队列的第一个元素,必要时将一直等待可用元素。

返回:
此双端队列的头部
抛出:
InterruptedException - 如果在等待时被中断

takeLast

E takeLast()
           throws InterruptedException
获取并移除此双端队列的最后一个元素,必要时将一直等待可用元素。

返回:
此双端队列的尾部
抛出:
InterruptedException - 如果在等待时被中断

pollFirst

E pollFirst(long timeout,
            TimeUnit unit)
            throws InterruptedException
获取并移除此双端队列的第一个元素,必要时将在指定的等待时间等待可用元素。

参数:
timeout - 放弃之前等待的时间长度,以 unit 为时间单位
unit - 确定如何解释 timeout 参数的 TimeUnit
返回:
此双端队列的头部,如果在元素可用前超过了指定的等待时间,则返回 null
抛出:
InterruptedException - 如果在等待时被中断

pollLast

E pollLast(long timeout,
           TimeUnit unit)
           throws InterruptedException
获取并移除此双端队列的最后一个元素,必要时将在指定的等待时间内等待可用元素。

参数:
timeout - 放弃之前等待的时间长度,以 unit 为时间单位
unit - 确定如何解释 timeout 参数的 TimeUnit
返回:
此双端队列的尾部,如果在元素可用前超过了指定的等待时间,则返回 null
抛出:
InterruptedException - 如果在等待时被中断

removeFirstOccurrence

boolean removeFirstOccurrence(Object o)
从此双端队列移除第一次出现的指定元素。如果此双端队列不包含该元素,则不作更改。更确切地讲,移除第一个满足 o.equals(e) 的元素 e(如果存在这样的元素)。如果此双端队列包含指定的元素(或者此双端队列由于调用而发生了更改),则返回 true

指定者:
接口 Deque<E> 中的 removeFirstOccurrence
参数:
o - 要从此双端队列移除的元素(如果存在)
返回:
如果由于此调用而移除了一个元素,则返回 true
抛出:
ClassCastException - 如果指定元素的类与此双端队列不兼容(可选)
NullPointerException - 如果指定的元素为 null(可选)

removeLastOccurrence

boolean removeLastOccurrence(Object o)
从此双端队列移除最后一次出现的指定元素。如果此双端队列不包含该元素,则不作更改。更确切地讲,移除最后一个满足 o.equals(e) 的元素 e(如果存在这样的元素)。如果此双端队列包含指定的元素(或者此双端队列由于调用而发生了更改),则返回 true

指定者:
接口 Deque<E> 中的 removeLastOccurrence
参数:
o - 要从此双端队列移除的元素(如果存在)
返回:
如果由于此调用而移除了一个元素,则返回 true
抛出:
ClassCastException - 如果指定元素的类与此双端队列不兼容(可选)
NullPointerException - 如果指定的元素为 null(可选)

add

boolean add(E e)
Inserts the 如果立即可行且不违反容量限制,则将指定的元素插入此双端队列表示的队列中(即此双端队列的尾部),并在成功时返回 true;如果当前没有空间可用,则抛出 IllegalStateException。当使用有容量限制的双端队列时,通常首选 offer

此方法等效于 addLast

指定者:
接口 BlockingQueue<E> 中的 add
指定者:
接口 Collection<E> 中的 add
指定者:
接口 Deque<E> 中的 add
指定者:
接口 Queue<E> 中的 add
参数:
e - 要添加的元素
返回:
true(根据 Collection.add(E) 的规定)
抛出:
IllegalStateException - 如果由于容量限制此时不能添加该元素
ClassCastException - 如果指定元素的类不允许它被添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

offer

boolean offer(E e)
如果立即可行且不违反容量限制,则将指定的元素插入此双端队列表示的队列中(即此双端队列的尾部),并在成功时返回 true;如果当前没有空间可用,则返回 false。当使用有容量限制的双端队列时,此方法通常优于 add(E) 方法,后者可能无法插入元素,而只是抛出一个异常。

此方法等效于 offerLast

指定者:
接口 BlockingQueue<E> 中的 offer
指定者:
接口 Deque<E> 中的 offer
指定者:
接口 Queue<E> 中的 offer
参数:
e - 要添加的元素
返回:
如果该元素已添加到此队列,则返回 true;否则返回 false
抛出:
ClassCastException - 如果指定元素的类不允许它被添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

put

void put(E e)
         throws InterruptedException
将指定的元素插入此双端队列表示的队列中(即此双端队列的尾部),必要时将一直等待可用空间。

此方法等效于 putLast

指定者:
接口 BlockingQueue<E> 中的 put
参数:
e - 要添加的元素
抛出:
InterruptedException - 如果在等待时被中断
ClassCastException - 如果指定元素的类不允许它被添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

offer

boolean offer(E e,
              long timeout,
              TimeUnit unit)
              throws InterruptedException
将指定的元素插入此双端队列表示的队列中(即此双端队列的尾部),必要时将在指定的等待时间内一直等待可用空间。

此方法等效于 offerLast

指定者:
接口 BlockingQueue<E> 中的 offer
参数:
e - 要添加的元素
timeout - 放弃之前等待的时间长度,以 unit 为时间单位
unit - 确定如何解释 timeout 参数的 TimeUnit
返回:
如果元素被添加到此双端队列,则返回 true,否则返回 false
抛出:
InterruptedException - 如果在等待时被中断
ClassCastException - 如果指定元素的类不允许它被添加到此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

remove

E remove()
获取并移除此双端队列表示的队列的头部(即此双端队列的第一个元素)。此方法与 poll 的不同之处在于:如果此双端队列为空,它会抛出一个异常。

此方法等效于 removeFirst

指定者:
接口 Deque<E> 中的 remove
指定者:
接口 Queue<E> 中的 remove
返回:
此双端队列表示的队列的头部
抛出:
NoSuchElementException - 如果此双端队列为空

poll

E poll()
获取并移除此双端队列表示的队列的头部(即此双端队列的第一个元素);如果此双端队列为空,则返回 null

此方法等效于 Deque.pollFirst()

指定者:
接口 Deque<E> 中的 poll
指定者:
接口 Queue<E> 中的 poll
返回:
此双端队列的头部;如果此双端队列为空,则返回 null

take

E take()
       throws InterruptedException
获取并移除此双端队列表示的队列的头部(即此双端队列的第一个元素),必要时将一直等待可用元素。

此方法等效于 takeFirst

指定者:
接口 BlockingQueue<E> 中的 take
返回:
此双端队列的头部
抛出:
InterruptedException - 如果在等待时被中断

poll

E poll(long timeout,
       TimeUnit unit)
       throws InterruptedException
获取并移除此双端队列表示的队列的头部(即此双端队列的第一个元素),如有必要将在指定的等待时间内等待可用元素。

此方法等效于 pollFirst

指定者:
接口 BlockingQueue<E> 中的 poll
参数:
timeout - 放弃之前要等待的时间长度,用 unit 的时间单位表示
unit - 确定如何解释 timeout 参数的 TimeUnit
返回:
此双端队列的头部;如果在元素可用前超过了指定的等待时间,则返回 null
抛出:
InterruptedException - 如果在等待时被中断

element

E element()
获取但不移除此双端队列表示的队列的头部(即此双端队列的第一个元素)。此方法与 peek 的不同之处在于:如果此双端队列为空,它会抛出一个异常。

此方法等效于 getFirst

指定者:
接口 Deque<E> 中的 element
指定者:
接口 Queue<E> 中的 element
返回:
此双端队列的头部
抛出:
NoSuchElementException - 如果此双端队列为空

peek

E peek()
获取但不移除此双端队列表示的队列的头部(即此双端队列的第一个元素);如果此双端队列为空,则返回 null

此方法等效于 peekFirst

指定者:
接口 Deque<E> 中的 peek
指定者:
接口 Queue<E> 中的 peek
返回:
此双端队列的头部;如果此双端队列为空,则返回 null

remove

boolean remove(Object o)
从此双端队列移除第一次出现的指定元素。如果此双端队列不包含该元素,则不作更改。更确切地讲,移除第一个满足 o.equals(e) 的元素 e(如果存在这样的元素)。如果此双端队列包含指定的元素(或者此双端队列由于调用而发生了更改),则返回 true

此方法等效于 removeFirstOccurrence

指定者:
接口 BlockingQueue<E> 中的 remove
指定者:
接口 Collection<E> 中的 remove
指定者:
接口 Deque<E> 中的 remove
参数:
o - 要从此双端队列移除的元素(如果存在)
返回:
如果此双端队列由于调用而发生更改,则返回 true
抛出:
ClassCastException - 如果指定元素的类与此双端队列不兼容(可选)
NullPointerException - 如果指定的元素为 null(可选)

contains

boolean contains(Object o)
如果此双端队列包含指定的元素,则返回 true。更确切地讲,当且仅当此双端队列至少包含一个满足 o.equals(e) 的元素 e,返回 true

指定者:
接口 BlockingQueue<E> 中的 contains
指定者:
接口 Collection<E> 中的 contains
指定者:
接口 Deque<E> 中的 contains
参数:
o - 检查是否包含在此双端队列中的对象
返回:
如果此双端队列包含指定的元素,则返回 true
抛出:
ClassCastException - 如果指定元素的类与此双端队列不兼容(可选)
NullPointerException - 如果指定的元素为 null(可选)

size

int size()
返回此双端队列中的元素数。

指定者:
接口 Collection<E> 中的 size
指定者:
接口 Deque<E> 中的 size
返回:
此双端队列中的元素数

iterator

Iterator<E> iterator()
返回在此双端队列中的元素上以恰当顺序进行迭代的迭代器。元素将按从第一个(头部)到最后一个(尾部)的顺序返回。

指定者:
接口 Collection<E> 中的 iterator
指定者:
接口 Deque<E> 中的 iterator
指定者:
接口 Iterable<E> 中的 iterator
返回:
按恰当顺序在此双端队列中的元素上进行迭代的迭代器

push

void push(E e)
将元素推入此双端队列表示的栈。换句话说,在不违反容量限制的情况下,将元素插入双端队列的开头。

此方法等效于 addFirst

指定者:
接口 Deque<E> 中的 push
参数:
e - 要推入的元素
抛出:
IllegalStateException - 如果此时由于容量限制而无法添加元素
ClassCastException - 如果指定元素的类不允许将它添加此双端队列
NullPointerException - 如果指定的元素为 null
IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策