Stopwatch (Java Simon 4.2.0 API)

All Superinterfaces:

HasAttributes, Simon
```
public interface Stopwatch
extends Simon
```
Stopwatch Simon measures time spans and holds related statistics. Methods start() creates new Split object. On this object you can call Split.stop() - this demarcates measured interval. Alternatively method addSplit(Split) can be used to add split to the stopwatch (Split.create(long) can be used to create finished Split for any nanos value). Both ways effectively updates usage times, increase usage counter by one and updates total time of the stopwatch. Split object enables multiple time-splits to be measured in parallel.
Example:
```
 Split split = SimonManager.getStopwatch("com.my.stopwatch").start();
 //... here goes the measured code
 split.stop();
 System.out.println("Result: " + split.getStopwatch()); // print will be probably somewhere else
```
This can be used for simple micro-benchmarking, critical section monitoring, in web filter to measure request times, etc. SimonManager should always be used to get the stopwatch before using it, because otherwise the code will not reflect enable/disable of the whole API.
Author:

Richard "Virgo" Richter

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Stopwatch`	`addSplit(Split split)` Adds `Split` to the stopwatch which is useful for aggregation of splits created for other stopwatch.
`long`	`getActive()` Returns current number of measured splits (concurrently running).
`long`	`getCounter()` Returns usage count of the stopwatch.
`long`	`getLast()` Returns value of the last added split - whether it was added directly or with stop method.
`long`	`getMax()` Returns maximal time split value in nanoseconds.
`long`	`getMaxActive()` Returns peek value of active concurrent splits.
`long`	`getMaxActiveTimestamp()` Returns ms timestamp when the last peek of the active split count occurred.
`long`	`getMaxTimestamp()` Returns ms timestamp when the max value was measured.
`double`	`getMean()` Returns mean value (average) of all measured values.
`long`	`getMin()` Returns minimal time split value in nanoseconds.
`long`	`getMinTimestamp()` Returns ms timestamp when the min value was measured.
`double`	`getStandardDeviation()` Returns unbiased estimate of standard deviation.
`long`	`getTotal()` Returns total sum of all split times in nanoseconds.
`double`	`getVariance()` Returns unbiased estimate of the population variance.
`double`	`getVarianceN()` Returns variance value of all measured values (entire population).
`StopwatchSample`	`sample()` Samples Simon values and returns them in a Java Bean derived from Sample interface.
`StopwatchSample`	`sampleIncrement(Object key)` Samples increment in Simon values since the previous call of this method with the same key.
`StopwatchSample`	`sampleIncrementNoReset(Object key)` Samples current value of incremental Simon.
`Split`	`start()` Starts the new split for this stopwatch.

Methods inherited from interface org.javasimon.Simon
getChildren, getFirstUsage, getLastUsage, getManager, getName, getNote, getParent, getState, isEnabled, setNote, setState, stopIncrementalSampling

Methods inherited from interface org.javasimon.HasAttributes
getAttribute, getAttribute, getAttributeNames, getCopyAsSortedMap, removeAttribute, setAttribute

- Method Detail
  - start
```
Split start()
```
    Starts the new split for this stopwatch. This action does not hold any resources and if Split object is collected, no leak occurs. However, active count is increased and without stopping the split active count stays increased which may render that information useless.
    
    Returns:
    
    split object
    
    See Also:
    
    Split.stop()
  - addSplit
```
Stopwatch addSplit(Split split)
```
    Adds Split to the stopwatch which is useful for aggregation of splits created for other stopwatch. Split object should be stopped. Main difference is the callback method called as Callback.onStopwatchAdd(Stopwatch, Split, StopwatchSample) provides split object to the callback.
    Usage examples:
```
Split split = Split.start(); // no stopwatch needed
 ...
 someStopwatch.addSplit(split.stop()); // you may omit stop(), if you does not use the split after this point
```
    Parameters:
    
    split - split object (should be stopped)
    
    Returns:
    
    this stopwatch
    
    Since:
    
    3.1
  - getTotal
```
long getTotal()
```
    Returns total sum of all split times in nanoseconds.
    
    Returns:
    
    total time of the stopwatch in nanoseconds
  - getLast
```
long getLast()
```
    Returns value of the last added split - whether it was added directly or with stop method.
    
    Returns:
    
    value of the last added split
  - getCounter
```
long getCounter()
```
    Returns usage count of the stopwatch. Counter is increased by addTime and stop - that means that it's updated every time the next time split is added.
    
    Returns:
    
    count of time splits
  - getMax
```
long getMax()
```
    Returns maximal time split value in nanoseconds.
    
    Returns:
    
    maximal time split in nanoseconds
  - getMin
```
long getMin()
```
    Returns minimal time split value in nanoseconds.
    
    Returns:
    
    minimal time split in nanoseconds
  - getMaxTimestamp
```
long getMaxTimestamp()
```
    Returns ms timestamp when the max value was measured.
    
    Returns:
    
    ms timestamp of the max value measurement
  - getMinTimestamp
```
long getMinTimestamp()
```
    Returns ms timestamp when the min value was measured.
    
    Returns:
    
    ms timestamp of the min value measurement
  - getActive
```
long getActive()
```
    Returns current number of measured splits (concurrently running). This counter can show more splits than is measured at any moment if some splits were "forgotten" (not stopped and garbage collected). This does not imply any resource leak, just bad practice of not stopping Splits somewhere in the client code.
    
    Returns:
    
    current number of active splits
  - getMaxActive
```
long getMaxActive()
```
    Returns peek value of active concurrent splits.
    
    Returns:
    
    maximum reached value of active splits
  - getMaxActiveTimestamp
```
long getMaxActiveTimestamp()
```
    Returns ms timestamp when the last peek of the active split count occurred.
    
    Returns:
    
    ms timestamp of the last peek of the active split count
  - getMean
```
double getMean()
```
    Returns mean value (average) of all measured values. If getCounter() is 0 it should return Double.NaN, but for practical reasons returns 0.
    
    Returns:
    
    mean value
  - getStandardDeviation
```
double getStandardDeviation()
```
    Returns unbiased estimate of standard deviation. If getCounter() is 0 returns Double.NaN. http://en.wikipedia.org/wiki/Unbiased_estimation_of_standard_deviation
    
    Returns:
    
    unbiased estimate of standard deviation
  - getVariance
```
double getVariance()
```
    Returns unbiased estimate of the population variance. If getCounter() is 0 returns Double.NaN. http://en.wikipedia.org/wiki/Variance#Population_variance_and_sample_variance
    
    Returns:
    
    unbiased estimated variance
  - getVarianceN
```
double getVarianceN()
```
    Returns variance value of all measured values (entire population). If getCounter() is 0 returns Double.NaN. http://en.wikipedia.org/wiki/Variance#Population_variance_and_sample_variance
    
    Returns:
    
    entire population variance
  - sample
```
StopwatchSample sample()
```
    Description copied from interface: Simon
    
    Samples Simon values and returns them in a Java Bean derived from Sample interface.
    
    Specified by:
    
    sample in interface Simon
    
    Returns:
    
    sample containing all Simon values
  - sampleIncrement
```
StopwatchSample sampleIncrement(Object key)
```
    Description copied from interface: Simon
    
    Samples increment in Simon values since the previous call of this method with the same key. When the method is called the first time for the key, current values are returned (same like from Simon.sample(). Any subsequent calls with the key provide increments.
    Clients can use any sampling key (any Object) which enables safe access to their own increments. Using String does not guarantee this as any client can potentially guess the key. This may or may not be an issue.
    
    Specified by:
    
    sampleIncrement in interface Simon
    
    Parameters:
    
    key - sampling key used to access incremental sample
    
    Returns:
    
    Sample with value increments
  - sampleIncrementNoReset
```
StopwatchSample sampleIncrementNoReset(Object key)
```
    Description copied from interface: Simon
    
    Samples current value of incremental Simon. Works like Simon.sampleIncrement(Object) but does not reset the incremental Simon. This method does not start incremental sampling and keeps returning values from Simon.sample() for any key that was not used with Simon.sampleIncrement(Object) before.
    
    Specified by:
    
    sampleIncrementNoReset in interface Simon
    
    Parameters:
    
    key - sampling key used to access incremental sample
    
    Returns:
    
    Sample with value increments
    
    See Also:
    
    Simon.sampleIncrement(Object)

Interface Stopwatch

Method Summary

Methods inherited from interface org.javasimon.Simon

Methods inherited from interface org.javasimon.HasAttributes

Method Detail

start

addSplit

getTotal

getLast

getCounter

getMax

getMin

getMaxTimestamp

getMinTimestamp

getActive

getMaxActive

getMaxActiveTimestamp

getMean

getStandardDeviation

getVariance

getVarianceN

sample

sampleIncrement

sampleIncrementNoReset