org.apache.commons.io.input

## Class BoundedInputStream.Builder

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

- All Implemented Interfaces:
    IOSupplier<BoundedInputStream>
  Enclosing class:
    BoundedInputStream

      public static class BoundedInputStream.Builder
      extends BoundedInputStream.AbstractBuilder<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();

  See Also:
    `get()`

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `BoundedInputStream` | `get()` Builds a new `BoundedInputStream`.

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

      `getCount, getMaxCount, getOnMaxCount, isPropagateClose, setCount, setMaxCount, setOnMaxCount, setPropagateClose`

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

    - #### Builder

          public Builder()

      Constructs a new builder of `BoundedInputStream`.

  - ### Method Detail

    - #### 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()`
      - `BoundedInputStream.AbstractBuilder.getCount()`
      - `BoundedInputStream.AbstractBuilder.getMaxCount()`
      - `BoundedInputStream.AbstractBuilder.getOnMaxCount()`
      - `BoundedInputStream.AbstractBuilder.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()`