A bounded blocking queue backed by an
array. This queue orders elements FIFO (first-in-first-out). The
head of the queue is that element that has been on the
queue the longest time. The tail of the queue is that
element that has been on the queue the shortest time. New elements
are inserted at the tail of the queue, and the queue retrieval
operations obtain elements at the head of the queue.

This is a classic "bounded buffer", in which a
fixed-sized array holds elements inserted by producers and
extracted by consumers. Once created, the capacity cannot be
changed. Attempts to put an element into a full queue
will result in the operation blocking; attempts to take an
element from an empty queue will similarly block.

This class supports an optional fairness policy for ordering
waiting producer and consumer threads. By default, this ordering
is not guaranteed. However, a queue constructed with fairness set
to true grants threads access in FIFO order. Fairness
generally decreases throughput but reduces variability and avoids
starvation.

This class and its iterator implement all of the
optional methods of the Collection and Iterator interfaces.

Creates an ArrayBlockingQueue with the given (fixed)
capacity, the specified access policy and initially containing the
elements of the given collection,
added in traversal order of the collection's iterator.

Method Summary

Inserts the specified element at the tail of this queue if it is
possible to do so immediately without exceeding the queue's capacity,
returning true upon success and throwing an
IllegalStateException if this queue is full.

ArrayBlockingQueue

Creates an ArrayBlockingQueue with the given (fixed)
capacity, the specified access policy and initially containing the
elements of the given collection,
added in traversal order of the collection's iterator.

Parameters:

capacity - the capacity of this queue

fair - if true then queue accesses for threads blocked
on insertion or removal, are processed in FIFO order;
if false the access order is unspecified.

Method Detail

add

Inserts the specified element at the tail of this queue if it is
possible to do so immediately without exceeding the queue's capacity,
returning true upon success and throwing an
IllegalStateException if this queue is full.

offer

Inserts the specified element at the tail of this queue if it is
possible to do so immediately without exceeding the queue's capacity,
returning true upon success and false if this queue
is full. This method is generally preferable to method add(E),
which can fail to insert an element only by throwing an exception.

size

remainingCapacity

public int remainingCapacity()

Returns the number of additional elements that this queue can ideally
(in the absence of memory or resource constraints) accept without
blocking. This is always equal to the initial capacity of this queue
less the current size of this queue.

Note that you cannot always tell if an attempt to insert
an element will succeed by inspecting remainingCapacity
because it may be the case that another thread is about to
insert or remove an element.

remove

Removes a single instance of the specified element from this queue,
if it is present. More formally, removes an element e such
that o.equals(e), if this queue contains one or more such
elements.
Returns true if this queue contained the specified element
(or equivalently, if this queue changed as a result of the call).

Removal of interior elements in circular array based queues
is an intrinsically slow and disruptive operation, so should
be undertaken only in exceptional circumstances, ideally
only when the queue is known not to be accessible by other
threads.

toArray

Returns an array containing all of the elements in this queue, in
proper sequence.

The returned array will be "safe" in that no references to it are
maintained by this queue. (In other words, this method must allocate
a new array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based
APIs.

toArray

public <T> T[] toArray(T[] a)

Returns an array containing all of the elements in this queue, in
proper sequence; the runtime type of the returned array is that of
the specified array. If the queue fits in the specified array, it
is returned therein. Otherwise, a new array is allocated with the
runtime type of the specified array and the size of this queue.

If this queue fits in the specified array with room to spare
(i.e., the array has more elements than this queue), the element in
the array immediately following the end of the queue is set to
null.

Like the toArray() method, this method acts as bridge between
array-based and collection-based APIs. Further, this method allows
precise control over the runtime type of the output array, and may,
under certain circumstances, be used to save allocation costs.

Suppose x is a queue known to contain only strings.
The following code can be used to dump the queue into a newly
allocated array of String:

String[] y = x.toArray(new String[0]);

Note that toArray(new Object[0]) is identical in function to
toArray().

drainTo

Removes all available elements from this queue and adds them
to the given collection. This operation may be more
efficient than repeatedly polling this queue. A failure
encountered while attempting to add elements to
collection c may result in elements being in neither,
either or both collections when the associated exception is
thrown. Attempts to drain a queue to itself result in
IllegalArgumentException. Further, the behavior of
this operation is undefined if the specified collection is
modified while the operation is in progress.

drainTo

Removes at most the given number of available elements from
this queue and adds them to the given collection. A failure
encountered while attempting to add elements to
collection c may result in elements being in neither,
either or both collections when the associated exception is
thrown. Attempts to drain a queue to itself result in
IllegalArgumentException. Further, the behavior of
this operation is undefined if the specified collection is
modified while the operation is in progress.