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(Object) offerFirst(e)} | + *{@link #putFirst putFirst(e)} | + *{@link #offerFirst(Object, long, TimeUnit) 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(Object) offerLast(e)} | + *{@link #putLast putLast(e)} | + *{@link #offerLast(Object, long, TimeUnit) 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(Object) add(e)} | + *{@link #addLast(Object) addLast(e)} | + *
| {@link #offer(Object) offer(e)} | + *{@link #offerLast(Object) offerLast(e)} | + *
| {@link #put(Object) put(e)} | + *{@link #putLast(Object) putLast(e)} | + *
| {@link #offer(Object, long, TimeUnit) offer(e, time, unit)} | + *{@link #offerLast(Object, long, TimeUnit) 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(Object) 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(Object) 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(Object) 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(Object,long,TimeUnit) 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(Object) 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(Object) addFirst}.
+ *
+ * @throws IllegalStateException {@inheritDoc}
+ * @throws ClassCastException {@inheritDoc}
+ * @throws NullPointerException if the specified element is null
+ * @throws IllegalArgumentException {@inheritDoc}
+ */
+ void push(E e);
+}