Package org.javasimon

Core package, contains Simon implementations, with the SimonManager as the center point of the API.

See: Description

Interface Summary

Interface	Description
Counter	Counter tracks the single integer value and watches its max/min values.
HasAttributes	Interface that declares support for arbitrary attributes that can be attached to the object (servlet style).
Manager	Manager provides access to Simons and manages them in a tree structure.
Simon	Simon interface contains common functions related to Simon management - enable/disable and hierarchy.
SimonFilter	Generic filter useful whenever Simons are filtered for some operation.
Stopwatch	Stopwatch Simon measures time spans and holds related statistics.

Class Summary

Class	Description
CounterSample	Object holds all relevant data from Counter Simon.
DisabledManager	Manager implementation that does nothing or returns null or NullSimon as expected from manager in disabled state.
EnabledManager	Implements fully functional Manager in the enabled state.
IncrementalSimonsPurger	This class implements periodical removing of old incremental Simons for specified Manager.
ManagerConfiguration	Holds configuration for one Simon Manager.
Sample	Sample contains all relevant values of the Simon that are obtained by the Simon.sample() and Simon.sampleIncrement(Object) methods.
SimonConfiguration	Stores configuration for the particular Simon or the set of Simons.
SimonManager	SimonManager is static utility class providing so called "default Manager.
SimonPattern	Matches Simon name patterns from configuration.
Split	Represents single time split - one Stopwatch measurement.
StopwatchSample	Object holds all relevant data from Stopwatch Simon.
SwitchingManager	Manager implementation that supports SwitchingManager.enable() and SwitchingManager.disable() and switches between backing EnabledManager and DisabledManager accordingly.
UnknownSample	Sample produced by UnknownSimons.

Enum Summary

Enum	Description
SimonState	Status of monitor.

Exception Summary

Exception	Description
SimonException	SimonException is runtime exception thrown in case something goes seriously wrong (class cast or similar).

Annotation Types Summary

Annotation Type	Description
MustBeInSynchronized	Marker annotation for a method that should be called within a synchronized block.

Package org.javasimon Description

Core package, contains Simon implementations, with the SimonManager as the center point of the API.

Core package contains all basic interfaces (Simon, Counter, Stopwatch and Manager) with their implementations along with SimonManager that provides convenient access to the default Simon Manger.

There are two basic types of Simons provided:

• Stopwatch that measures time and sums the time splits - this is obtained by SimonManager.getStopwatch(String);
• Counter that counts - occurrences, or tracks the integer value - this is obtained by SimonManager.getCounter(String).

All Simons share some basic functions - these are implemented in AbstractSimon. Simons are organized in the tree - methods Simon.getChildren() and Simon.getParent() can be used to traverse it along with SimonManager.getRootSimon(). This tree is also important to determine if the Simon is enabled or disabled. Disabled Simon has minimal possible overhead - but it does not count or measure anything. Simon's state is specified by Simon.setState(SimonState, boolean). SimonState enumeration has three values: SimonState.ENABLED sets Simon as enabled, SimonState.DISABLED sets Simon as disabled and SimonState.INHERIT lets Simon to inherit its state from the parent (recursively).

The whole SimonManager can be enabled or disabled - this is important difference from disabled Simons. Whenever SimonManager is disabled (SimonManager.disable()) any method returning Simon returns NullSimon. Null Simon is different from the disabled Simon because it does nothing and always returns zero/empty values if value is expected. Null Simon is always disabled and cannot be enabled. If the SimonManager is enabled again (SimonManager.enable()) it returns real Simons again. This leads to following recommendations:

• It is recommended always to use SimonManager.getStopwatch(String) or SimonManager.getCounter(String) to get the Simon because this always reflects the status of the SimonManager.
• If it is necessary to keep Simon reference be sure to obtain it while SimonManager is enabled.
• Remember that real Simon is not disabled if the SimonManager is disabled!

Bottom line: If you want to use Simon, get it from SimonManager when needed and don not cache it. (Unless you know what you're doing.)

TODO: Configuration