org.jlf.vitals
Class VitalSign

java.lang.Object
  |
  +--org.jlf.vitals.VitalSign

Direct Known Subclasses:

MemoryInUseVitalSign, TotalMemory, WebLogicRuntimeVital

public class VitalSign

extends java.lang.Object

VitalSign is a class that holds a statistic vital to the proper operation of your code. A VitalSign is automatically registered with the JVM's singleton instance of a VitalsManager, so all server vitals can be accumulated, queried and reported from a centralized location.

Although VitalSigns can be dynamically created and configured, you usually want to configure them via property file settings. The settings and their defaults are listed below.

See Also:

VitalSignProperties

Field Summary

protected java.util.Map	childInstances Holds a collection of child instances.
protected java.lang.String	childVitalKey Unique name of the child vital sign.
protected boolean	isActiveFlag Holds a flag to tell if the vital sign is active
protected boolean	isParentVital Holds a flag to see if a child instance capable vital sign is the parent or the child.
protected VitalSignProperties	properties Holds the properties of the vital sign, whether defined in a property file or given created dynamically.
protected VitalStatistics	statistics Holds a collection of vital sign statistics accumulated over time.
protected long	timeLastChildInstancesCollected Holds the date/time of the last time the vital collected any child instances.
protected long	timeLastVitalMeasurementRegistered Holds the date/time of the last registered measurement for the vital sign.
protected java.lang.String	vitalKey Unique name of the vital sign.

Constructor Summary

VitalSign(java.lang.String vitalKey)
Creates a vital sign, looking to properties in the property file for information on how the vital should work.

VitalSign(java.lang.String vitalKey, VitalSignProperties properties)
Creates a vital sign with the properties dynamically constructed instead of read from a property file.

Method Summary

protected VitalSign	basicCreateChildInstance(java.lang.String inputChildVitalKey) Helper method that creates a new child instance but does not register it.
AbstractVitalMeasurement	basicGetMaximumMeasurement() Returns the maximum theoritical value of the vital sign.
protected void	collectChildInstanceMeasurements() Helper method to iterate through any child instances and collect measurements.
AbstractVitalMeasurement	collectMeasurement() Collects a current measurement of the vital sign and adds it into the vital sign's set of statistics.
VitalSign	findOrCreateChildInstance(java.lang.String inputChildVitalKey) For vital signs enabled for children, this method takes a childVitalKey as an input parameter and either finds that child in the current children collection or creates a new child instances of the same class.
VitalSign	getChildInstance(java.lang.String inputChildVitalKey) Finds a vital sign child instance in the collection.
java.util.Collection	getChildInstances() Returns a list of child instances.
java.lang.String	getChildVitalKey() Returns the childVitalKey.
protected AbstractVitalMeasurement	getCurrentMeasurement() Takes a measurement of the vital sign at the current moment and returns it to the caller.
static VitalSign	getInstance(java.lang.String vitalKey) Creates a vital sign of the correct sub-class, using properties defined in the main property file.
static VitalSign	getInstance(java.lang.String vitalKey, VitalSignProperties properties) Creates a vital sign of the correct sub-class, given its vital key and properties.
AbstractVitalMeasurement	getMaximumMeasurement() Returns the maximum theoritical value of the vital sign.
VitalSignProperties	getProperties() Returns the properties for the vital sign.
VitalStatistics	getStatistics() Returns the statistics.
java.lang.String	getVitalKey() Returns the vitalKey.
boolean	hasChildInstances() Tells whether the vital sign has child instances or not.
boolean	isActive() Returns if the vital is active or not
boolean	isParentVital() For a child instance capable vital, returns if the vital sign instance is the parent or a child.
boolean	isVitalApplicable() Checks to see if a vital sign is applicable for collection in the current JVM.
protected void	putChildInstance(VitalSign childInstance) Helper method to put a child instance in the collection.
void	refreshChildInstances() Refreshes the list of child instances for those vitals that have such.
void	registerMeasurement(AbstractVitalMeasurement newMeasurement) Registers a measurement for this vital sign into the vital sign's set of statistics it keeps.
void	setChildVitalKey(java.lang.String childVitalKey) Sets the childVitalKey.
void	setIsActiveFlag(boolean isActiveFlag) Sets whether the vital is active.
void	setIsParentVital(boolean isParentVital) For a child instance capable vital, sets the flag if the vital sign instance is the parent or a child.
protected boolean	shouldChildInstancesBeCollected() Checks to see if a vital sign measurement should be collected, given its frequency defined in the property file.
boolean	shouldMeasurementBeCollected() Checks to see if a vital sign measurement should be collected, given its frequency defined in the property file.
protected java.lang.String	vitalKeyForChildVitalKey(java.lang.String inputChildVitalKey) Helper method to construct a child instance vital key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

vitalKey

protected java.lang.String vitalKey

Unique name of the vital sign.

properties

protected VitalSignProperties properties

Holds the properties of the vital sign, whether defined in a property file or given created dynamically.

statistics

protected VitalStatistics statistics

Holds a collection of vital sign statistics accumulated over time.

timeLastVitalMeasurementRegistered

protected long timeLastVitalMeasurementRegistered

Holds the date/time of the last registered measurement for the vital sign.

timeLastChildInstancesCollected

protected long timeLastChildInstancesCollected

Holds the date/time of the last time the vital collected any child instances.

childVitalKey

protected java.lang.String childVitalKey

Unique name of the child vital sign. This name is pre-pended to the vitalKey and the vital name property.

childInstances

protected java.util.Map childInstances

Holds a collection of child instances.

isParentVital

protected boolean isParentVital

Holds a flag to see if a child instance capable vital sign is the parent or the child.

isActiveFlag

protected boolean isActiveFlag

Holds a flag to tell if the vital sign is active

Constructor Detail

VitalSign

public VitalSign(java.lang.String vitalKey)

Creates a vital sign, looking to properties in the property file for information on how the vital should work.

VitalSign

public VitalSign(java.lang.String vitalKey,
                 VitalSignProperties properties)

Creates a vital sign with the properties dynamically constructed instead of read from a property file.

Note: When you create a subclass of VitalSign, particularly for Vital Signs that are entered in your property file to be perioidically collected, you MUST pass this constructor through to this superclass or the automated collection process will not be able to instantiate the class.

Method Detail

getInstance

public static VitalSign getInstance(java.lang.String vitalKey)

Creates a vital sign of the correct sub-class, using properties defined in the main property file.

getInstance

public static VitalSign getInstance(java.lang.String vitalKey,
                                    VitalSignProperties properties)

Creates a vital sign of the correct sub-class, given its vital key and properties.

getVitalKey

public java.lang.String getVitalKey()

Returns the vitalKey.

getProperties

public VitalSignProperties getProperties()

Returns the properties for the vital sign.

isActive

public boolean isActive()

Returns if the vital is active or not

setIsActiveFlag

public void setIsActiveFlag(boolean isActiveFlag)

Sets whether the vital is active. This is really only effective for vitals that are collected periodically.

isVitalApplicable

public boolean isVitalApplicable()

Checks to see if a vital sign is applicable for collection in the current JVM. For example, vital signs designed for a WebLogic container should return false if the vital is run in a non-WebLogic container. This method needs to be overridden in subclasses that implement periodically-collected vitals if there is a chance the vital sign isn't applicable in a particular JVM.

getStatistics

public VitalStatistics getStatistics()

Returns the statistics.

registerMeasurement

public void registerMeasurement(AbstractVitalMeasurement newMeasurement)

Registers a measurement for this vital sign into the vital sign's set of statistics it keeps.

getCurrentMeasurement

protected AbstractVitalMeasurement getCurrentMeasurement()

Takes a measurement of the vital sign at the current moment and returns it to the caller. This method should be implemented by subclasses that are automatically called by the vitals manager on a periodic basis. The default implementation in this superclass is to return null, leaving the implementation to a subclass.

Returns:

the current measurement for this vital sign or null if no implementation

getMaximumMeasurement

public AbstractVitalMeasurement getMaximumMeasurement()

Returns the maximum theoritical value of the vital sign. This method should NOT be overriden by subclasses as it may cache the result or implement behavior like changing the measurement name.

Returns:

the current measurement for this vital sign or null if no implementation

basicGetMaximumMeasurement

public AbstractVitalMeasurement basicGetMaximumMeasurement()

Returns the maximum theoritical value of the vital sign. This method should be implemented by subclasses that are automatically called by the vitals manager on a periodic basis and have a pretty good idea what the maximum value that could be recorded is. The default implementation in this superclass is to return null, leaving the implementation to a subclass.

Returns:

the current measurement for this vital sign or null if no implementation

shouldMeasurementBeCollected

public boolean shouldMeasurementBeCollected()

Checks to see if a vital sign measurement should be collected, given its frequency defined in the property file.

collectChildInstanceMeasurements

protected void collectChildInstanceMeasurements()

Helper method to iterate through any child instances and collect measurements.

collectMeasurement

public AbstractVitalMeasurement collectMeasurement()

Collects a current measurement of the vital sign and adds it into the vital sign's set of statistics.

This method is typically called by the vitals manager, which kicks in every second or and sees if a new measurement needs to be taken. It in turn calls the getCurrentMeasurement() method, which is implemented by subclasses to take a measurement appropriate to the subclass.

Returns:

the current measurement for this vital sign or null if no implementation

hasChildInstances

public boolean hasChildInstances()

Tells whether the vital sign has child instances or not. If a vital sign has instances, it is sort of abstract, that is, it does not actually collect any vitals. Instead, its child instances do. For example, a JDBC connection pool vital sign knows how to collect vital sign measurements for a named pool. There could be several instances of named pools, one child instance for each pool.

The default for this is false, only one instance (itself) for the vital.

getChildVitalKey

public java.lang.String getChildVitalKey()

Returns the childVitalKey.

Returns:

String

setChildVitalKey

public void setChildVitalKey(java.lang.String childVitalKey)

Sets the childVitalKey.

Parameters:

childVitalKey - The childVitalKey to set

getChildInstances

public java.util.Collection getChildInstances()

Returns a list of child instances.

vitalKeyForChildVitalKey

protected java.lang.String vitalKeyForChildVitalKey(java.lang.String inputChildVitalKey)

Helper method to construct a child instance vital key.

getChildInstance

public VitalSign getChildInstance(java.lang.String inputChildVitalKey)

Finds a vital sign child instance in the collection. Child instances have a vitalKey that is usually a combination of its parent's vital key plus something to uniquely identify the child, called the childVitalKey.

Returns:

the VitalSign that matches the inputChildVitalKey if found, null if not.

basicCreateChildInstance

protected VitalSign basicCreateChildInstance(java.lang.String inputChildVitalKey)

Helper method that creates a new child instance but does not register it. Using the current instance class, it does a reflection object create, cloning the current properties settings from the current object and resetting its vital name property to include the child instance key.

For this method to work, Vital Sign subclasses MUST implement a public constructor that takes a String vital key and a VitalSignProperties object as input parameters.

findOrCreateChildInstance

public VitalSign findOrCreateChildInstance(java.lang.String inputChildVitalKey)

For vital signs enabled for children, this method takes a childVitalKey as an input parameter and either finds that child in the current children collection or creates a new child instances of the same class.

For this method to work, Vital Sign subclasses MUST implement a public constructor that takes a String vital key and a VitalSignProperties object as input parameters.

putChildInstance

protected void putChildInstance(VitalSign childInstance)

Helper method to put a child instance in the collection.

Throws:

AppError - if the child instance is already registered

shouldChildInstancesBeCollected

protected boolean shouldChildInstancesBeCollected()

Checks to see if a vital sign measurement should be collected, given its frequency defined in the property file. This method should NOT be overridden in subclasses.

refreshChildInstances

public void refreshChildInstances()

Refreshes the list of child instances for those vitals that have such. Subclasses that periodically collect vitals must implement this method, call the superclass method FIRST, and refresh its list of collected vitals. This method will set all child instances to inactive and require the subclass implementation to re-activate any children that are still applicable.

isParentVital

public boolean isParentVital()

For a child instance capable vital, returns if the vital sign instance is the parent or a child.

setIsParentVital

public void setIsParentVital(boolean isParentVital)

For a child instance capable vital, sets the flag if the vital sign instance is the parent or a child.