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, 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, newCharSequenceOrigin, newFileOrigin, newFileOrigin, newInputStreamOrigin, newOutputStreamOrigin, newPathOrigin, newPathOrigin, newRandomAccessFileOrigin, newRandomAccessFileOrigin, newReaderOrigin, newURIOrigin, newWriterOrigin, setByteArray, 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 max 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.