com.custardsource.parfait.Monitorable Maven / Gradle / Ivy
Show all versions of parfait-core Show documentation
package com.custardsource.parfait;
import javax.measure.unit.Unit;
/**
*
* An interface to be implemented by any value that needs to be monitored using
* the Parfait monitoring system.
*
*
* An Monitorable primarily exists to return a value on demand (see
* {@link #get()}) but must also be capable of providing metadata about the
* semantics of a value so that various output sinks may treat the value
* appropriately.
*
*
* Monitors use JSR-275 Unit semantics to define their value scale, however if
* the output sinks in use do not care about this value, or use it in any
* meaningful way this may not need to be provided.
*
*
* It is up to the particular {@link Monitor} implementation which uses a given
* Monitorable to determine whether all Monitorables need to be 'pre-registered'
* with the Monitor, or if dynamic addition of Monitorables over the lifetime of
* an application is acceptable.
*
*
* All monitor implementations must support concurrent access from multiple
* threads.
*
*
* @see MonitoredValue
* @see MonitoredConstant
* @see MonitoredCounter
*/
public interface Monitorable {
/**
* @return the name of this Monitorable. Name must be unique across a single
* JVM. Typically uses a logging-framework-style dotted string
* ("java.vm.gc.count") but may be any arbitrary String value.
*/
String getName();
/**
* @return a human-readable descriptive text for the Monitorable. May be
* used by tools to assist understanding of the metric.
*/
String getDescription();
/**
* @return the JSR-275 Unit represented by the value of this Monitorable.
* This may be used to do comparisons and rate-conversions between
* metrics which do not share the same scale. Values which do not
* take a unit should use {@link Unit#ONE}; values for which no unit
* is sensible (e.g. String values) may return null.
*/
Unit getUnit();
/**
* @return the semantics of this Monitorable. Some tools may treat constant,
* variable, or monotonically-increasing values differently; this
* enables them to do so if required.
*/
ValueSemantics getSemantics();
/**
* The type of the value returned by the {@link #get()} method.
*/
Class getType();
/**
*
* The current value of this Monitorable.
*
*
* This method should never block and must return as quickly as possible.
*
*/
T get();
/**
* Attaches the provided Monitor. Once attached the Monitor will be notified
* whenever the value of this Monitorable changes.
*/
void attachMonitor(Monitor m);
/**
* Removed the provided Monitor from the list of attached Monitors.
*/
void removeMonitor(Monitor m);
}