org.javasimon
Class Split

java.lang.Object
  org.javasimon.Split

All Implemented Interfaces:

HasAttributes

public final class Split
extends Object
implements HasAttributes

Represents single time split - one Stopwatch measurement. Object is obtained by Stopwatch.start() and the measurement is ended using stop() method on this object. Split will return 0 as the result if the related Stopwatch was disabled when the Split was obtained. The Split can be stopped in any other thread. Split measures real time (based on System.nanoTime()), it does not measure CPU time. Split can be garbage collected and no resource leak occurs if it is not stopped, however Stopwatch's active counter (Stopwatch.getActive()) will be stay incremented.

Split can never be running (isRunning()) if it is disabled. Enabled split is running until it is stopped. Stopped split (not running) will never again be running. Split never changes enabled flag after creation.

Author:

Richard "Virgo" Richter

See Also:

Stopwatch

Field Summary

static String	ATTR_EFFECTIVE_STOPWATCH Attribute name under which effectively used stopwatch is stored if the split was stopped with stop(String).
private AttributesSupport	attributesSupport
static Split	DISABLED Disabled split (implies not running) for cases where monitoring is disabled and null value is not an option.
private boolean	enabled
private boolean	running
private long	start
private Stopwatch	stopwatch
private long	total

Constructor Summary

private	Split(boolean enabled)
(package private)	Split(Stopwatch stopwatch) Creates a new Split for a disabled Stopwatch - called internally only.
(package private)	Split(Stopwatch stopwatch, long start) Creates a new Split for an enabled Stopwatch with a specific timestamp in nanoseconds - called internally only.

Method Summary

Object	getAttribute(String name) Returns the value of the named attribute as an Object, or null if no attribute of the given name exists.
<T> T	getAttribute(String name, Class<T> clazz) Returns the value of the named attribute typed to the specified class, or null if no attribute of the given name exists.
Iterator<String>	getAttributeNames() Returns an Iterator containing the names of the attributes available to this Split.
Map<String,Object>	getCopyAsSortedMap() Returns copy of attributes as a sorted map, this can be used further for operations like toString.
long	getStart() Returns start nano timer value - can be converted to ms timestamp using SimonUtils.millisForNano(long).
Stopwatch	getStopwatch() Returns the stopwatch that this split is running for.
boolean	isEnabled() Returns true if this split was created from enabled Simon or via start().
boolean	isRunning() Returns true if this split is still running (stop() has not been called yet).
String	presentRunningFor() Returns printable form of how long this split was running for.
void	removeAttribute(String name) Removes an attribute from this Split.
long	runningFor() Returns the current running nano-time from the start to the method call or the total split time if the Split has been stopped already.
void	setAttribute(String name, Object value) Stores an attribute in this Split.
static Split	start() Creates a new Split for direct use without Stopwatch ("anonymous split").
Split	stop() Stops the split, updates the stopwatch and returns this.
Split	stop(String subSimon) Stops the split, updates the sub-stopwatch specified by parameter and returns this.
String	toString() Returns information about this Split, if it's running, name of the related Stopwatch and split's time.

Methods inherited from class java.lang.Object

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

Field Detail

DISABLED

public static final Split DISABLED

Disabled split (implies not running) for cases where monitoring is disabled and null value is not an option.

ATTR_EFFECTIVE_STOPWATCH

public static final String ATTR_EFFECTIVE_STOPWATCH

Attribute name under which effectively used stopwatch is stored if the split was stopped with stop(String).

See Also:

Constant Field Values

stopwatch

private volatile Stopwatch stopwatch

enabled

private final boolean enabled

running

private volatile boolean running

start

private volatile long start

total

private volatile long total

attributesSupport

private AttributesSupport attributesSupport

Constructor Detail

Split

private Split(boolean enabled)

Split

Split(Stopwatch stopwatch,
      long start)

Creates a new Split for an enabled Stopwatch with a specific timestamp in nanoseconds - called internally only.

Parameters:

stopwatch - owning Stopwatch (enabled)

start - start timestamp in nanoseconds

Split

Split(Stopwatch stopwatch)

Creates a new Split for a disabled Stopwatch - called internally only. Disabled split

Parameters:

stopwatch - owning Stopwatch (disabled)

Method Detail

start

public static Split start()

Creates a new Split for direct use without Stopwatch ("anonymous split"). Stop will not update any Stopwatch, value can be added to any chosen Stopwatch using Stopwatch.addSplit(Split) - even in conjunction with stop() like this:

Split split = Split.start();
 ...
 SimonManager.getStopwatch("codeBlock2.success").addTime(split.stop());

If the split is not needed afterwards calling stop() is not necessary:

Split split = Split.start();
 ...
 SimonManager.getStopwatch("codeBlock2.success").addTime(split);

Since:

3.4

getStopwatch

public Stopwatch getStopwatch()

Returns the stopwatch that this split is running for. May be null for anonymous splits (directly created).

Returns:

owning stopwatch, may be null

stop

public Split stop()

Stops the split, updates the stopwatch and returns this. Subsequent calls do not change the state of the split.

Returns:

this split object

Since:

3.1 - previously returned split time in ns, call additional runningFor() for the same result

stop

public Split stop(String subSimon)

Stops the split, updates the sub-stopwatch specified by parameter and returns this. Active counter of the original stopwatch is decreased as expected. Subsequent calls do not change the state of the split.

Important: While stop() (or this stop with null argument) results in Callback.onStopwatchStop(Split, StopwatchSample) callback method being invoked, if sub-simon is affected then Callback.onStopwatchAdd(Stopwatch, Split, StopwatchSample) is called instead.

If the split was obtained from disabled Stopwatch, this method does not update sub-simon even if it is enabled, because split itself is disabled as well. If split is enabled, but sub-simon is disabled, the latter is not updated.

Parameters:

subSimon - name of the sub-stopwatch (hierarchy delimiter is added automatically) - if null it behaves exactly like stop()

Returns:

this split object

Since:

3.4

runningFor

public long runningFor()

Returns the current running nano-time from the start to the method call or the total split time if the Split has been stopped already.

Returns:

current running nano-time of the split

presentRunningFor

public String presentRunningFor()

Returns printable form of how long this split was running for.

Returns:

short information about the Split time as a human readable string

Since:

2.2

isEnabled

public boolean isEnabled()

Returns true if this split was created from enabled Simon or via start().

Returns:

true if this split was created from enabled Simon

isRunning

public boolean isRunning()

Returns true if this split is still running (stop() has not been called yet). Returns false for disabled Split.

Returns:

true if this split is still running

Since:

3.1.0

getStart

public long getStart()

Returns start nano timer value - can be converted to ms timestamp using SimonUtils.millisForNano(long). Returns 0 if the split is not enabled (started for disabled Stopwatch).

Returns:

nano timer value when the Split was started or 0 if the split is not enabled

Since:

3.1

setAttribute

public void setAttribute(String name,
                         Object value)

Stores an attribute in this Split. Attributes can be used to store any custom objects.

Specified by:

setAttribute in interface HasAttributes

Parameters:

name - a String specifying the name of the attribute

value - the Object to be stored

Since:

2.3

getAttribute

public Object getAttribute(String name)

Returns the value of the named attribute as an Object, or null if no attribute of the given name exists.

Specified by:

getAttribute in interface HasAttributes

Parameters:

name - a String specifying the name of the attribute

Returns:

an Object containing the value of the attribute, or null if the attribute does not exist

Since:

2.3

getAttribute

public <T> T getAttribute(String name,
                          Class<T> clazz)

Returns the value of the named attribute typed to the specified class, or null if no attribute of the given name exists.

Specified by:

getAttribute in interface HasAttributes

Parameters:

name - a String specifying the name of the attribute

Returns:

the value of the attribute typed to T, or null if the attribute does not exist

Since:

3.4

removeAttribute

public void removeAttribute(String name)

Removes an attribute from this Split.

Specified by:

removeAttribute in interface HasAttributes

Parameters:

name - a String specifying the name of the attribute to remove

Since:

2.3

getAttributeNames

public Iterator<String> getAttributeNames()

Returns an Iterator containing the names of the attributes available to this Split. This method returns an empty Iterator if the Split has no attributes available to it.

Specified by:

getAttributeNames in interface HasAttributes

Returns:

an Iterator of strings containing the names of the Split's attributes

Since:

2.3

getCopyAsSortedMap

public Map<String,Object> getCopyAsSortedMap()

Returns copy of attributes as a sorted map, this can be used further for operations like toString.

Specified by:

getCopyAsSortedMap in interface HasAttributes

Returns:

copy of attributes as a sorted map

Since:

3.4

toString

public String toString()

Returns information about this Split, if it's running, name of the related Stopwatch and split's time.

Overrides:

toString in class Object

Returns:

information about the Split as a human readable string