Split (Java Simon 4.1.4 API)

java.lang.Object
- org.javasimon.Split

All Implemented Interfaces:

AutoCloseable, HasAttributes
```
public final class Split
extends Object
implements HasAttributes, AutoCloseable
```
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 SimonClock.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.
Split implements AutoCloseable hence it can be used in try-with-resource construction.

Author:

Richard "Virgo" Richter

See Also:
Stopwatch

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ATTR_EFFECTIVE_STOPWATCH` Attribute name under which effectively used stopwatch is stored if the split was stopped with `stop(String)`.
`static Split`	`DISABLED` Disabled split (implies not running) for cases where monitoring is disabled and `null` value is not an option.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`close()` Allows to use Split as a resource in try-with-resource construct.
`static Split`	`create(long nanos)` Creates simulated non-running Split that took specific time in nanos.
`static Split`	`create(long nanos, SimonClock clock)` Creates simulated non-running Split that took specific time in nanos.
`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 or 0 if the Split is not enabled (started for disabled Stopwatch).
`long`	`getStartMillis()` Returns millis timestamp when this Split was started - or 0 if the Split is not enabled (started for disabled Stopwatch).
`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") based on system time.
`static Split`	`start(SimonClock clock)` Creates a new Split for direct use without `Stopwatch` ("anonymous split") based on specified `SimonClock`.
`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
- Method Detail
  - start
```
public static Split start(SimonClock clock)
```
    Creates a new Split for direct use without Stopwatch ("anonymous split") based on specified SimonClock. 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();
 ...
 stopwatch.addSplit(split.stop());
```
    If the split is not needed afterwards (subject to garbage collection) calling stop() is not necessary:
```
Split split = Split.start();
 ...
 stopwatch.addSplit(split);
```
    No callbacks are called for this Split.
    Parameters:
    clock - Clock for this Split
    Since:
    
    3.5
  - start
```
public static Split start()
```
    Creates a new Split for direct use without Stopwatch ("anonymous split") based on system time. Equivalent of Split.start(Clock.SYSTEM).
    
    Since:
    
    3.4
    
    See Also:
    start(SimonClock)
  - create
```
public static Split create(long nanos,
           SimonClock clock)
```
    Creates simulated non-running Split that took specific time in nanos. No callbacks are called for this Split. Start of this Split is set clock.nanoTime().
    
    Parameters:
    nanos - Split's total time in nanos
    clock - Clock for this Split
    
    Returns:
    created Split
    Since:
    
    3.5
  - create
```
public static Split create(long nanos)
```
    Creates simulated non-running Split that took specific time in nanos. No callbacks are called for this Split. Start of this Split is based on SimonClock.SYSTEM.
    
    Parameters:
    nanos - Split's total time in nanos
    
    Returns:
    created Split
    Since:
    
    3.5
    
    See Also:
    create(long, SimonClock)
  - 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 return 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 or 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
  - getStartMillis
```
public long getStartMillis()
```
    Returns millis timestamp when this Split was started - or 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()
```
    Description copied from interface: HasAttributes
    
    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
  - close
```
public void close()
```
    Allows to use Split as a resource in try-with-resource construct. Calls stop() internally.
    
    Specified by:
    
    close in interface AutoCloseable
    
    Since:
    
    4.0
  - 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

Class Split

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DISABLED

ATTR_EFFECTIVE_STOPWATCH

Method Detail

start

start

create

create

getStopwatch

stop

stop

runningFor

presentRunningFor

isEnabled

isRunning

getStart

getStartMillis

setAttribute

getAttribute

getAttribute

removeAttribute

getAttributeNames

getCopyAsSortedMap

close

toString