org.apache.commons.collections.buffer

Class BoundedBuffer

Implemented Interfaces:
BoundedCollection, Collection, Buffer, Serializable

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.

Version:
$Revision: 405927 $ $Date: 2006-05-12 23:57:03 +0100 (Fri, 12 May 2006) $
Authors:
James Carman
Stephen Colebourne
Since:
Commons Collections 3.2

Field Summary

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

collection, lock

Constructor Summary

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(Object o)
boolean
addAll(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.
Iterator
iterator()
Iterators must be manually synchronized.
int
maxSize()
Gets the maximum size of the collection (the bound).
Object
remove()
Gets and removes the next object from the buffer.

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

decorate, get, getBuffer, remove

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

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

Constructor Details

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

Method Details

add

public boolean add(Object o)
Overrides:
add in interface SynchronizedCollection

addAll

public boolean addAll(Collection c)
Overrides:
addAll in interface SynchronizedCollection

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

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

isFull

public boolean isFull()
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

iterator

public Iterator iterator()
Iterators must be manually synchronized.
 synchronized (coll) {
   Iterator it = coll.iterator();
   // do stuff with iterator
 }
Overrides:
iterator in interface SynchronizedCollection
Returns:
an iterator that must be manually synchronized on the collection

maxSize

public int maxSize()
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

remove

public Object remove()
Gets and removes the next object from the buffer.
Specified by:
remove in interface Buffer
Overrides:
remove in interface SynchronizedBuffer
Returns:
the next object in the buffer, which is also removed

Copyright © 2001-2006 Apache Software Foundation. All Rights Reserved.