org.javasimon

Interface Simon

All Superinterfaces:

HasAttributes

All Known Subinterfaces:

Counter, Stopwatch

public interface Simon
extends HasAttributes

Simon interface contains common functions related to Simon management - enable/disable and hierarchy. It does not contain any real action method - these are in specific interfaces that describes purpose of the particular type of monitor.

Author:

Richard "Virgo" Richter

See Also:

Manager, for Simon counting some events, for Simon measuring time spans

Method Summary

Modifier and Type	Method and Description
List<Simon>	getChildren() Returns list of children - direct sub-simons.
long	getFirstUsage() Returns ms timestamp of the first usage of this Simon.
long	getLastUsage() Returns ms timestamp of the last usage of this Simon.
Manager	getManager() Returns Simon's Manager.
String	getName() Returns Simon name.
String	getNote() Returns note for the Simon.
Simon	getParent() Returns parent Simon.
SimonState	getState() Returns state of the Simon that can be enabled, disabled or inherited.
boolean	isEnabled() Returns true, if the Simon is enabled or if the enabled state is inherited.
Sample	sample() Samples Simon values and returns them in a Java Bean derived from Sample interface.
Sample	sampleIncrement(Object key) Samples increment in Simon values since the previous call of this method with the same key.
Sample	sampleIncrementNoReset(Object key) Samples current value of incremental Simon.
void	setNote(String note) Sets note for the Simon.
void	setState(SimonState state, boolean overrule) Sets the state of the Simon.
boolean	stopIncrementalSampling(Object key) Stops incremental sampling for the key, removing any internal information for the key.

Methods inherited from interface org.javasimon.HasAttributes

getAttribute, getAttribute, getAttributeNames, getCopyAsSortedMap, removeAttribute, setAttribute

Method Detail

getName

String getName()

Returns Simon name. Simon name is always fully qualified and determines also position of the Simon in the monitor hierarchy. Simon name can be null for anonymous Simons.

Returns:

name of the Simon

getParent

Simon getParent()

Returns parent Simon.

Returns:

parent Simon

getChildren

List<Simon> getChildren()

Returns list of children - direct sub-simons.

Returns:

list of children

getManager

Manager getManager()

Returns Simon's Manager.

Returns:

Simon's Manager

Since:

3.5

getState

SimonState getState()

Returns state of the Simon that can be enabled, disabled or inherited.

Returns:

state of the Simon

setState

void setState(SimonState state,
              boolean overrule)

Sets the state of the Simon. It must be specified whether to propagate the change and overrule states of all sub-simons which effectively sets the same state to the whole subtree. If subtree is not overruled, some Simons (with their subtrees) may not be affected by this change.

Parameters:

state - a new state.

overrule - specifies whether this change is forced to the whole subtree.

Throws:

IllegalArgumentException - if state is null.

isEnabled

boolean isEnabled()

Returns true, if the Simon is enabled or if the enabled state is inherited.

Returns:

true, if the Simon is effectively enabled

getNote

String getNote()

Returns note for the Simon. Note enables Simon with an additional information in human readable form.

Returns:

note for the Simon.

setNote

void setNote(String note)

Sets note for the Simon. Note enables Simon with an additional information in human readable form.

Parameters:

note - note for the Simon.

getFirstUsage

long getFirstUsage()

Returns ms timestamp of the first usage of this Simon. First and last usage are updated when monitor performs the measuring (start/stop/count/etc). They are not updated when values are obtained from the monitor.

Returns:

ms timestamp of the first usage

getLastUsage

long getLastUsage()

Returns ms timestamp of the last usage of this Simon. First and last usage are updated when monitor performs the measuring (start/stop/count/etc). They are not updated when values are obtained from the monitor.

Returns:

ms timestamp of the last usage

sample

Sample sample()

Samples Simon values and returns them in a Java Bean derived from Sample interface.

Returns:

sample containing all Simon values

sampleIncrement

Sample sampleIncrement(Object key)

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 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.

Parameters:

key - sampling key used to access incremental sample

Returns:

Sample with value increments

Since:

3.5

sampleIncrementNoReset

Sample sampleIncrementNoReset(Object key)

Samples current value of incremental Simon. Works like sampleIncrement(Object) but does not reset the incremental Simon. This method does not start incremental sampling and keeps returning values from sample() for any key that was not used with sampleIncrement(Object) before.

Parameters:

key - sampling key used to access incremental sample

Returns:

Sample with value increments

Since:

4.1

See Also:

sampleIncrement(Object)

stopIncrementalSampling

boolean stopIncrementalSampling(Object key)

Stops incremental sampling for the key, removing any internal information for the key. Next call to sampleIncrement(Object) for the key will be considered the first call for the key.

Parameters:

key - sampling key used to access incremental sample

Returns:

true if incremental information for the key existed, false otherwise

Since:

3.5