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:

java.io.Closeable, java.lang.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 and Description
static class	ThrottledInputStream.Builder Builds a new ThrottledInputStream.

Field Summary

Fields

Modifier and Type	Field and Description
private long	maxBytesPerSecond
private long	startTime
private java.time.Duration	totalSleepDuration

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

Constructors

Modifier	Constructor and Description
private	ThrottledInputStream(java.io.InputStream proxy, long maxBytesPerSecond)

Method Summary

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.
private long	getBytesPerSecond() Gets the read-rate from this stream, since creation.
private long	getSleepMillis()
(package private) java.time.Duration	getTotalSleepDuration() Gets the total duration spent in sleep.
private void	throttle()
(package private) static long	toSleepMillis(long bytesRead, long maxBytesPerSec, long elapsedMillis)
java.lang.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

Field Detail

maxBytesPerSecond

private final long maxBytesPerSecond

startTime

private final long startTime

totalSleepDuration

private java.time.Duration totalSleepDuration

Constructor Detail

ThrottledInputStream

private ThrottledInputStream(java.io.InputStream proxy,
                             long maxBytesPerSecond)

Method Detail

builder

public static ThrottledInputStream.Builder builder()

Constructs a new ThrottledInputStream.Builder.

Returns:

a new ThrottledInputStream.Builder.

toSleepMillis

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

beforeRead

protected void beforeRead(int n)
                   throws java.io.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:

java.io.IOException - if the pre-processing fails in a subclass.

getBytesPerSecond

private long getBytesPerSecond()

Gets the read-rate from this stream, since creation. Calculated as bytesRead/elapsedTimeSinceStart.

Returns:

Read rate, in bytes/sec.

getSleepMillis

private long getSleepMillis()

getTotalSleepDuration

java.time.Duration getTotalSleepDuration()

Gets the total duration spent in sleep.

Returns:

Duration spent in sleep.

throttle

private void throttle()
               throws java.io.InterruptedIOException

Throws:

java.io.InterruptedIOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object