StatsInputStream (EasyStream 1.2.16-SNAPSHOT API)

java.lang.Object
- java.io.InputStream
- - com.gc.iotools.stream.is.StatsInputStream

All Implemented Interfaces:

Closeable, AutoCloseable
```
public class StatsInputStream
extends InputStream
```
An InputStream wrapper that gather statistics about the InputStream passed in the constructor.

It can be used to read:
- The size of the internal stream.
- The time spent reading the bytes.
- The raw bandwidth of the underlying stream, calculated excluding the time spent by the external process to elaborate the data.
- The effective bandwidth of the underlying stream, calculated including the time spent by the external process to elaborate the data.
- The average bytes read each read() call.
Statistics are accumulated for each call and are available both on a per-instance basis or in "historical" mode (for the current and all the past invocations). It is also possible to specify a key for regrouping (e.g "filesystem", "network" in order to regroup statistics of different areas)

Usage:
```
 StatsInputStream srIstream = new StatsInputStream(originalStream);
 // performs all the application operation on stream
 performTasksOnStream(srIstream);
 srIstream.close();
 long size = srIstream.getSize();
 
```
Since:

1.2.1

Version:

$Id: StatsInputStream.java 606 2016-05-21 10:24:36Z gcontini $

Author:

G.Contini

Constructor Summary

Constructors
Constructor and Description
`StatsInputStream(InputStream source)` Constructs an `SizeReaderInputStream`.
`StatsInputStream(InputStream istream, boolean fullReadOnClose)` Constructs an `SizeReaderInputStream` and allow to specify actions to do on close.
`StatsInputStream(InputStream istream, boolean fullReadOnClose, boolean automaticLog)` Constructs an `SizeReaderInputStream` and allow to specify actions to do on close.
`StatsInputStream(InputStream istream, boolean fullReadOnClose, boolean automaticLog, String groupCategory)` Constructs an `SizeReaderInputStream` and allow to specify a key for regrouping the global statistics.
`StatsInputStream(InputStream istream, boolean fullReadOnClose, boolean automaticLog, String groupCategory, StatsInputStream chainStream)` Constructs an `SizeReaderInputStream`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`int`	`available()`
`void`	`close()` Closes the inner stream.
`protected void`	`finalize()`
`float`	`getAverageBytePerRead()` Returns the average bytes per read.
`float`	`getBitRate()` Returns the reading bit rate in KB per second of this single instance.
`String`	`getBitRateString()` Returns the reading bit rate formatted with a convenient unit.
`static Set<String>`	`getCategories()` Returns the set of categories defined for this stream (defined with the parameter groupCategory in the constructor.
`long`	`getElapsedTime(TimeUnit tu)` Returns the time elapsed since this instance was constructed.
`double`	`getInternalOverTotalTime()` This method return a ratio between the time spent by the internal `InputStream` waiting for I/O over the total time since this class was instantiated.
`float`	`getIOBitRate(ByteUnit bu)` Returns the read speed of this single instance.
`long`	`getIOTime(TimeUnit tu)` Returns the time spent until now waiting for the internal stream to respond.
`long`	`getNumberRead()` Number of calls to `int read()` , `int read(byte[])` and `int read(byte[],int,int)` methods.
`long`	`getSize()` Returns the number of bytes read until now from the internal `InputStream` or total length of the stream if the `close()` method has been called or EOF was reached.
`long`	`getTime()` Returns the time (in milliseconds) spent until now waiting for reading from the internal `InputStream`.
`double`	`getTotalDataRead(ByteUnit unit)` Total number of bytes read made by this instance over the subsequent calls.
`long`	`getTotalElapsedTime(TimeUnit tu)` Returns the total time of the instance activity (the time elapsed from the constructor call to the `close()` method.
`long`	`getTotalIOTime(TimeUnit tu)` Returns the total time spent waiting for IO operations from all the instances of the `StatsInputStream`.
`long`	`getTotalNumberRead()` Total count of calls to `int read()`, `int read(byte[])` and `int read(byte[],int,int)` methods, made by this instance over the subsequent calls.
`long`	`getTotalTime(TimeUnit tu)` Deprecated.
`boolean`	`isFullReadOnClose()` Returns the behavior of the close method.
`void`	`logCurrentStatistics()` Logs the current statistics.
`void`	`mark(int readlimit)`
`boolean`	`markSupported()`
`int`	`read()`
`int`	`read(byte[] b)`
`int`	`read(byte[] b, int off, int len)`
`void`	`reset()`
`static void`	`resetStatistics()` Remove keys with 0 associated instances from the maps.
`long`	`skip(long n)`

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - StatsInputStream
```
public StatsInputStream(InputStream source)
```
    Constructs an SizeReaderInputStream. When close() is called the underlying stream will be closed. No further read will be done.
    
    Parameters:
    
    source - Stream whose statistics must be calculated.
  - StatsInputStream
```
public StatsInputStream(InputStream istream,
                        boolean fullReadOnClose)
```
    Constructs an SizeReaderInputStream and allow to specify actions to do on close.
    
    Parameters:
    
    istream - Stream whose bytes must be counted.
    
    fullReadOnClose - if true after the close the inner stream is read completely and the effective size of the inner stream is calculated. For performance reasons we advise to set this parameter to "false".
  - StatsInputStream
```
public StatsInputStream(InputStream istream,
                        boolean fullReadOnClose,
                        boolean automaticLog)
```
    Constructs an SizeReaderInputStream and allow to specify actions to do on close.
    
    If automaticLog is true the statistics will be written when the StatsInputStream is closed or finalized.
    
    Parameters:
    
    istream - Stream whose bytes must be counted.
    
    fullReadOnClose - if true after the close the inner stream is read completely and the effective size of the inner stream is calculated. For performance reasons we advise to set this parameter to "false".
    
    automaticLog - if true statistics will be automatically written when the stream is closed or finalized.
    
    Since:
    
    1.2.7
  - StatsInputStream
```
public StatsInputStream(InputStream istream,
                        boolean fullReadOnClose,
                        boolean automaticLog,
                        String groupCategory)
```
    Constructs an SizeReaderInputStream and allow to specify a key for regrouping the global statistics.
    
    If automaticLog is true the statistics will be written when the StatsInputStream is closed or finalized.
    
    The parameter groupCategory let users specify a key to regroup the totals. It is possible to assign the same key to different instances across the application. In this way users are allowed to compute statistics for different kind of streams ("filesystem", "databaseBlob" or "network"). If left null the class will assign an identifier based on the location where StatInputStream is instantiated.
    
    Parameters:
    
    istream - Stream whose bytes must be counted.
    
    fullReadOnClose - if true after the close the inner stream is read completely and the effective size of the inner stream is calculated. For performance reasons we advise to set this parameter to "false".
    
    automaticLog - if true statistics will be automatically written when the stream is closed or finalized.
    
    groupCategory - a key to regroup the "totals".
    
    Since:
    
    1.2.16
  - StatsInputStream
```
public StatsInputStream(InputStream istream,
                        boolean fullReadOnClose,
                        boolean automaticLog,
                        String groupCategory,
                        StatsInputStream chainStream)
```
    Constructs an SizeReaderInputStream. This constructor is useful to evaluate the performances of a FilterInputStream (its maximum bandwidth and the time spent in processing data internally).
    
    If automaticLog is true the statistics will be written when the StatsInputStream is closed or finalized.
    
    The latest parameter indicates another StatsInputStream to chain with. The aim is to test performances of a single InputStream in a chain of multiple InputStreams . You should put the InputStream to be tested between two StatsInputStream and chain the two together.
    InputStream source = //source of data StatsInputStream sourceStats = new StatsInputStream(source); InputStream toBeTested = new InputStreamToBeTested(stis); StatsInputStream wrapperStis=new StatsInputStream(toBeTested, false, false, sourceStats);
    This will allow to produce statistics of the single InputStream to be tested, in a way independent from the source. Times spent will be the difference between the times from the source and times on the final wrapper.
    
    Parameters:
    
    istream - Stream whose bytes must be counted.
    
    fullReadOnClose - if true after the close the inner stream is read completely and the effective size of the inner stream is calculated.
    
    automaticLog - if true statistics will be automatically written when the stream is closed or finalized.
    
    groupCategory - a key to regroup the "totals".
    
    chainStream - The InputStream to chain.
    
    Since:
    
    1.2.16
- Method Detail
  - getCategories
```
public static Set<String> getCategories()
```
    Returns the set of categories defined for this stream (defined with the parameter groupCategory in the constructor.
    
    Returns:
    
    the set of categories.
  - resetStatistics
```
public static void resetStatistics()
```
    Remove keys with 0 associated instances from the maps. Zeroes other statistics.
  - available
```
public int available()
              throws IOException
```
    Overrides:
    
    available in class InputStream
    
    Throws:
    
    IOException
  - close
```
public void close()
           throws IOException
```
    Closes the inner stream. If fullReadOnClose was set in the constructor it also count all the bytes of the underlying stream.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Overrides:
    
    close in class InputStream
    
    Throws:
    
    IOException - if an I/O error occurs reading the whole content of the stream.
    
    See Also:
    
    InputStream.close()
  - getAverageBytePerRead
```
public float getAverageBytePerRead()
```
    Returns the average bytes per read.
    
    If this parameter is near 1 means that too many calls are made to read the InputStream bringing a loss of performances for large amount of data. Access to this InputStream should be made trough a BufferedInputStream with a reasonable buffer size.
    
    WARN: This measure is not accurate in case of mark and reset.
    
    Returns:
    
    The average bytes per read().
  - getBitRate
```
public float getBitRate()
```
    Returns the reading bit rate in KB per second of this single instance.
    
    Returns:
    
    The KB/Sec bitRate of the stream.
  - getBitRateString
```
public String getBitRateString()
```
    Returns the reading bit rate formatted with a convenient unit.
    
    Returns:
    
    The bitRate of the stream.
  - getElapsedTime
```
public long getElapsedTime(TimeUnit tu)
```
    Returns the time elapsed since this instance was constructed.
    
    Parameters:
    
    tu - Unit to measure the time.
    
    Returns:
    
    time spent in waiting.
  - getInternalOverTotalTime
```
public double getInternalOverTotalTime()
```
    This method return a ratio between the time spent by the internal InputStream waiting for I/O over the total time since this class was instantiated.
    
    This can be used as an indicator to find where the most part of the time is spent. If near 1 means all the time is spent waiting for the internal stream to read the data, if near 0 means the interna
    
    Returns:
    
    Since:
    
    1.2.16
  - getIOBitRate
```
public float getIOBitRate(ByteUnit bu)
```
    Returns the read speed of this single instance. The bit rate is calculated only on the time spent waiting for IO operations. It doesn't take count of the time spent by the software processing this data.
    
    Returns:
    
    the bitRate of the inner stream.
  - getIOTime
```
public long getIOTime(TimeUnit tu)
```
    Returns the time spent until now waiting for the internal stream to respond.
    
    Parameters:
    
    tu - Unit to measure the time.
    
    Returns:
    
    time spent in waiting.
    
    Since:
    
    1.2.16
  - getNumberRead
```
public long getNumberRead()
```
    Number of calls to int read() , int read(byte[]) and int read(byte[],int,int) methods.
    
    Returns:
    
    Long representing the number of calls to read() methods.
  - getSize
```
public long getSize()
```
    Returns the number of bytes read until now from the internal InputStream or total length of the stream if the close() method has been called or EOF was reached.
    
    Calculation refers to the original size of the internal InputStream. If mark(int) and reset() are called, the extra data read after the reset() is not taken in account, until the mark position is reached again.
    
    Returns:
    
    bytes read until now or the total length of the stream if close() was called.
  - getTime
```
public long getTime()
```
    Returns the time (in milliseconds) spent until now waiting for reading from the internal InputStream.
    
    Returns:
    
    time spent in waiting in milliseconds.
  - getTotalDataRead
```
public double getTotalDataRead(ByteUnit unit)
```
    Total number of bytes read made by this instance over the subsequent calls.
    
    Returns:
    
    Long representing the number of bytes in the chosen unit.
  - getTotalElapsedTime
```
public long getTotalElapsedTime(TimeUnit tu)
```
    Returns the total time of the instance activity (the time elapsed from the constructor call to the close() method.
    
    Global statistics are grouped using the key passed in the constructor ( parameter "groupCategory" StatsInputStream(InputStream, boolean, boolean, String) )
    
    Parameters:
    
    tu - Unit to measure the time.
    
    Returns:
    
    amount of time from instantiation to close().
    
    Since:
    
    1.2.16
  - getTotalIOTime
```
public long getTotalIOTime(TimeUnit tu)
```
    Returns the total time spent waiting for IO operations from all the instances of the StatsInputStream.
    
    Global statistics are grouped using the key passed in the constructor ( parameter "groupCategory" StatsInputStream(InputStream, boolean, boolean, String) )
    
    Parameters:
    
    tu - Unit to measure the time.
    
    Returns:
    
    time spent in waiting for IO.
    
    Since:
    
    1.2.16
  - getTotalNumberRead
```
public long getTotalNumberRead()
```
    Total count of calls to int read(), int read(byte[]) and int read(byte[],int,int) methods, made by this instance over the subsequent calls.
    
    Returns:
    
    Long representing the number of calls to read() methods.
  - getTotalTime
```
@Deprecated
public long getTotalTime(TimeUnit tu)
```
    Deprecated.
    
    Renamed in getTotalIOTime(). Please use the new method.
    
    Parameters:
    
    tu -
    
    Returns:
    
    See Also:
    
    getTotalIOTime(TimeUnit)
  - isFullReadOnClose
```
public boolean isFullReadOnClose()
```
    Returns the behavior of the close method. If true when close is invoked a full read of the stream will be performed.
    
    Returns:
    
    Whether a full read will be performed on the invocation of close() method.
  - logCurrentStatistics
```
public void logCurrentStatistics()
```
    Logs the current statistics.
  - mark
```
public void mark(int readlimit)
```
    Overrides:
    
    mark in class InputStream
  - markSupported
```
public boolean markSupported()
```
    Overrides:
    
    markSupported in class InputStream
  - read
```
public int read()
         throws IOException
```
    Specified by:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b)
         throws IOException
```
    Overrides:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b,
                int off,
                int len)
         throws IOException
```
    Overrides:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - reset
```
public void reset()
           throws IOException
```
    Overrides:
    
    reset in class InputStream
    
    Throws:
    
    IOException
  - skip
```
public long skip(long n)
          throws IOException
```
    Overrides:
    
    skip in class InputStream
    
    Throws:
    
    IOException
  - finalize
```
protected void finalize()
                 throws Throwable
```
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable

Class StatsInputStream

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

StatsInputStream

StatsInputStream

StatsInputStream

StatsInputStream

StatsInputStream

Method Detail

getCategories

resetStatistics

available

close

getAverageBytePerRead

getBitRate

getBitRateString

getElapsedTime

getInternalOverTotalTime

getIOBitRate

getIOTime

getNumberRead

getSize

getTime

getTotalDataRead

getTotalElapsedTime

getTotalIOTime

getTotalNumberRead

getTotalTime

isFullReadOnClose

logCurrentStatistics

mark

markSupported

read

read

read

reset

skip

finalize