Package 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 CountingInputStream
Provides bandwidth throttling on a specified InputStream. It is implemented as a wrapper on top of another InputStream instance. The throttling works by examining the number of bytes read from the underlying InputStream from the beginning, and sleep()ing for a time interval if the byte-transfer is found exceed the specified tolerable maximum. (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, see `ThrottledInputStream.Builder`

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

Since:
  2.16.0
See Also:
  - `ThrottledInputStream.Builder`

- ## Nested Class Summary

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

- ## Field Summary

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

  `in`

- ## Method Summary

  Modifier and Type
  Method
  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`.
  `String`
  `toString()`

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

  `afterRead, getByteCount, getCount, resetByteCount, resetCount, skip`

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

  `available, close, handleIOException, mark, markSupported, read, read, read, reset, unwrap`

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

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

- ## Method Details

  - ### builder

    public static ThrottledInputStream.Builder builder()
    Constructs a new `ThrottledInputStream.Builder`.
    Returns:
      a new `ThrottledInputStream.Builder`.

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

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`