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，這兩個操作是：獲取元素時等待雙端佇列變為非空(null)；存儲元素時等待雙端佇列中的空間變得可用。

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) 將元素推入此雙端佇列表示的堆疊(stack)空間。
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)

將元素推入此雙端佇列表示的堆疊(stack)空間。換句話說，在不違反容量限制的情況下，將元素插入雙端佇列的開頭。

此方法等效於 addFirst。

指定者：

介面 Deque<E> 中的 push

參數：

e - 要推入的元素

拋出：

IllegalStateException - 如果此時由於容量限制而無法添加元素

ClassCastException - 如果指定元素的類別不允許將它添加此雙端佇列

NullPointerException - 如果指定的元素為 null

IllegalArgumentException - 如果指定元素的某些屬性不允許將它添加到此雙端佇列