Package 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 maximum count reached

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

Since:
  2.0
See Also:
  - `BoundedInputStream.Builder`

- ## Nested Class Summary

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

- ## Field Summary

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

  `in`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BoundedInputStream(InputStream in)`
  Deprecated.
  Use `IOSupplier.get()`.
  `BoundedInputStream(InputStream inputStream, long maxCount)`
  Deprecated.
  Use `IOSupplier.get()`.

- ## Method Summary

  Modifier and Type
  Method
  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 maximum number of bytes to read.
  `long`
  `getMaxLength()`
  Deprecated.
  Use `getMaxCount()`.
  `long`
  `getRemaining()`
  Gets the number of bytes remaining to read before the maximum is reached.
  `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.
  `void`
  `setPropagateClose(boolean propagateClose)`
  Deprecated.
  Use `BoundedInputStream.AbstractBuilder.setPropagateClose(boolean)`.
  `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, handleIOException, setReference, unwrap`

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

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

- ## Constructor Details

  - ### BoundedInputStream

    @Deprecated public BoundedInputStream(InputStream in)
    Deprecated.
    Use `IOSupplier.get()`.
    Constructs a new `BoundedInputStream` that wraps the given input stream and is unbounded.

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

    Parameters:
      `in` - The wrapped input stream.

  - ### BoundedInputStream

    @Deprecated public BoundedInputStream(InputStream inputStream, long maxCount)
    Deprecated.
    Use `IOSupplier.get()`.
    Constructs a new `BoundedInputStream` that wraps the given input stream and limits it to a certain size.
    Parameters:
      `inputStream` - The wrapped input stream.
      `maxCount` - The maximum number of bytes to return, negative means unbound.

- ## Method Details

  - ### builder

    public static BoundedInputStream.Builder builder()
    Constructs a new `BoundedInputStream.AbstractBuilder`.
    Returns:
      a new `BoundedInputStream.AbstractBuilder`.
    Since:
      2.16.0

  - ### 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.
    Since:
      2.0

  - ### available

    public int available() throws IOException
    Description copied from class: `ProxyInputStream`
    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.

  - ### close

    public void close() throws IOException
    Invokes the delegate's `InputStream.close()` method if `isPropagateClose()` is `true`.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    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.
    Since:
      2.12.0

  - ### getMaxCount

    public long getMaxCount()
    Gets the maximum number of bytes to read.
    Returns:
      The maximum number of bytes to read, or -1 if unbounded.
    Since:
      2.16.0

  - ### getMaxLength

    @Deprecated public long getMaxLength()
    Deprecated.
    Use `getMaxCount()`.
    Gets the maximum count of bytes to read.
    Returns:
      The maximum count of bytes to read.
    Since:
      2.12.0

  - ### getRemaining

    public long getRemaining()
    Gets the number of bytes remaining to read before the maximum is reached.

    This method does not report the bytes available in the underlying stream; it only reflects the remaining allowance imposed by this `BoundedInputStream`.

    Returns:
      The number of bytes remaining to read before the maximum is reached, or `Long.MAX_VALUE` if no bound is set.
    Since:
      2.16.0

  - ### 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 maximum count of bytes to read.
      `count` - The count of bytes read.
    Throws:
      `IOException` - Subclasses may throw.
    Since:
      2.12.0

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

  - ### setPropagateClose

    @Deprecated public void setPropagateClose(boolean propagateClose)
    Deprecated.
    Use `BoundedInputStream.AbstractBuilder.setPropagateClose(boolean)`.
    Sets whether the `close()` method should propagate to the underling `InputStream`.
    Parameters:
      `propagateClose` - `true` if calling `close()` propagates to the `close()` method of the underlying stream or `false` if it does not.

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