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:
    Serializable, Iterable, 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 14:33:15 +0200 (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

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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`

    - ### 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:
        `IllegalArgumentException` - if the buffer is null
        `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:
        `IllegalArgumentException` - if the buffer is null
        `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:
        `IllegalArgumentException` - if the buffer is null
        `IllegalArgumentException` - if the maximum size is zero or less

    - #### remove

          public 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(Object o)

      Specified by:
        `add` in interface `Collection`
      Overrides:
        `add` in class `SynchronizedCollection`

    - #### addAll

          public boolean addAll(Collection c)

      Specified by:
        `addAll` in interface `Collection`
      Overrides:
        `addAll` in class `SynchronizedCollection`

    - #### iterator

          public 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 `Iterable`
      Specified by:
        `iterator` in interface `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–2015 The Apache Software Foundation. All rights reserved.