Package org.apache.commons.io.input

# Class QueueInputStream

java.lang.Object
java.io.InputStream
org.apache.commons.io.input.QueueInputStream

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public class QueueInputStream extends InputStream
Simple alternative to JDK `PipedInputStream`; queue input stream provides what's written in queue output stream.

To build an instance, use `QueueInputStream.Builder`.

Example usage:

     QueueInputStream inputStream = new QueueInputStream();
     QueueOutputStream outputStream = inputStream.newQueueOutputStream();

     outputStream.write("hello world".getBytes(UTF_8));
     inputStream.read();

Unlike JDK `PipedInputStream` and `PipedOutputStream`, queue input/output streams may be used safely in a single thread or multiple threads. Also, unlike JDK classes, no special meaning is attached to initial or current thread. Instances can be used longer after initial threads exited.

Closing a `QueueInputStream` has no effect. The methods in this class can be called after the stream has been closed without generating an `IOException`.

Since:
  2.9.0
See Also:
  - `QueueInputStream.Builder`
  - `QueueOutputStream`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `QueueInputStream.Builder`
  Builds a new `QueueInputStream`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `QueueInputStream()`
  Constructs a new instance with no limit to its internal queue size and zero timeout.
  `QueueInputStream(BlockingQueue<Integer> blockingQueue)`
  Deprecated.
  Use `builder()`, `QueueInputStream.Builder`, and `QueueInputStream.Builder.get()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static QueueInputStream.Builder`
  `builder()`
  Constructs a new `QueueInputStream.Builder`.
  `QueueOutputStream`
  `newQueueOutputStream()`
  Constructs a new QueueOutputStream instance connected to this.
  `int`
  `read()`
  Reads and returns a single byte.
  `int`
  `read(byte[] b, int offset, int length)`
  Reads up to `length` bytes of data from the input stream into an array of bytes.

  ### Methods inherited from class java.io.InputStream

  `available, close, mark, markSupported, read, reset, skip`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### QueueInputStream

    public QueueInputStream()
    Constructs a new instance with no limit to its internal queue size and zero timeout.

  - ### QueueInputStream

    @Deprecated public QueueInputStream(BlockingQueue<Integer> blockingQueue)
    Deprecated.
    Use `builder()`, `QueueInputStream.Builder`, and `QueueInputStream.Builder.get()`.
    Constructs a new instance with given queue and zero timeout.
    Parameters:
      `blockingQueue` - backing queue for the stream, null maps to a new blocking queue instance.

- ## Method Details

  - ### builder

    public static QueueInputStream.Builder builder()
    Constructs a new `QueueInputStream.Builder`.
    Returns:
      a new `QueueInputStream.Builder`.
    Since:
      2.12.0

  - ### newQueueOutputStream

    public QueueOutputStream newQueueOutputStream()
    Constructs a new QueueOutputStream instance connected to this. Writes to the output stream will be visible to this input stream.
    Returns:
      QueueOutputStream connected to this stream.

  - ### read

    public int read()
    Reads and returns a single byte.
    Specified by:
      `read` in class `InputStream`
    Returns:
      the byte read, or `-1` if a timeout occurs before a queue element is available.
    Throws:
      `IllegalStateException` - if thread is interrupted while waiting.

  - ### read

    public int read(byte[] b, int offset, int length)
    Reads up to `length` bytes of data from the input stream into an array of bytes. The first byte is read while honoring the timeout; the rest are read while not honoring the timeout. The number of bytes actually read is returned as an integer.
    Overrides:
      `read` in class `InputStream`
    Parameters:
      `b` - the buffer into which the data is read.
      `offset` - the start offset in array `b` at which the data is written.
      `length` - the maximum number of bytes to read.
    Returns:
      the total number of bytes read into the buffer, or `-1` if there is no more data because the end of the stream has been reached.
    Throws:
      `NullPointerException` - If `b` is `null`.
      `IllegalStateException` - if thread is interrupted while waiting for the first byte.
      `IndexOutOfBoundsException` - if `offset` is negative, `length` is negative, or `length` is greater than `b.length - offset`.
    Since:
      2.20.0