Package org.apache.commons.io.input

# Class BoundedInputStream.Builder

java.lang.Object
org.apache.commons.io.build.AbstractSupplier<BoundedInputStream,BoundedInputStream.Builder>
org.apache.commons.io.build.AbstractOriginSupplier<BoundedInputStream,BoundedInputStream.Builder>
org.apache.commons.io.build.AbstractStreamBuilder<BoundedInputStream,BoundedInputStream.Builder>
org.apache.commons.io.input.ProxyInputStream.AbstractBuilder<BoundedInputStream,BoundedInputStream.Builder>
org.apache.commons.io.input.BoundedInputStream.Builder

All Implemented Interfaces:
  `IOSupplier<BoundedInputStream>`

Enclosing class:
  `BoundedInputStream`

public static class BoundedInputStream.Builder extends ProxyInputStream.AbstractBuilder<BoundedInputStream,BoundedInputStream.Builder>
Builds a new `BoundedInputStream`.

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

Since:
  2.16.0
See Also:
  - `get()`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Builder()`
  Constructs a new builder of `BoundedInputStream`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `BoundedInputStream`
  `get()`
  Builds a new `BoundedInputStream`.
  `BoundedInputStream.Builder`
  `setCount(long count)`
  Sets the current number of bytes counted.
  `BoundedInputStream.Builder`
  `setMaxCount(long maxCount)`
  Sets the maximum number of bytes to return.
  `BoundedInputStream.Builder`
  `setOnMaxCount(IOBiConsumer<Long,Long> onMaxCount)`
  Sets the default `BoundedInputStream.onMaxLength(long, long)` behavior, `null` resets to a NOOP.
  `BoundedInputStream.Builder`
  `setPropagateClose(boolean propagateClose)`
  Sets whether the `ProxyInputStream.close()` method should propagate to the underling `InputStream`.

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

  `getAfterRead, setAfterRead`

  ### Methods inherited from class org.apache.commons.io.build.AbstractStreamBuilder

  `getBufferSize, getBufferSizeDefault, getByteArray, getChannel, getCharSequence, getCharset, getCharsetDefault, getFile, getInputStream, getOpenOptions, getOutputStream, getPath, getRandomAccessFile, getReader, getWriter, setBufferSize, setBufferSize, setBufferSizeChecker, setBufferSizeDefault, setBufferSizeMax, setCharset, setCharset, setCharsetDefault, setOpenOptions`

  ### Methods inherited from class org.apache.commons.io.build.AbstractOriginSupplier

  `checkOrigin, getOrigin, hasOrigin, newByteArrayOrigin, newChannelOrigin, newCharSequenceOrigin, newFileOrigin, newFileOrigin, newInputStreamOrigin, newOutputStreamOrigin, newPathOrigin, newPathOrigin, newRandomAccessFileOrigin, newRandomAccessFileOrigin, newReaderOrigin, newURIOrigin, newWriterOrigin, setByteArray, setChannel, setCharSequence, setFile, setFile, setInputStream, setOrigin, setOutputStream, setPath, setPath, setRandomAccessFile, setRandomAccessFile, setReader, setURI, setWriter`

  ### Methods inherited from class org.apache.commons.io.build.AbstractSupplier

  `asThis`

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

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

  ### Methods inherited from interface org.apache.commons.io.function.IOSupplier

  `asSupplier, getUnchecked`

- ## Constructor Details

  - ### Builder

    public Builder()
    Constructs a new builder of `BoundedInputStream`.

- ## Method Details

  - ### get

    public BoundedInputStream get() throws IOException
    Builds a new `BoundedInputStream`.

    You must set an aspect that supports `AbstractStreamBuilder.getInputStream()`, otherwise, this method throws an exception.

    If you start from an input stream, an exception can't be thrown, and you can call `IOSupplier.getUnchecked()` instead.

    This builder uses the following aspects:

    - `AbstractStreamBuilder.getInputStream()` gets the target aspect.
    - `ProxyInputStream.AbstractBuilder.getAfterRead()`
    - `#getCount()`
    - `#getMaxCount()`
    - `#getOnMaxCount()`
    - `#isPropagateClose()`
    Returns:
      a new instance.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to an `InputStream`.
      `IOException` - if an I/O error occurs converting to an `InputStream` using `AbstractStreamBuilder.getInputStream()`.
    See Also:
      - `AbstractStreamBuilder.getInputStream()`
      - `IOSupplier.getUnchecked()`

  - ### setCount

    public BoundedInputStream.Builder setCount(long count)
    Sets the current number of bytes counted.

    Useful when building from another stream to carry forward a read count.

    Default is `0`, negative means 0.

    Parameters:
      `count` - The current number of bytes counted.
    Returns:
      `this` instance.

  - ### setMaxCount

    public BoundedInputStream.Builder setMaxCount(long maxCount)
    Sets the maximum number of bytes to return.

    Default is -1, negative means unbound.

    Parameters:
      `maxCount` - The maximum number of bytes to return, negative means unbound.
    Returns:
      `this` instance.

  - ### setOnMaxCount

    public BoundedInputStream.Builder setOnMaxCount(IOBiConsumer<Long,Long> onMaxCount)
    Sets the default `BoundedInputStream.onMaxLength(long, long)` behavior, `null` resets to a NOOP.

    The first Long is the number of bytes remaining to read before the maximum is reached count of bytes to read. The second Long is the count of bytes read.

    This does not override a `BoundedInputStream` subclass' implementation of the `BoundedInputStream.onMaxLength(long, long)` method.

    Parameters:
      `onMaxCount` - the `ProxyInputStream.afterRead(int)` behavior.
    Returns:
      `this` instance.
    Since:
      2.18.0

  - ### setPropagateClose

    public BoundedInputStream.Builder setPropagateClose(boolean propagateClose)
    Sets whether the `ProxyInputStream.close()` method should propagate to the underling `InputStream`.

    Default is `true`.

    Parameters:
      `propagateClose` - `true` if calling `ProxyInputStream.close()` propagates to the `close()` method of the underlying stream or `false` if it does not.
    Returns:
      `this` instance.