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 | *{@link #addFirst addFirst(e)} | *{@link #offerFirst offerFirst(e)} | *{@link #putFirst putFirst(e)} | *{@link #offerFirst offerFirst(e, time, unit)} | *
| Remove | *{@link #removeFirst removeFirst()} | *{@link #pollFirst pollFirst()} | *{@link #takeFirst takeFirst()} | *{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)} | *
| Examine | *{@link #getFirst getFirst()} | *{@link #peekFirst peekFirst()} | *not applicable | *not applicable | *
| Last Element (Tail) | *||||
| * | Throws exception | *Special value | *Blocks | *Times out | *
| Insert | *{@link #addLast addLast(e)} | *{@link #offerLast offerLast(e)} | *{@link #putLast putLast(e)} | *{@link #offerLast offerLast(e, time, unit)} | *
| Remove | *{@link #removeLast() removeLast()} | *{@link #pollLast() pollLast()} | *{@link #takeLast takeLast()} | *{@link #pollLast(long, TimeUnit) pollLast(time, unit)} | *
| Examine | *{@link #getLast getLast()} | *{@link #peekLast peekLast()} | *not applicable | *not applicable | *
Like any {@link 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: * *
*
| BlockingQueue Method | *Equivalent BlockingDeque Method | *
| Insert | *|
| {@link #add add(e)} | *{@link #addLast addLast(e)} | *
| {@link #offer offer(e)} | *{@link #offerLast offerLast(e)} | *
| {@link #put put(e)} | *{@link #putLast putLast(e)} | *
| {@link #offer offer(e, time, unit)} | *{@link #offerLast offerLast(e, time, unit)} | *
| Remove | *|
| {@link #remove() remove()} | *{@link #removeFirst() removeFirst()} | *
| {@link #poll() poll()} | *{@link #pollFirst() pollFirst()} | *
| {@link #take() take()} | *{@link #takeFirst() takeFirst()} | *
| {@link #poll(long, TimeUnit) poll(time, unit)} | *{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)} | *
| Examine | *|
| {@link #element() element()} | *{@link #getFirst() getFirst()} | *
| {@link #peek() peek()} | *{@link #peekFirst() peekFirst()} | *
Memory consistency effects: As with other concurrent * collections, actions in a thread prior to placing an object into a * {@code BlockingDeque} * happen-before * actions subsequent to the access or removal of that element from * the {@code BlockingDeque} in another thread. * *
This interface is a member of the
*
* Java Collections Framework.
*
* @since 1.6
* @author Doug Lea
* @param This method is equivalent to {@link #addLast addLast}.
*
* @param e the element to add
* @throws IllegalStateException {@inheritDoc}
* @throws ClassCastException if the class of the specified element
* prevents it from being added to this deque
* @throws NullPointerException if the specified element is null
* @throws IllegalArgumentException if some property of the specified
* element prevents it from being added to this deque
*/
boolean add(E e);
/**
* Inserts 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, returning
* true upon success and false if no space is currently
* available. When using a capacity-restricted deque, this method is
* generally preferable to the {@link #add} method, which can fail to
* insert an element only by throwing an exception.
*
* This method is equivalent to {@link #offerLast offerLast}.
*
* @param e the element to add
* @throws ClassCastException if the class of the specified element
* prevents it from being added to this deque
* @throws NullPointerException if the specified element is null
* @throws IllegalArgumentException if some property of the specified
* element prevents it from being added to this deque
*/
boolean offer(E e);
/**
* Inserts 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 {@link #putLast putLast}.
*
* @param e the element to add
* @throws InterruptedException {@inheritDoc}
* @throws ClassCastException if the class of the specified element
* prevents it from being added to this deque
* @throws NullPointerException if the specified element is null
* @throws IllegalArgumentException if some property of the specified
* element prevents it from being added to this deque
*/
void put(E e) throws InterruptedException;
/**
* Inserts 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
* {@link #offerLast offerLast}.
*
* @param e the element to add
* @return true if the element was added to this deque, else
* false
* @throws InterruptedException {@inheritDoc}
* @throws ClassCastException if the class of the specified element
* prevents it from being added to this deque
* @throws NullPointerException if the specified element is null
* @throws IllegalArgumentException if some property of the specified
* element prevents it from being added to this deque
*/
boolean offer(E e, long timeout, TimeUnit unit)
throws InterruptedException;
/**
* Retrieves and removes the head of the queue represented by this deque
* (in other words, the first element of this deque).
* This method differs from {@link #poll poll} only in that it
* throws an exception if this deque is empty.
*
* This method is equivalent to {@link #removeFirst() removeFirst}.
*
* @return the head of the queue represented by this deque
* @throws NoSuchElementException if this deque is empty
*/
E remove();
/**
* Retrieves and removes the head of the queue represented by this deque
* (in other words, the first element of this deque), or returns
* null if this deque is empty.
*
* This method is equivalent to {@link #pollFirst()}.
*
* @return the head of this deque, or null if this deque is empty
*/
E poll();
/**
* 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.
*
* This method is equivalent to {@link #takeFirst() takeFirst}.
*
* @return the head of this deque
* @throws InterruptedException if interrupted while waiting
*/
E take() throws InterruptedException;
/**
* 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.
*
* This method is equivalent to
* {@link #pollFirst(long,TimeUnit) pollFirst}.
*
* @return the head of this deque, or null if the
* specified waiting time elapses before an element is available
* @throws InterruptedException if interrupted while waiting
*/
E poll(long timeout, TimeUnit unit)
throws InterruptedException;
/**
* Retrieves, but does not remove, the head of the queue represented by
* this deque (in other words, the first element of this deque).
* This method differs from {@link #peek peek} only in that it throws an
* exception if this deque is empty.
*
* This method is equivalent to {@link #getFirst() getFirst}.
*
* @return the head of this deque
* @throws NoSuchElementException if this deque is empty
*/
E element();
/**
* Retrieves, but does not remove, the head of the queue represented by
* this deque (in other words, the first element of this deque), or
* returns null if this deque is empty.
*
* This method is equivalent to {@link #peekFirst() peekFirst}.
*
* @return the head of this deque, or null if this deque is empty
*/
E peek();
/**
* Removes 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 element e such that
* o.equals(e) (if such an element exists).
* Returns true if this deque contained the specified element
* (or equivalently, if this deque changed as a result of the call).
*
* This method is equivalent to
* {@link #removeFirstOccurrence removeFirstOccurrence}.
*
* @param o element to be removed from this deque, if present
* @return true if this deque changed as a result of the call
* @throws ClassCastException if the class of the specified element
* is incompatible with this deque (optional)
* @throws NullPointerException if the specified element is null (optional)
*/
boolean remove(Object o);
/**
* Returns true if this deque contains the specified element.
* More formally, returns true if and only if this deque contains
* at least one element e such that o.equals(e).
*
* @param o object to be checked for containment in this deque
* @return true if this deque contains the specified element
* @throws ClassCastException if the class of the specified element
* is incompatible with this deque (optional)
* @throws NullPointerException if the specified element is null (optional)
*/
public boolean contains(Object o);
/**
* Returns the number of elements in this deque.
*
* @return the number of elements in this deque
*/
public int size();
/**
* Returns an iterator over the elements in this deque in proper sequence.
* The elements will be returned in order from first (head) to last (tail).
*
* @return an iterator over the elements in this deque in proper sequence
*/
Iterator This method is equivalent to {@link #addFirst addFirst}.
*
* @throws IllegalStateException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException if the specified element is null
* @throws IllegalArgumentException {@inheritDoc}
*/
void push(E e);
}