java.util.concurrent

接口
类
异常

java.util.concurrent
接口 BlockingDeque

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

      extends 
      BlockingQueue<E>, 
      Deque<E>

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

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

第一个元素（头部）
抛出异常 特殊值 阻塞 超时期
插入 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 -