org.javasimon.callback

Interface Callback

All Known Subinterfaces:

CompositeCallback, FilterCallback

All Known Implementing Classes:

AutoQuantilesCallback, CallbackSkeleton, CallTreeCallback, CompositeCallbackImpl, CompositeFilterCallback, FixedQuantilesCallback, JmxRegisterCallback, LastSplitsCallback, LoggingCallback, LoggingCallback, PropertiesQuantilesCallback, QuantilesCallback, SLF4JLoggingCallback, SystemDebugCallback, TimelineCallback

public interface Callback

Callback processes various events of the Java Simon API and is used as an extension point of the API. Callbacks can be registered with the Manager using its CompositeCallback that can be obtained by calling Manager.callback(). After adding the callback into the main composite callback (or anywhere lower into the callback tree) by calling CompositeCallback.addCallback(Callback) all events are propagated to all Callbacks (unless filtered using FilterCallback). Methods called on various events are named onEventXY with type of the source clearly mentioned in the name (Manager, Simon, Stopwatch, Counter).

Callbacks can be configured via Manager configuration facility. (Configuration part is still rather WIP.)

Callback can have a lifecycle supported with methods initialize(Manager) and cleanup(). Callback is initialized when it is attached to the manager (anywhere in the callback tree) and deinitialized when the callback is removed from the callback tree.

Author:

Richard "Virgo" Richter

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Callback.Event Enumeration of all supported callback actions.

Method Summary

Methods

Modifier and Type	Method and Description
void	cleanup() Lifecycle method called when the callback is removed from the manager.
void	initialize(Manager manager) Lifecycle method called when the callback is added to a manager.
void	onCounterDecrease(Counter counter, long dec, CounterSample sample) Counter decrease event.
void	onCounterIncrease(Counter counter, long inc, CounterSample sample) Counter increase event.
void	onCounterSet(Counter counter, long val, CounterSample sample) Counter set event.
void	onManagerClear() Event called when the manager is cleared.
void	onManagerMessage(String message) Message event is used to propagate arbitrary messages from the manager, or it can be used by the other Callback methods internally.
void	onManagerWarning(String warning, Exception cause) Warning event containing warning and/or cause.
void	onSimonCreated(Simon simon) Simon created event is called when Simon is successfully created by the Manager.
void	onSimonDestroyed(Simon simon) Simon destroyed event is called when Simon is successfully destroyed by the Manager.
void	onStopwatchAdd(Stopwatch stopwatch, Split split, StopwatchSample sample) Stopwatch add split event.
void	onStopwatchStart(Split split) Stopwatch start event.
void	onStopwatchStop(Split split, StopwatchSample sample) Stopwatch stop event.

Method Detail

initialize

void initialize(Manager manager)

Lifecycle method called when the callback is added to a manager.

cleanup

void cleanup()

Lifecycle method called when the callback is removed from the manager. It should implement any necessary cleanup or resources - e.g. release JDBC connection if one was used for Callback functionality.

It is important to realize that this method is not guaranteed to be called for all callbacks, only for callbacks removed from Manager's callback tree.

onStopwatchStart

void onStopwatchStart(Split split)

Stopwatch start event. Duration of all callbacks is included into the split time! StopwatchSample valid for the moment after the start is provided because the callback is executed out of synchronized block. It is guaranteed that Split.getStopwatch() will not return null.

Parameters:

split - started Split

onStopwatchStop

void onStopwatchStop(Split split,
                   StopwatchSample sample)

Stopwatch stop event. This action is executed after the split time is calculated and does not affect the measuring. StopwatchSample valid for the moment after the stop is provided because the callback is executed out of synchronized block. It is guaranteed that Split.getStopwatch() will not return null.

Parameters:

split - stopped Split

sample - stopwatch sampled after the stop

onStopwatchAdd

void onStopwatchAdd(Stopwatch stopwatch,
                  Split split,
                  StopwatchSample sample)

Stopwatch add split event. StopwatchSample valid for the moment after the add is provided because the callback is executed out of synchronized block. It is guaranteed that Split.getStopwatch() will not return null.

Parameters:

stopwatch - modified Stopwatch

split - added split object

sample - stopwatch sampled after the add

Since:

3.1

onCounterDecrease

void onCounterDecrease(Counter counter,
                     long dec,
                     CounterSample sample)

Counter decrease event. CounterSample valid for the moment after the operation is provided because the callback is executed out of synchronized block.

Parameters:

counter - modified Counter

dec - decrement amount

sample - counter sampled after the operation

onCounterIncrease

void onCounterIncrease(Counter counter,
                     long inc,
                     CounterSample sample)

Counter increase event. CounterSample valid for the moment after the operation is provided because the callback is executed out of synchronized block.

Parameters:

counter - modified Counter

inc - increment amount

sample - counter sampled after the operation

onCounterSet

void onCounterSet(Counter counter,
                long val,
                CounterSample sample)

Counter set event. CounterSample valid for the moment after the operation is provided because the callback is executed out of synchronized block.

Parameters:

counter - modified Counter

val - new value

sample - counter sampled after the operation

onSimonCreated

void onSimonCreated(Simon simon)

Simon created event is called when Simon is successfully created by the Manager. Runs within the block synchronized on the Manager - this results in high consistency, but it also means that implementations of this method should not take much time.

Parameters:

simon - created Simon

onSimonDestroyed

void onSimonDestroyed(Simon simon)

Simon destroyed event is called when Simon is successfully destroyed by the Manager. Runs within the block synchronized on the Manager - this results in high consistency, but it also means that implementations of this method should not take much time.

Parameters:

simon - destroyed Simon

onManagerClear

void onManagerClear()

Event called when the manager is cleared. Runs within the block synchronized on the Manager - this results in high consistency, but it also means that implementations of this method should not take much time.

onManagerMessage

void onManagerMessage(String message)

Message event is used to propagate arbitrary messages from the manager, or it can be used by the other Callback methods internally.

Parameters:

message - message text

onManagerWarning

void onManagerWarning(String warning,
                    Exception cause)

Warning event containing warning and/or cause.

Parameters:

warning - arbitrary warning message - can be null, unless concrete implementation states otherwise

cause - exception causing this warning - can be null, unless concrete implementation states otherwise