org.apache.commons.io.input

## Class ChecksumInputStream.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<ChecksumInputStream,ChecksumInputStream.Builder>
        - - org.apache.commons.io.input.ChecksumInputStream.Builder

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

      public static class ChecksumInputStream.Builder
      extends ProxyInputStream.AbstractBuilder<ChecksumInputStream,ChecksumInputStream.Builder>

  Builds a new `ChecksumInputStream`.

  There is no default `Checksum`; you MUST provide one. This avoids any issue with a default `Checksum` being proven deficient or insecure in the future.

  ## Using NIO

       ChecksumInputStream s = ChecksumInputStream.builder()
         .setPath(Paths.get("MyFile.xml"))
         .setChecksum(new CRC32())
         .setExpectedChecksumValue(12345)
         .get();

  ## Using IO

       ChecksumInputStream s = ChecksumInputStream.builder()
         .setFile(new File("MyFile.xml"))
         .setChecksum(new CRC32())
         .setExpectedChecksumValue(12345)
         .get();

  ## Validating only part of an InputStream

  The following validates the first 100 bytes of the given input.

       ChecksumInputStream s = ChecksumInputStream.builder()
         .setPath(Paths.get("MyFile.xml"))
         .setChecksum(new CRC32())
         .setExpectedChecksumValue(12345)
         .setCountThreshold(100)
         .get();

  To validate input after the beginning of a stream, build an instance with an InputStream starting where you want to validate.

       InputStream inputStream = ...;
       inputStream.read(...);
       inputStream.skip(...);
       ChecksumInputStream s = ChecksumInputStream.builder()
         .setInputStream(inputStream)
         .setChecksum(new CRC32())
         .setExpectedChecksumValue(12345)
         .setCountThreshold(100)
         .get();

  See Also:
    `get()`

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ChecksumInputStream` | `get()` Builds a new `ChecksumInputStream`.
    `ChecksumInputStream.Builder` | `setChecksum(Checksum checksum)` Sets the Checksum.
    `ChecksumInputStream.Builder` | `setCountThreshold(long countThreshold)` Sets the count threshold to limit how much input is consumed to update the `Checksum` before the input stream validates its value.
    `ChecksumInputStream.Builder` | `setExpectedChecksumValue(long expectedChecksumValue)` The expected `Checksum` value once the stream is exhausted or the count threshold is reached.

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

  - ### Method Detail

    - #### get

          public ChecksumInputStream get()
                                  throws IOException

      Builds a new `ChecksumInputStream`.

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

      This builder uses the following aspects:

      - `AbstractStreamBuilder.getInputStream()` gets the target aspect.
      - `Checksum`
      - expectedChecksumValue
      - countThreshold
      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()`

    - #### setChecksum

          public ChecksumInputStream.Builder setChecksum(Checksum checksum)

      Sets the Checksum. There is no default `Checksum`, you MUST provide one. This avoids any issue with a default `Checksum` being proven deficient or insecure in the future.
      Parameters:
        `checksum` - the Checksum.
      Returns:
        `this` instance.

    - #### setCountThreshold

          public ChecksumInputStream.Builder setCountThreshold(long countThreshold)

      Sets the count threshold to limit how much input is consumed to update the `Checksum` before the input stream validates its value.

      By default, all input updates the `Checksum`.

      Parameters:
        `countThreshold` - the count threshold. A negative number means the threshold is unbound.
      Returns:
        `this` instance.

    - #### setExpectedChecksumValue

          public ChecksumInputStream.Builder setExpectedChecksumValue(long expectedChecksumValue)

      The expected `Checksum` value once the stream is exhausted or the count threshold is reached.
      Parameters:
        `expectedChecksumValue` - The expected Checksum value.
      Returns:
        `this` instance.