org.apache.commons.io.input

## Class ThrottledInputStream

- java.lang.Object
- - java.io.InputStream
  - - java.io.FilterInputStream
    - - org.apache.commons.io.input.ProxyInputStream
      - - org.apache.commons.io.input.CountingInputStream
        - - org.apache.commons.io.input.ThrottledInputStream

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public final class ThrottledInputStream
      extends org.apache.commons.io.input.CountingInputStream

  Provides bandwidth throttling on an InputStream as a filter input stream. The throttling examines the number of bytes read from the underlying InputStream, and sleeps for a time interval if the byte-transfer is found to exceed the specified maximum rate. Thus, while the read-rate might exceed the maximum for a short interval, the average tends towards the specified maximum, overall.

  To build an instance, call `builder()`.

  Inspired by Apache HBase's class of the same name.

  See Also:
    `ThrottledInputStream.Builder`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ThrottledInputStream.Builder` Builds a new `ThrottledInputStream`.

    - ### Nested classes/interfaces inherited from class org.apache.commons.io.input.ProxyInputStream

      `ProxyInputStream.AbstractBuilder<T,B extends AbstractStreamBuilder<T,B>>`

  - ### Field Summary

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

      `in`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `beforeRead(int n)` Invoked by the `read` methods before the call is proxied.
    `static ThrottledInputStream.Builder` | `builder()` Constructs a new `ThrottledInputStream.Builder`.
    `(package private) double` | `getMaxBytesPerSecond()`
    `(package private) java.time.Duration` | `getTotalSleepDuration()` Gets the total duration spent in sleep.
    `(package private) static long` | `toSleepMillis(long bytesRead, long elapsedMillis, double maxBytesPerSec)`
    `String` | `toString()`

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

      `afterRead, getByteCount, resetByteCount, skip`

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

      `available, checkOpen, close, handleIOException, isClosed, mark, markSupported, read, read, read, reset, setReference, unwrap`

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

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

- - ### Method Detail

    - #### beforeRead

          protected void beforeRead(int n)
                             throws IOException

      Description copied from class: `ProxyInputStream`
      Invoked by the `read` methods before the call is proxied. The number of bytes that the caller wanted to read (1 for the `ProxyInputStream.read()` method, buffer length for `ProxyInputStream.read(byte[])`, etc.) is given as an argument.

      Subclasses can override this method to add common pre-processing functionality without having to override all the read methods. The default implementation does nothing.

      Note this method is not called from `ProxyInputStream.skip(long)` or `ProxyInputStream.reset()`. You need to explicitly override those methods if you want to add pre-processing steps also to them.

      Overrides:
        `beforeRead` in class `ProxyInputStream`
      Parameters:
        `n` - number of bytes that the caller asked to be read.
      Throws:
        `IOException` - if the pre-processing fails in a subclass.

    - #### builder

          public static ThrottledInputStream.Builder builder()

      Constructs a new `ThrottledInputStream.Builder`.
      Returns:
        a new `ThrottledInputStream.Builder`.

    - #### getMaxBytesPerSecond

          double getMaxBytesPerSecond()

    - #### getTotalSleepDuration

          java.time.Duration getTotalSleepDuration()

      Gets the total duration spent in sleep.
      Returns:
        Duration spent in sleep.

    - #### toSleepMillis

          static long toSleepMillis(long bytesRead,
                                    long elapsedMillis,
                                    double maxBytesPerSec)

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`