StatsReader (EasyStream 1.2.16-SNAPSHOT API)

java.lang.Object
- java.io.Reader
- - com.gc.iotools.stream.reader.StatsReader

All Implemented Interfaces:

Closeable, AutoCloseable, Readable
```
public class StatsReader
extends Reader
```
Gather some statistics of the Reader passed in the constructor.

It can be used to read:
- The size of the internal stream.
- The time spent reading the characters.
- The raw bandwidth of the underlying stream, calculated excluding 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:
```
 StatsReader srReader = new StatsReader(originalStream);
 // performs all the application operation on stream
 performTasksOnStream(srReader);
 srReader.close();
 long size = srReader.getSize();
 
```
Since:

1.2.7

Version:

$Id: StatsReader.java 607 2016-05-28 02:58:35Z gcontini $

Author:

G.Contini

Field Summary
- Fields inherited from class java.io.Reader
  lock

Constructor Summary

Constructors
Constructor and Description
`StatsReader(Reader source)` Constructs an `SizeReaderReader`.
`StatsReader(Reader istream, boolean fullReadOnClose)` Constructs an `SizeReaderReader` and allow to specify actions to do on close.
`StatsReader(Reader istream, boolean fullReadOnClose, boolean automaticLog)` Constructs an `SizeReaderReader` and allow to specify actions to do on close.
`StatsReader(Reader istream, boolean fullReadOnClose, boolean automaticLog, String groupCategory, StatsReader chainStream)` Constructs an `SizeReaderReader` and allow to specify actions to do on close.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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`	`getIOCharRate(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 `Reader` 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 `Reader`.
`double`	`getTotalDataRead(ByteUnit unit)` Total number of characters read by this instance over the subsequent calls.
`long`	`getTotalElapsedTime(TimeUnit tu)` Returns the time spent until now waiting for the internal stream to respond.
`long`	`getTotalIOTime(TimeUnit tu)` Returns the total time spent until now waiting for reading from the internal `Reader` by the instances (identified by their constructor position).
`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.
`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(char[] b)`
`int`	`read(char[] chars, 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.io.Reader
read, ready

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

- Constructor Detail
  - StatsReader
```
public StatsReader(Reader source)
```
    Constructs an SizeReaderReader. When close() is called the underlying stream will be closed. No further read will be done.
    
    Parameters:
    
    source - Stream whose statistics must be calculated.
  - StatsReader
```
public StatsReader(Reader istream,
                   boolean fullReadOnClose)
```
    Constructs an SizeReaderReader 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.
  - StatsReader
```
public StatsReader(Reader istream,
                   boolean fullReadOnClose,
                   boolean automaticLog)
```
    Constructs an SizeReaderReader and allow to specify actions to do on close.
    
    If automaticLog is true the statistics will be written when the StatsReader 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.
    
    automaticLog - if true statistics will be automatically written when the stream is closed or finalized.
    
    Since:
    
    1.2.7
  - StatsReader
```
public StatsReader(Reader istream,
                   boolean fullReadOnClose,
                   boolean automaticLog,
                   String groupCategory,
                   StatsReader chainStream)
```
    Constructs an SizeReaderReader and allow to specify actions to do on close.
    
    If automaticLog is true the statistics will be written when the StatsReader is closed or finalized.
    
    Indicates another StatsReader to chain with. The aim is to test performances of a single Reader in a chain of multiple Readers. You should put the Reader to be tested between two StatsReader and chain the two together.
    Reader source = //source of data StatsReader sourceStats = new StatsReader(source); Reader toBeTested = new ReaderToBeTested(sourceStats); StatsReader wrapperStis=new StatsReader(toBeTested, false, false, sourceStats);
    This will allow to produce statistics of the single Reader 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 Reader 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.
  - 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
    
    Specified by:
    
    close in class Reader
    
    Throws:
    
    IOException - if an I/O error occurs reading the whole content of the stream.
    
    See Also:
    
    Reader.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 Reader bringing a loss of performances for large amount of data. Access to this Reader should be made trough a BufferedReader 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
  - getIOCharRate
```
public float getIOCharRate(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 Reader 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 Reader. 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 Reader.
    
    Returns:
    
    time spent in waiting in milliseconds.
  - getTotalDataRead
```
public double getTotalDataRead(ByteUnit unit)
```
    Total number of characters read 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 time spent until now waiting for the internal stream to respond.
    
    Parameters:
    
    tu - Unit to measure the time.
    
    Returns:
    
    time spent in waiting.
  - 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.
  - getTotalIOTime
```
public long getTotalIOTime(TimeUnit tu)
```
    Returns the total time spent until now waiting for reading from the internal Reader by the instances (identified by their constructor position).
    
    Parameters:
    
    tu - Unit to measure the time.
    
    Returns:
    
    time spent in waiting.
  - 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)
          throws IOException
```
    Overrides:
    
    mark in class Reader
    
    Throws:
    
    IOException
  - markSupported
```
public boolean markSupported()
```
    Overrides:
    
    markSupported in class Reader
  - read
```
public int read()
         throws IOException
```
    Overrides:
    
    read in class Reader
    
    Throws:
    
    IOException
  - read
```
public int read(char[] b)
         throws IOException
```
    Overrides:
    
    read in class Reader
    
    Throws:
    
    IOException
  - read
```
public int read(char[] chars,
                int off,
                int len)
         throws IOException
```
    Specified by:
    
    read in class Reader
    
    Throws:
    
    IOException
  - reset
```
public void reset()
           throws IOException
```
    Overrides:
    
    reset in class Reader
    
    Throws:
    
    IOException
  - skip
```
public long skip(long n)
          throws IOException
```
    Overrides:
    
    skip in class Reader
    
    Throws:
    
    IOException
  - finalize
```
protected void finalize()
                 throws Throwable
```
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable

Class StatsReader

Field Summary

Fields inherited from class java.io.Reader

Constructor Summary

Method Summary

Methods inherited from class java.io.Reader

Methods inherited from class java.lang.Object

Constructor Detail

StatsReader

StatsReader

StatsReader

StatsReader

Method Detail

getCategories

resetStatistics

close

getAverageBytePerRead

getBitRate

getBitRateString

getElapsedTime

getInternalOverTotalTime

getIOCharRate

getIOTime

getNumberRead

getSize

getTime

getTotalDataRead

getTotalElapsedTime

getTotalNumberRead

getTotalIOTime

isFullReadOnClose

logCurrentStatistics

mark

markSupported

read

read

read

reset

skip

finalize