org.apache.commons.collections.buffer

## Class BlockingBuffer

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

- All Implemented Interfaces:
    Serializable, Iterable, Collection, Buffer

      public class BlockingBuffer
      extends SynchronizedBuffer

  Decorates another `Buffer` to make `get()` and `remove()` block when the `Buffer` is empty.

  If either `get` or `remove` is called on an empty `Buffer`, the calling thread waits for notification that an `add` or `addAll` operation has completed.

  When one or more entries are added to an empty `Buffer`, all threads blocked in `get` or `remove` are notified. There is no guarantee that concurrent blocked `get` or `remove` requests will be "unblocked" and receive data in the order that they arrive.

  This class is Serializable from Commons Collections 3.1. This class contains an extra field in 3.2, however the serialization specification will handle this gracefully.

  Since:
    Commons Collections 3.0
  Version:
    $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
  Author:
    Stephen Colebourne, Janek Bogucki, Phil Steitz, James Carman
  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` | `BlockingBuffer(Buffer buffer)` Constructor that wraps (not copies).
    `protected` | `BlockingBuffer(Buffer buffer, long timeoutMillis)` Constructor that wraps (not copies).

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(Object o)`
    `boolean` | `addAll(Collection c)`
    `static Buffer` | `decorate(Buffer buffer)` Factory method to create a blocking buffer.
    `static Buffer` | `decorate(Buffer buffer, long timeoutMillis)` Factory method to create a blocking buffer with a timeout value.
    `Object` | `get()` Gets the next value from the buffer, waiting until an object is added if the buffer is empty.
    `Object` | `get(long timeout)` Gets the next value from the buffer, waiting until an object is added for up to the specified timeout value if the buffer is empty.
    `Object` | `remove()` Removes the next value from the buffer, waiting until an object is added if the buffer is empty.
    `Object` | `remove(long timeout)` Removes the next value from the buffer, waiting until an object is added for up to the specified timeout value if the buffer is empty.

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

      `getBuffer`

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

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

- - ### Constructor Detail

    - #### BlockingBuffer

          protected BlockingBuffer(Buffer buffer)

      Constructor that wraps (not copies).
      Parameters:
        `buffer` - the buffer to decorate, must not be null
      Throws:
        `IllegalArgumentException` - if the buffer is null

    - #### BlockingBuffer

          protected BlockingBuffer(Buffer buffer,
                        long timeoutMillis)

      Constructor that wraps (not copies).
      Parameters:
        `buffer` - the buffer to decorate, must not be null
        `timeoutMillis` - the timeout value in milliseconds, zero or less for no timeout
      Throws:
        `IllegalArgumentException` - if the buffer is null
      Since:
        Commons Collections 3.2

  - ### Method Detail

    - #### decorate

          public static Buffer decorate(Buffer buffer)

      Factory method to create a blocking buffer.
      Parameters:
        `buffer` - the buffer to decorate, must not be null
      Returns:
        a new blocking Buffer
      Throws:
        `IllegalArgumentException` - if buffer is null

    - #### decorate

          public static Buffer decorate(Buffer buffer,
                        long timeoutMillis)

      Factory method to create a blocking buffer with a timeout value.
      Parameters:
        `buffer` - the buffer to decorate, must not be null
        `timeoutMillis` - the timeout value in milliseconds, zero or less for no timeout
      Returns:
        a new blocking buffer
      Throws:
        `IllegalArgumentException` - if the buffer is null
      Since:
        Commons Collections 3.2

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

    - #### get

          public Object get()

      Gets the next value from the buffer, waiting until an object is added if the buffer is empty. This method uses the default timeout set in the constructor.
      Specified by:
        `get` in interface `Buffer`
      Overrides:
        `get` in class `SynchronizedBuffer`
      Returns:
        the next object in the buffer, which is not removed
      Throws:
        `BufferUnderflowException` - if an interrupt is received

    - #### get

          public Object get(long timeout)

      Gets the next value from the buffer, waiting until an object is added for up to the specified timeout value if the buffer is empty.
      Parameters:
        `timeout` - the timeout value in milliseconds
      Throws:
        `BufferUnderflowException` - if an interrupt is received
        `BufferUnderflowException` - if the timeout expires
      Since:
        Commons Collections 3.2

    - #### remove

          public Object remove()

      Removes the next value from the buffer, waiting until an object is added if the buffer is empty. This method uses the default timeout set in the constructor.
      Specified by:
        `remove` in interface `Buffer`
      Overrides:
        `remove` in class `SynchronizedBuffer`
      Returns:
        the next object in the buffer, which is also removed
      Throws:
        `BufferUnderflowException` - if an interrupt is received

    - #### remove

          public Object remove(long timeout)

      Removes the next value from the buffer, waiting until an object is added for up to the specified timeout value if the buffer is empty.
      Parameters:
        `timeout` - the timeout value in milliseconds
      Throws:
        `BufferUnderflowException` - if an interrupt is received
        `BufferUnderflowException` - if the timeout expires
      Since:
        Commons Collections 3.2

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.