org.apache.commons.io.input

## Class BoundedInputStream

- java.lang.Object
- - java.io.InputStream
  - - java.io.FilterInputStream
    - - org.apache.commons.io.input.ProxyInputStream
      - - org.apache.commons.io.input.BoundedInputStream

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public class BoundedInputStream
      extends ProxyInputStream

  Reads bytes up to a maximum count and stops once reached.

  To build an instance: Use the `builder()` to access all features.

  By default, a `BoundedInputStream` is unbound; so make sure to call `BoundedInputStream.AbstractBuilder.setMaxCount(long)`.

  You can find out how many bytes this stream has seen so far by calling `getCount()`. This value reflects bytes read and skipped.

  ## Using a ServletInputStream

  A `ServletInputStream` can block if you try to read content that isn't there because it doesn't know whether the content hasn't arrived yet or whether the content has finished. Initialize an `BoundedInputStream` with the `Content-Length` sent in the `ServletInputStream`'s header, this stop it from blocking, providing it's been sent with a correct content length in the first place.

  ## Using NIO

       BoundedInputStream s = BoundedInputStream.builder()
         .setPath(Paths.get("MyFile.xml"))
         .setMaxCount(1024)
         .setPropagateClose(false)
         .get();

  ## Using IO

       BoundedInputStream s = BoundedInputStream.builder()
         .setFile(new File("MyFile.xml"))
         .setMaxCount(1024)
         .setPropagateClose(false)
         .get();

  ## Counting Bytes

  You can set the running count when building, which is most useful when starting from another stream:

       InputStream in = ...;
       BoundedInputStream s = BoundedInputStream.builder()
         .setInputStream(in)
         .setCount(12)
         .setMaxCount(1024)
         .setPropagateClose(false)
         .get();

  ## Listening for the max count reached

       BoundedInputStream s = BoundedInputStream.builder()
         .setPath(Paths.get("MyFile.xml"))
         .setMaxCount(1024)
         .setOnMaxCount((max, count) -> System.out.printf("Max count %,d reached with a last read count of %,d%n", max, count))
         .get();

  See Also:
    `BoundedInputStream.Builder`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static class` | `BoundedInputStream.AbstractBuilder<T extends BoundedInputStream.AbstractBuilder<T>>` For subclassing builders from `BoundedInputStream` subclassses.
    `static class` | `BoundedInputStream.Builder` Builds a new `BoundedInputStream`.

  - ### Field Summary

    - ### Fields inherited from class java.io.FilterInputStream

      `in`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BoundedInputStream(BoundedInputStream.Builder builder)`
    `BoundedInputStream(InputStream inputStream, BoundedInputStream.Builder builder)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `afterRead(int n)` Adds the number of read bytes to the count.
    `int` | `available()` Invokes the delegate's `InputStream.available()` method.
    `static BoundedInputStream.Builder` | `builder()` Constructs a new `BoundedInputStream.AbstractBuilder`.
    `void` | `close()` Invokes the delegate's `InputStream.close()` method if `isPropagateClose()` is `true`.
    `long` | `getCount()` Gets the count of bytes read.
    `long` | `getMaxCount()` Gets the max count of bytes to read.
    `long` | `getRemaining()` Gets how many bytes remain to read.
    `boolean` | `isPropagateClose()` Tests whether the `close()` method should propagate to the underling `InputStream`.
    `void` | `mark(int readLimit)` Invokes the delegate's `InputStream.mark(int)` method.
    `boolean` | `markSupported()` Invokes the delegate's `InputStream.markSupported()` method.
    `protected void` | `onMaxLength(long max, long count)` A caller has caused a request that would cross the `maxLength` boundary.
    `int` | `read()` Invokes the delegate's `InputStream.read()` method if the current position is less than the limit.
    `int` | `read(byte[] b)` Invokes the delegate's `InputStream.read(byte[])` method.
    `int` | `read(byte[] b, int off, int len)` Invokes the delegate's `InputStream.read(byte[], int, int)` method.
    `void` | `reset()` Invokes the delegate's `InputStream.reset()` method.
    `long` | `skip(long n)` Invokes the delegate's `InputStream.skip(long)` method.
    `String` | `toString()` Invokes the delegate's `Object.toString()` method.

    - ### Methods inherited from class org.apache.commons.io.input.ProxyInputStream

      `beforeRead, checkOpen, handleIOException, isClosed, setReference, unwrap`

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

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

- - ### Constructor Detail

    - #### BoundedInputStream

          BoundedInputStream(BoundedInputStream.Builder builder)
                      throws IOException

      Throws:
        `IOException`

    - #### BoundedInputStream

          BoundedInputStream(InputStream inputStream,
                             BoundedInputStream.Builder builder)

  - ### Method Detail

    - #### afterRead

          protected void afterRead(int n)
                            throws IOException

      Adds the number of read bytes to the count.
      Overrides:
        `afterRead` in class `ProxyInputStream`
      Parameters:
        `n` - number of bytes read, or -1 if no more bytes are available
      Throws:
        `IOException` - Not thrown here but subclasses may throw.

    - #### available

          public int available()
                        throws IOException

      Invokes the delegate's `InputStream.available()` method.
      Overrides:
        `available` in class `ProxyInputStream`
      Returns:
        the number of available bytes, 0 if the stream is closed.
      Throws:
        `IOException` - if an I/O error occurs.

    - #### builder

          public static BoundedInputStream.Builder builder()

      Constructs a new `BoundedInputStream.AbstractBuilder`.
      Returns:
        a new `BoundedInputStream.AbstractBuilder`.

    - #### close

          public void close()
                     throws IOException

      Invokes the delegate's `InputStream.close()` method if `isPropagateClose()` is `true`.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Overrides:
        `close` in class `ProxyInputStream`
      Throws:
        `IOException` - if an I/O error occurs.

    - #### getCount

          public long getCount()

      Gets the count of bytes read.
      Returns:
        The count of bytes read.

    - #### getMaxCount

          public long getMaxCount()

      Gets the max count of bytes to read.
      Returns:
        The max count of bytes to read.

    - #### getRemaining

          public long getRemaining()

      Gets how many bytes remain to read.
      Returns:
        bytes how many bytes remain to read.

    - #### isPropagateClose

          public boolean isPropagateClose()

      Tests whether the `close()` method should propagate to the underling `InputStream`.
      Returns:
        `true` if calling `close()` propagates to the `close()` method of the underlying stream or `false` if it does not.

    - #### mark

          public void mark(int readLimit)

      Invokes the delegate's `InputStream.mark(int)` method.
      Overrides:
        `mark` in class `ProxyInputStream`
      Parameters:
        `readLimit` - read ahead limit

    - #### markSupported

          public boolean markSupported()

      Invokes the delegate's `InputStream.markSupported()` method.
      Overrides:
        `markSupported` in class `ProxyInputStream`
      Returns:
        true if mark is supported, otherwise false
      See Also:
        `ProxyInputStream.mark(int)`, `ProxyInputStream.reset()`

    - #### onMaxLength

          protected void onMaxLength(long max,
                                     long count)
                              throws IOException

      A caller has caused a request that would cross the `maxLength` boundary.

      Delegates to the consumer set in `BoundedInputStream.AbstractBuilder.setOnMaxCount(IOBiConsumer)`.

      Parameters:
        `max` - The max count of bytes to read.
        `count` - The count of bytes read.
      Throws:
        `IOException` - Subclasses may throw.

    - #### read

          public int read()
                   throws IOException

      Invokes the delegate's `InputStream.read()` method if the current position is less than the limit.
      Overrides:
        `read` in class `ProxyInputStream`
      Returns:
        the byte read or -1 if the end of stream or the limit has been reached.
      Throws:
        `IOException` - if an I/O error occurs.

    - #### read

          public int read(byte[] b)
                   throws IOException

      Invokes the delegate's `InputStream.read(byte[])` method.
      Overrides:
        `read` in class `ProxyInputStream`
      Parameters:
        `b` - the buffer to read the bytes into
      Returns:
        the number of bytes read or -1 if the end of stream or the limit has been reached.
      Throws:
        `IOException` - if an I/O error occurs.

    - #### read

          public int read(byte[] b,
                          int off,
                          int len)
                   throws IOException

      Invokes the delegate's `InputStream.read(byte[], int, int)` method.
      Overrides:
        `read` in class `ProxyInputStream`
      Parameters:
        `b` - the buffer to read the bytes into
        `off` - The start offset
        `len` - The number of bytes to read
      Returns:
        the number of bytes read or -1 if the end of stream or the limit has been reached.
      Throws:
        `IOException` - if an I/O error occurs.

    - #### reset

          public void reset()
                     throws IOException

      Invokes the delegate's `InputStream.reset()` method.
      Overrides:
        `reset` in class `ProxyInputStream`
      Throws:
        `IOException` - if an I/O error occurs.

    - #### skip

          public long skip(long n)
                    throws IOException

      Invokes the delegate's `InputStream.skip(long)` method.
      Overrides:
        `skip` in class `ProxyInputStream`
      Parameters:
        `n` - the number of bytes to skip
      Returns:
        the actual number of bytes skipped
      Throws:
        `IOException` - if an I/O error occurs.

    - #### toString

          public String toString()

      Invokes the delegate's `Object.toString()` method.
      Overrides:
        `toString` in class `Object`
      Returns:
        the delegate's `Object.toString()`