Interface BlockingDeque<E>
- Type Parameters:
- E- the type of elements held in this deque
- All Superinterfaces:
- BlockingQueue<E>,- Collection<E>,- Deque<E>,- Iterable<E>,- Queue<E>,- SequencedCollection<E>
- All Known Implementing Classes:
- LinkedBlockingDeque
Deque that additionally supports blocking operations that wait
 for the deque to become non-empty when retrieving an element, and wait for
 space to become available in the deque when storing an element.
 BlockingDeque methods come in four forms, with different ways
 of handling operations that cannot be satisfied immediately, but may be
 satisfied at some point in the future:
 one throws an exception, the second returns a special value (either
 null or false, depending on the operation), the third
 blocks the current thread indefinitely until the operation can succeed,
 and the fourth blocks for only a given maximum time limit before giving
 up.  These methods are summarized in the following table:
 
| First Element (Head) | ||||
|---|---|---|---|---|
| Throws exception | Special value | Blocks | Times out | |
| Insert | addFirst(e) | offerFirst(e) | putFirst(e) | offerFirst(e, time, unit) | 
| Remove | removeFirst() | pollFirst() | takeFirst() | pollFirst(time, unit) | 
| Examine | getFirst() | peekFirst() | not applicable | not applicable | 
| Last Element (Tail) | ||||
| Throws exception | Special value | Blocks | Times out | |
| Insert | addLast(e) | offerLast(e) | putLast(e) | offerLast(e, time, unit) | 
| Remove | removeLast() | pollLast() | takeLast() | pollLast(time, unit) | 
| Examine | getLast() | peekLast() | not applicable | not applicable | 
Like any BlockingQueue, a BlockingDeque is thread safe,
 does not permit null elements, and may (or may not) be
 capacity-constrained.
 
A BlockingDeque implementation may be used directly as a FIFO
 BlockingQueue. The methods inherited from the
 BlockingQueue interface are precisely equivalent to
 BlockingDeque methods as indicated in the following table:
 
| BlockingQueueMethod | Equivalent BlockingDequeMethod | |
|---|---|---|
| Insert | add(e) | addLast(e) | 
| offer(e) | offerLast(e) | |
| put(e) | putLast(e) | |
| offer(e, time, unit) | offerLast(e, time, unit) | |
| Remove | remove() | removeFirst() | 
| poll() | pollFirst() | |
| take() | takeFirst() | |
| poll(time, unit) | pollFirst(time, unit) | |
| Examine | element() | getFirst() | 
| peek() | peekFirst() | 
Memory consistency effects: As with other concurrent
 collections, actions in a thread prior to placing an object into a
 BlockingDeque
 happen-before
 actions subsequent to the access or removal of that element from
 the BlockingDeque in another thread.
 
This interface is a member of the Java Collections Framework.
- Since:
- 1.6
- 
Method SummaryModifier and TypeMethodDescriptionbooleanInserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returningtrueupon success and throwing anIllegalStateExceptionif no space is currently available.voidInserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, throwing anIllegalStateExceptionif no space is currently available.voidInserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, throwing anIllegalStateExceptionif no space is currently available.booleanReturnstrueif this deque contains the specified element.element()Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque).iterator()Returns an iterator over the elements in this deque in proper sequence.booleanInserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returningtrueupon success andfalseif no space is currently available.booleanInserts the specified element into the queue represented by this deque (in other words, at the tail of this deque), waiting up to the specified wait time if necessary for space to become available.booleanofferFirst(E e) Inserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, returningtrueupon success andfalseif no space is currently available.booleanofferFirst(E e, long timeout, TimeUnit unit) Inserts the specified element at the front of this deque, waiting up to the specified wait time if necessary for space to become available.booleanInserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, returningtrueupon success andfalseif no space is currently available.booleanInserts the specified element at the end of this deque, waiting up to the specified wait time if necessary for space to become available.peek()Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque), or returnsnullif this deque is empty.poll()Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), or returnsnullif this deque is empty.Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), waiting up to the specified wait time if necessary for an element to become available.Retrieves and removes the first element of this deque, waiting up to the specified wait time if necessary for an element to become available.Retrieves and removes the last element of this deque, waiting up to the specified wait time if necessary for an element to become available.voidPushes an element onto the stack represented by this deque (in other words, at the head of this deque) if it is possible to do so immediately without violating capacity restrictions, throwing anIllegalStateExceptionif no space is currently available.voidInserts the specified element into the queue represented by this deque (in other words, at the tail of this deque), waiting if necessary for space to become available.voidInserts the specified element at the front of this deque, waiting if necessary for space to become available.voidInserts the specified element at the end of this deque, waiting if necessary for space to become available.remove()Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque).booleanRemoves the first occurrence of the specified element from this deque.booleanRemoves the first occurrence of the specified element from this deque.booleanRemoves the last occurrence of the specified element from this deque.intsize()Returns the number of elements in this deque.take()Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), waiting if necessary until an element becomes available.Retrieves and removes the first element of this deque, waiting if necessary until an element becomes available.takeLast()Retrieves and removes the last element of this deque, waiting if necessary until an element becomes available.Methods declared in interface java.util.concurrent.BlockingQueuedrainTo, drainTo, remainingCapacityMethods declared in interface java.util.Collectionclear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray, toArrayMethods declared in interface java.util.DequeaddAll, descendingIterator, getFirst, getLast, peekFirst, peekLast, pollFirst, pollLast, pop, removeFirst, removeLast, reversed
- 
Method Details- 
addFirstInserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, throwing anIllegalStateExceptionif no space is currently available. When using a capacity-restricted deque, it is generally preferable to useofferFirst.- Specified by:
- addFirstin interface- Deque<E>
- Specified by:
- addFirstin interface- SequencedCollection<E>
- Parameters:
- e- the element to add
- Throws:
- IllegalStateException- if the element cannot be added at this time due to capacity restrictions
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
addLastInserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, throwing anIllegalStateExceptionif no space is currently available. When using a capacity-restricted deque, it is generally preferable to useofferLast.- Specified by:
- addLastin interface- Deque<E>
- Specified by:
- addLastin interface- SequencedCollection<E>
- Parameters:
- e- the element to add
- Throws:
- IllegalStateException- if the element cannot be added at this time due to capacity restrictions
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
offerFirstInserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, returningtrueupon success andfalseif no space is currently available. When using a capacity-restricted deque, this method is generally preferable to theaddFirstmethod, which can fail to insert an element only by throwing an exception.- Specified by:
- offerFirstin interface- Deque<E>
- Parameters:
- e- the element to add
- Returns:
- trueif the element was added to this deque, else- false
- Throws:
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
offerLastInserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, returningtrueupon success andfalseif no space is currently available. When using a capacity-restricted deque, this method is generally preferable to theaddLastmethod, which can fail to insert an element only by throwing an exception.- Specified by:
- offerLastin interface- Deque<E>
- Parameters:
- e- the element to add
- Returns:
- trueif the element was added to this deque, else- false
- Throws:
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
putFirstInserts the specified element at the front of this deque, waiting if necessary for space to become available.- Parameters:
- e- the element to add
- Throws:
- InterruptedException- if interrupted while waiting
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
putLastInserts the specified element at the end of this deque, waiting if necessary for space to become available.- Parameters:
- e- the element to add
- Throws:
- InterruptedException- if interrupted while waiting
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
offerFirstInserts the specified element at the front of this deque, waiting up to the specified wait time if necessary for space to become available.- Parameters:
- e- the element to add
- timeout- how long to wait before giving up, in units of- unit
- unit- a- TimeUnitdetermining how to interpret the- timeoutparameter
- Returns:
- trueif successful, or- falseif the specified waiting time elapses before space is available
- Throws:
- InterruptedException- if interrupted while waiting
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
offerLastInserts the specified element at the end of this deque, waiting up to the specified wait time if necessary for space to become available.- Parameters:
- e- the element to add
- timeout- how long to wait before giving up, in units of- unit
- unit- a- TimeUnitdetermining how to interpret the- timeoutparameter
- Returns:
- trueif successful, or- falseif the specified waiting time elapses before space is available
- Throws:
- InterruptedException- if interrupted while waiting
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
takeFirstRetrieves and removes the first element of this deque, waiting if necessary until an element becomes available.- Returns:
- the head of this deque
- Throws:
- InterruptedException- if interrupted while waiting
 
- 
takeLastRetrieves and removes the last element of this deque, waiting if necessary until an element becomes available.- Returns:
- the tail of this deque
- Throws:
- InterruptedException- if interrupted while waiting
 
- 
pollFirstRetrieves and removes the first element of this deque, waiting up to the specified wait time if necessary for an element to become available.- Parameters:
- timeout- how long to wait before giving up, in units of- unit
- unit- a- TimeUnitdetermining how to interpret the- timeoutparameter
- Returns:
- the head of this deque, or nullif the specified waiting time elapses before an element is available
- Throws:
- InterruptedException- if interrupted while waiting
 
- 
pollLastRetrieves and removes the last element of this deque, waiting up to the specified wait time if necessary for an element to become available.- Parameters:
- timeout- how long to wait before giving up, in units of- unit
- unit- a- TimeUnitdetermining how to interpret the- timeoutparameter
- Returns:
- the tail of this deque, or nullif the specified waiting time elapses before an element is available
- Throws:
- InterruptedException- if interrupted while waiting
 
- 
removeFirstOccurrenceRemoves the first occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the first elementesuch thato.equals(e)(if such an element exists). Returnstrueif this deque contained the specified element (or equivalently, if this deque changed as a result of the call).- Specified by:
- removeFirstOccurrencein interface- Deque<E>
- Parameters:
- o- element to be removed from this deque, if present
- Returns:
- trueif an element was removed as a result of this call
- Throws:
- ClassCastException- if the class of the specified element is incompatible with this deque (optional)
- NullPointerException- if the specified element is null (optional)
 
- 
removeLastOccurrenceRemoves the last occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the last elementesuch thato.equals(e)(if such an element exists). Returnstrueif this deque contained the specified element (or equivalently, if this deque changed as a result of the call).- Specified by:
- removeLastOccurrencein interface- Deque<E>
- Parameters:
- o- element to be removed from this deque, if present
- Returns:
- trueif an element was removed as a result of this call
- Throws:
- ClassCastException- if the class of the specified element is incompatible with this deque (optional)
- NullPointerException- if the specified element is null (optional)
 
- 
addInserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returningtrueupon success and throwing anIllegalStateExceptionif no space is currently available. When using a capacity-restricted deque, it is generally preferable to useoffer.This method is equivalent to addLast.- Specified by:
- addin interface- BlockingQueue<E>
- Specified by:
- addin interface- Collection<E>
- Specified by:
- addin interface- Deque<E>
- Specified by:
- addin interface- Queue<E>
- Parameters:
- e- the element to add
- Returns:
- true(as specified by- Collection.add(E))
- Throws:
- IllegalStateException- if the element cannot be added at this time due to capacity restrictions
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
offerInserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returningtrueupon success andfalseif no space is currently available. When using a capacity-restricted deque, this method is generally preferable to theadd(E)method, which can fail to insert an element only by throwing an exception.This method is equivalent to offerLast.- Specified by:
- offerin interface- BlockingQueue<E>
- Specified by:
- offerin interface- Deque<E>
- Specified by:
- offerin interface- Queue<E>
- Parameters:
- e- the element to add
- Returns:
- trueif the element was added to this queue, else- false
- Throws:
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
putInserts the specified element into the queue represented by this deque (in other words, at the tail of this deque), waiting if necessary for space to become available.This method is equivalent to putLast.- Specified by:
- putin interface- BlockingQueue<E>
- Parameters:
- e- the element to add
- Throws:
- InterruptedException- if interrupted while waiting
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
offerInserts the specified element into the queue represented by this deque (in other words, at the tail of this deque), waiting up to the specified wait time if necessary for space to become available.This method is equivalent to offerLast.- Specified by:
- offerin interface- BlockingQueue<E>
- Parameters:
- e- the element to add
- timeout- how long to wait before giving up, in units of- unit
- unit- a- TimeUnitdetermining how to interpret the- timeoutparameter
- Returns:
- trueif the element was added to this deque, else- false
- Throws:
- InterruptedException- if interrupted while waiting
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
- 
removeE remove()Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque). This method differs frompoll()only in that it throws an exception if this deque is empty.This method is equivalent to removeFirst.
- 
pollE poll()Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), or returnsnullif this deque is empty.This method is equivalent to Deque.pollFirst().
- 
takeRetrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), waiting if necessary until an element becomes available.This method is equivalent to takeFirst.- Specified by:
- takein interface- BlockingQueue<E>
- Returns:
- the head of this deque
- Throws:
- InterruptedException- if interrupted while waiting
 
- 
pollRetrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), waiting up to the specified wait time if necessary for an element to become available.This method is equivalent to pollFirst.- Specified by:
- pollin interface- BlockingQueue<E>
- Parameters:
- timeout- how long to wait before giving up, in units of- unit
- unit- a- TimeUnitdetermining how to interpret the- timeoutparameter
- Returns:
- the head of this deque, or nullif the specified waiting time elapses before an element is available
- Throws:
- InterruptedException- if interrupted while waiting
 
- 
element
- 
peek
- 
removeRemoves the first occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the first elementesuch thato.equals(e)(if such an element exists). Returnstrueif this deque contained the specified element (or equivalently, if this deque changed as a result of the call).This method is equivalent to removeFirstOccurrence.- Specified by:
- removein interface- BlockingQueue<E>
- Specified by:
- removein interface- Collection<E>
- Specified by:
- removein interface- Deque<E>
- Parameters:
- o- element to be removed from this deque, if present
- Returns:
- trueif this deque changed as a result of the call
- Throws:
- ClassCastException- if the class of the specified element is incompatible with this deque (optional)
- NullPointerException- if the specified element is null (optional)
 
- 
containsReturnstrueif this deque contains the specified element. More formally, returnstrueif and only if this deque contains at least one elementesuch thato.equals(e).- Specified by:
- containsin interface- BlockingQueue<E>
- Specified by:
- containsin interface- Collection<E>
- Specified by:
- containsin interface- Deque<E>
- Parameters:
- o- object to be checked for containment in this deque
- Returns:
- trueif this deque contains the specified element
- Throws:
- ClassCastException- if the class of the specified element is incompatible with this deque (optional)
- NullPointerException- if the specified element is null (optional)
 
- 
size
- 
iteratorReturns an iterator over the elements in this deque in proper sequence. The elements will be returned in order from first (head) to last (tail).
- 
pushPushes an element onto the stack represented by this deque (in other words, at the head of this deque) if it is possible to do so immediately without violating capacity restrictions, throwing anIllegalStateExceptionif no space is currently available.This method is equivalent to addFirst.- Specified by:
- pushin interface- Deque<E>
- Parameters:
- e- the element to push
- Throws:
- IllegalStateException- if the element cannot be added at this time due to capacity restrictions
- ClassCastException- if the class of the specified element prevents it from being added to this deque
- NullPointerException- if the specified element is null
- IllegalArgumentException- if some property of the specified element prevents it from being added to this deque
 
 
-