## 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

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.