org.apache.commons.collections.buffer
Class BlockingBuffer

java.lang.Object
  org.apache.commons.collections.collection.SynchronizedCollection
      org.apache.commons.collections.buffer.SynchronizedBuffer
          org.apache.commons.collections.buffer.BlockingBuffer

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable, java.util.Collection, Buffer

public class BlockingBuffer
extends SynchronizedBuffer

Decorates another Buffer to make get() and remove() block when the Buffer is empty.

If either get or remove is called on an empty Buffer, the calling thread waits for notification that an add or addAll operation has completed.

When one or more entries are added to an empty Buffer, all threads blocked in get or remove are notified. There is no guarantee that concurrent blocked get or remove requests will be "unblocked" and receive data in the order that they arrive.

This class is Serializable from Commons Collections 3.1. This class contains an extra field in 3.2, however the serialization specification will handle this gracefully.

Since:

Commons Collections 3.0

Version:

$Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $

Author:

Stephen Colebourne, Janek Bogucki, Phil Steitz, James Carman

See Also:

Serialized Form

Field Summary

Fields inherited from class org.apache.commons.collections.collection.SynchronizedCollection

collection, lock

Constructor Summary

protected	BlockingBuffer(Buffer buffer) Constructor that wraps (not copies).
protected	BlockingBuffer(Buffer buffer, long timeoutMillis) Constructor that wraps (not copies).

Method Summary

boolean	add(java.lang.Object o)
boolean	addAll(java.util.Collection c)
static Buffer	decorate(Buffer buffer) Factory method to create a blocking buffer.
static Buffer	decorate(Buffer buffer, long timeoutMillis) Factory method to create a blocking buffer with a timeout value.
java.lang.Object	get() Gets the next value from the buffer, waiting until an object is added if the buffer is empty.
java.lang.Object	get(long timeout) Gets the next value from the buffer, waiting until an object is added for up to the specified timeout value if the buffer is empty.
java.lang.Object	remove() Removes the next value from the buffer, waiting until an object is added if the buffer is empty.
java.lang.Object	remove(long timeout) Removes the next value from the buffer, waiting until an object is added for up to the specified timeout value if the buffer is empty.

Methods inherited from class org.apache.commons.collections.buffer.SynchronizedBuffer

getBuffer

Methods inherited from class org.apache.commons.collections.collection.SynchronizedCollection

clear, contains, containsAll, decorate, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Constructor Detail

BlockingBuffer

protected BlockingBuffer(Buffer buffer)

Constructor that wraps (not copies).

Parameters:

buffer - the buffer to decorate, must not be null

Throws:

java.lang.IllegalArgumentException - if the buffer is null

BlockingBuffer

protected BlockingBuffer(Buffer buffer,
                         long timeoutMillis)

Constructor that wraps (not copies).

Parameters:

buffer - the buffer to decorate, must not be null

timeoutMillis - the timeout value in milliseconds, zero or less for no timeout

Throws:

java.lang.IllegalArgumentException - if the buffer is null

Since:

Commons Collections 3.2

Method Detail

decorate

public static Buffer decorate(Buffer buffer)

Factory method to create a blocking buffer.

Parameters:

buffer - the buffer to decorate, must not be null

Returns:

a new blocking Buffer

Throws:

java.lang.IllegalArgumentException - if buffer is null

decorate

public static Buffer decorate(Buffer buffer,
                              long timeoutMillis)

Factory method to create a blocking buffer with a timeout value.

Parameters:

buffer - the buffer to decorate, must not be null

timeoutMillis - the timeout value in milliseconds, zero or less for no timeout

Returns:

a new blocking buffer

Throws:

java.lang.IllegalArgumentException - if the buffer is null

Since:

Commons Collections 3.2

add

public boolean add(java.lang.Object o)

Specified by:

add in interface java.util.Collection

Overrides:

add in class SynchronizedCollection

addAll

public boolean addAll(java.util.Collection c)

Specified by:

addAll in interface java.util.Collection

Overrides:

addAll in class SynchronizedCollection

get

public java.lang.Object get()

Gets the next value from the buffer, waiting until an object is added if the buffer is empty. This method uses the default timeout set in the constructor.

Specified by:

get in interface Buffer

Overrides:

get in class SynchronizedBuffer

Returns:

the next object in the buffer, which is not removed

Throws:

BufferUnderflowException - if an interrupt is received

get

public java.lang.Object get(long timeout)

Gets the next value from the buffer, waiting until an object is added for up to the specified timeout value if the buffer is empty.

Parameters:

timeout - the timeout value in milliseconds

Throws:

BufferUnderflowException - if an interrupt is received

BufferUnderflowException - if the timeout expires

Since:

Commons Collections 3.2

remove

public java.lang.Object remove()

Removes the next value from the buffer, waiting until an object is added if the buffer is empty. This method uses the default timeout set in the constructor.

Specified by:

remove in interface Buffer

Overrides:

remove in class SynchronizedBuffer

Returns:

the next object in the buffer, which is also removed

Throws:

BufferUnderflowException - if an interrupt is received

remove

public java.lang.Object remove(long timeout)

Removes the next value from the buffer, waiting until an object is added for up to the specified timeout value if the buffer is empty.

Parameters:

timeout - the timeout value in milliseconds

Throws:

BufferUnderflowException - if an interrupt is received

BufferUnderflowException - if the timeout expires

Since:

Commons Collections 3.2