Package org.apache.commons.collections.buffer

Class 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 14:33:15 +0200 (Thu, 10 Apr 2008) $
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Modifier Constructor 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.

    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        The serialization version.
        See Also:
        Constant Field Values

      • maximumSize

        private final int maximumSize
        The maximum size.

      • timeout

        private final long timeout
        The timeout milliseconds.

    • 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.util.Collection
        Specified by:
        iterator in interface java.lang.Iterable
        Overrides:
        iterator in class SynchronizedCollection
        Returns:
        an iterator that must be manually synchronized on the collection

      • timeoutWait

        private void timeoutWait​(int nAdditions)

      • 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