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

  See Also:
    `QueueInputStream.Builder`, `QueueOutputStream`

- - ### Nested Class Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `QueueInputStream()` Constructs a new instance with no limit to its internal queue size and zero timeout.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static QueueInputStream.Builder` | `builder()` Constructs a new `QueueInputStream.Builder`.
    `(package private) BlockingQueue<Integer>` | `getBlockingQueue()` Gets the blocking queue.
    `(package private) java.time.Duration` | `getTimeout()` Gets the timeout duration.
    `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 Detail

    - #### QueueInputStream

          public QueueInputStream()

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

  - ### Method Detail

    - #### builder

          public static QueueInputStream.Builder builder()

      Constructs a new `QueueInputStream.Builder`.
      Returns:
        a new `QueueInputStream.Builder`.

    - #### getBlockingQueue

          BlockingQueue<Integer> getBlockingQueue()

      Gets the blocking queue.
      Returns:
        the blocking queue.

    - #### getTimeout

          java.time.Duration getTimeout()

      Gets the timeout duration.
      Returns:
        the timeout duration.

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