net.sf.beanlib.util.concurrent
Interface BlockingDeque<E>

Type Parameters:

E - the type of elements held in this collection

All Superinterfaces:

BlockingQueue<E>, Collection<E>, Deque<E>, Iterable<E>, Queue<E>

All Known Implementing Classes:

LinkedBlockingDeque

public interface BlockingDeque<E>
extends Deque<E>, BlockingQueue<E>

A Deque that additionally supports 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. These methods are summarized in the following table:

	First Element (Head)		Last Element (Tail)
	Block	Time out	Block	Time out
Insert	putFirst(e)	offerFirst(e, time, unit)	putLast(e)	offerLast(e, time, unit)
Remove	takeFirst()	pollFirst(time, unit)	takeLast()	pollLast(time, unit)

Like any BlockingQueue, a BlockingDeque is thread safe and may (or may not) be capacity-constrained. A BlockingDeque implementation may be used directly as a FIFO BlockingQueue. The blocking methods inherited from the BlockingQueue interface are precisely equivalent to BlockingDeque methods as indicated in the following table:

BlockingQueue Method	Equivalent BlockingDeque Method
put(e)	putLast(e)
take()	takeFirst()
offer(e, time. unit)	offerLast(e, time, unit)
poll(time, unit)	pollFirst(time, unit)

This interface is a member of the Java Collections Framework.

Since:

1.6

Author:

Doug Lea

Method Summary

boolean	offer(E o, long timeout, TimeUnit unit) Inserts the specified element as the lest element of this deque, if possible.
boolean	offerFirst(E o, long timeout, TimeUnit unit) Inserts the specified element as the first element of this deque, waiting if necessary up to the specified wait time for space to become available.
boolean	offerLast(E o, long timeout, TimeUnit unit) Inserts the specified element as the last element of this deque, waiting if necessary up to the specified wait time for space to become available.
E	poll(long timeout, TimeUnit unit) Retrieves and removes the first element of this deque, waiting if necessary up to the specified wait time if no elements are present on this deque.
E	pollFirst(long timeout, TimeUnit unit) Retrieves and removes the first element of this deque, waiting if necessary up to the specified wait time if no elements are present on this deque.
E	pollLast(long timeout, TimeUnit unit) Retrieves and removes the last element of this deque, waiting if necessary up to the specified wait time if no elements are present on this deque.
void	put(E o) Adds the specified element as the last element of this deque, waiting if necessary for space to become available.
void	putFirst(E o) Adds the specified element as the first element of this deque, waiting if necessary for space to become available.
void	putLast(E o) Adds the specified element as the last element of this deque, waiting if necessary for space to become available.
E	take() Retrieves and removes the first element of this deque, waiting if no elements are present on this deque.
E	takeFirst() Retrieves and removes the first element of this deque, waiting if no elements are present on this deque.
E	takeLast() Retrieves and removes the last element of this deque, waiting if no elements are present on this deque.

Methods inherited from interface net.sf.beanlib.util.Deque

add, addFirst, addLast, contains, descendingIterator, element, getFirst, getLast, iterator, offer, offerFirst, offerLast, peek, peekFirst, peekLast, poll, pollFirst, pollLast, pop, push, remove, remove, removeFirst, removeFirstOccurrence, removeLast, removeLastOccurrence, size

Methods inherited from interface java.util.Collection

addAll, clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray

Methods inherited from interface java.util.concurrent.BlockingQueue

add, drainTo, drainTo, offer, remainingCapacity

Methods inherited from interface java.util.Collection

addAll, clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray

Method Detail

putFirst

void putFirst(E o)
              throws InterruptedException

Adds the specified element as the first element of this deque, waiting if necessary for space to become available.

Parameters:

o - the element to add

Throws:

InterruptedException - if interrupted while waiting.

NullPointerException - if the specified element is null.

putLast

void putLast(E o)
             throws InterruptedException

Adds the specified element as the last element of this deque, waiting if necessary for space to become available.

Parameters:

o - the element to add

Throws:

InterruptedException - if interrupted while waiting.

NullPointerException - if the specified element is null.

takeFirst

E takeFirst()
            throws InterruptedException

Retrieves and removes the first element of this deque, waiting if no elements are present on this deque.

Returns:

the head of this deque

Throws:

InterruptedException - if interrupted while waiting.

takeLast

E takeLast()
           throws InterruptedException

Retrieves and removes the last element of this deque, waiting if no elements are present on this deque.

Returns:

the head of this deque

Throws:

InterruptedException - if interrupted while waiting.

offerFirst

boolean offerFirst(E o,
                   long timeout,
                   TimeUnit unit)
                   throws InterruptedException

Inserts the specified element as the first element of this deque, waiting if necessary up to the specified wait time for space to become available.

Parameters:

o - the element to add

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

true if successful, or false if the specified waiting time elapses before space is available.

Throws:

InterruptedException - if interrupted while waiting.

NullPointerException - if the specified element is null.

offerLast

boolean offerLast(E o,
                  long timeout,
                  TimeUnit unit)
                  throws InterruptedException

Inserts the specified element as the last element of this deque, waiting if necessary up to the specified wait time for space to become available.

Parameters:

o - the element to add

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

true if successful, or false if the specified waiting time elapses before space is available.

Throws:

InterruptedException - if interrupted while waiting.

NullPointerException - if the specified element is null.

pollFirst

E pollFirst(long timeout,
            TimeUnit unit)
            throws InterruptedException

Retrieves and removes the first element of this deque, waiting if necessary up to the specified wait time if no elements are present on this deque.

Parameters:

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the head of this deque, or null if the specified waiting time elapses before an element is present.

Throws:

InterruptedException - if interrupted while waiting.

pollLast

E pollLast(long timeout,
           TimeUnit unit)
           throws InterruptedException

Retrieves and removes the last element of this deque, waiting if necessary up to the specified wait time if no elements are present on this deque.

Parameters:

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the head of this deque, or null if the specified waiting time elapses before an element is present.

Throws:

InterruptedException - if interrupted while waiting.

put

void put(E o)
         throws InterruptedException

Adds the specified element as the last element of this deque, waiting if necessary for space to become available. This method is equivalent to to putLast

Specified by:

put in interface BlockingQueue<E>

Parameters:

o - the element to add

Throws:

InterruptedException - if interrupted while waiting.

NullPointerException - if the specified element is null.

offer

boolean offer(E o,
              long timeout,
              TimeUnit unit)
              throws InterruptedException

Inserts the specified element as the lest element of this deque, if possible. When using deques that may impose insertion restrictions (for example capacity bounds), method offer is generally preferable to method Collection.add(E), which can fail to insert an element only by throwing an exception. This method is equivalent to to offerLast

Specified by:

offer in interface BlockingQueue<E>

Parameters:

o - the element to add.

Returns:

true if it was possible to add the element to this deque, else false

Throws:

NullPointerException - if the specified element is null

InterruptedException

take

E take()
       throws InterruptedException

Retrieves and removes the first element of this deque, waiting if no elements are present on this deque. This method is equivalent to to takeFirst

Specified by:

take in interface BlockingQueue<E>

Returns:

the head of this deque

Throws:

InterruptedException - if interrupted while waiting.

poll

E poll(long timeout,
       TimeUnit unit)
       throws InterruptedException

Retrieves and removes the first element of this deque, waiting if necessary up to the specified wait time if no elements are present on this deque. This method is equivalent to to pollFirst

Specified by:

poll in interface BlockingQueue<E>

Parameters:

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the head of this deque, or null if the specified waiting time elapses before an element is present.

Throws:

InterruptedException - if interrupted while waiting.