org.apache.commons.collections.buffer
Class BoundedBuffer

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

All Implemented Interfaces:

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

public class BoundedBuffer
extends SynchronizedBuffer
implements BoundedCollection

Decorates another Buffer to ensure a fixed maximum size.

Note: This class should only be used if you need to add bounded behaviour to another buffer. If you just want a bounded buffer then you should use BoundedFifoBuffer or CircularFifoBuffer.

The decoration methods allow you to specify a timeout value. This alters the behaviour of the add methods when the buffer is full. Normally, when the buffer is full, the add method will throw an exception. With a timeout, the add methods will wait for up to the timeout period to try and add the elements.

Since:

Commons Collections 3.2

Version:

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

Author:

James Carman, Stephen Colebourne

See Also:

Serialized Form

Field Summary

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

collection, lock

Constructor Summary

protected

BoundedBuffer(Buffer buffer, int maximumSize, long timeout) Constructor that wraps (not copies) another buffer, making it bounded waiting only up to a maximum amount of time.

Method Summary

boolean	add(java.lang.Object o)
boolean	addAll(java.util.Collection c)
static BoundedBuffer	decorate(Buffer buffer, int maximumSize) Factory method to create a bounded buffer.
static BoundedBuffer	decorate(Buffer buffer, int maximumSize, long timeout) Factory method to create a bounded buffer that blocks for a maximum amount of time.
boolean	isFull() Returns true if this collection is full and no new elements can be added.
java.util.Iterator	iterator() Iterators must be manually synchronized.
int	maxSize() Gets the maximum size of the collection (the bound).
java.lang.Object	remove() Gets and removes the next object from the buffer.

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

decorate, get, getBuffer

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

clear, contains, containsAll, decorate, equals, hashCode, isEmpty, 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, remove, removeAll, retainAll, size, toArray, toArray

Constructor Detail

BoundedBuffer

protected BoundedBuffer(Buffer buffer,
                        int maximumSize,
                        long timeout)

Constructor that wraps (not copies) another buffer, making it bounded waiting only up to a maximum amount of time.

Parameters:

buffer - the buffer to wrap, must not be null

maximumSize - the maximum size, must be size one or greater

timeout - the maximum amount of time to wait

Throws:

java.lang.IllegalArgumentException - if the buffer is null

java.lang.IllegalArgumentException - if the maximum size is zero or less

Method Detail

decorate

public static BoundedBuffer decorate(Buffer buffer,
                                     int maximumSize)

Factory method to create a bounded buffer.

When the buffer is full, it will immediately throw a BufferOverflowException on calling add().

Parameters:

buffer - the buffer to decorate, must not be null

maximumSize - the maximum size, must be size one or greater

Returns:

a new bounded buffer

Throws:

java.lang.IllegalArgumentException - if the buffer is null

java.lang.IllegalArgumentException - if the maximum size is zero or less

decorate

public static BoundedBuffer decorate(Buffer buffer,
                                     int maximumSize,
                                     long timeout)

Factory method to create a bounded buffer that blocks for a maximum amount of time.

Parameters:

buffer - the buffer to decorate, must not be null

maximumSize - the maximum size, must be size one or greater

timeout - the maximum amount of time to wait in milliseconds

Returns:

a new bounded buffer

Throws:

java.lang.IllegalArgumentException - if the buffer is null

java.lang.IllegalArgumentException - if the maximum size is zero or less

remove

public java.lang.Object remove()

Description copied from interface: Buffer

Gets and removes the next object from the buffer.

Specified by:

remove in interface Buffer

Overrides:

remove in class SynchronizedBuffer

Returns:

the next object in the buffer, which is also removed

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

iterator

public java.util.Iterator iterator()

Description copied from class: SynchronizedCollection

Iterators must be manually synchronized.

 synchronized (coll) {
   Iterator it = coll.iterator();
   // do stuff with iterator
 }


Specified by:
iterator in interface java.lang.Iterable
Specified by:
iterator in interface java.util.Collection
Overrides:
iterator in class SynchronizedCollection



Returns:
an iterator that must be manually synchronized on the collection

isFull

public boolean isFull()

Description copied from interface: BoundedCollection

Returns true if this collection is full and no new elements can be added.

Specified by:

isFull in interface BoundedCollection

Returns:

true if the collection is full

maxSize

public int maxSize()

Description copied from interface: BoundedCollection

Gets the maximum size of the collection (the bound).

Specified by:

maxSize in interface BoundedCollection

Returns:

the maximum number of elements the collection can hold