org.apache.excalibur.instrument.manager.impl

Interface InstrumentSample

All Superinterfaces:

org.apache.avalon.framework.logger.LogEnabled

All Known Implementing Classes:

AbstractInstrumentSample, AbstractValueInstrumentSample, CounterInstrumentSample, MaximumValueInstrumentSample, MeanValueInstrumentSample, MinimumValueInstrumentSample

interface InstrumentSample
extends org.apache.avalon.framework.logger.LogEnabled

InstrumentSamples are used to provide an Instrument with state. Samples have a sample interval, which is the period over which data is grouped.

InstrmentSamples can be created when the InstrumentManager is created as part of the configuration process, or as a result of a request from an InstrumentClient.

Since:

4.1

Version:

CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:25 $

Author:

Avalon Development Team

Method Summary

Methods

Modifier and Type	Method and Description
void	addInstrumentSampleListener(org.apache.excalibur.instrument.manager.InstrumentSampleListener listener) Registers a InstrumentSampleListener with a InstrumentSample given a name.
void	expire() Tells the sample that its lease has expired.
long	extendLease(long lease) Extends the lease to be lease milliseconds from the current time.
java.lang.String	getDescription() Returns the description of the sample.
org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor	getDescriptor() Returns a Descriptor for the InstrumentSample.
InstrumentProxy	getInstrumentProxy() Returns the InstrumentProxy which owns the InstrumentSample.
int	getInstrumentType() Returns the Type of the Instrument which can use the sample.
long	getInterval() Returns the sample interval.
long	getLeaseExpirationTime() Returns the time that the current lease expires.
java.lang.String	getName() Returns the name of the sample.
int	getSize() Returns the number of samples in the sample history.
org.apache.excalibur.instrument.manager.InstrumentSampleSnapshot	getSnapshot() Obtains a static snapshot of the InstrumentSample.
int	getStateVersion() Returns the stateVersion of the sample.
long	getTime() Obtain the UNIX time of the beginning of the sample.
int	getType() Returns the type of the Instrument Sample.
int	getValue() Obtain the value of the sample.
boolean	isConfigured() Returns true if the InstrumentSample was configured in the instrumentables section of the configuration.
void	loadState(org.apache.avalon.framework.configuration.Configuration state) Loads the state into the InstrumentSample.
void	removeInstrumentSampleListener(org.apache.excalibur.instrument.manager.InstrumentSampleListener listener) Unregisters a InstrumentSampleListener from a InstrumentSample given a name.
void	writeState(java.io.PrintWriter out) Writes the current state to a PrintWriter as XML.

Methods inherited from interface org.apache.avalon.framework.logger.LogEnabled

enableLogging

Method Detail

getInstrumentProxy

InstrumentProxy getInstrumentProxy()

Returns the InstrumentProxy which owns the InstrumentSample.

Returns:

The InstrumentProxy which owns the InstrumentSample.

isConfigured

boolean isConfigured()

Returns true if the InstrumentSample was configured in the instrumentables section of the configuration.

Returns:

True if configured.

getName

java.lang.String getName()

Returns the name of the sample.

Returns:

The name of the sample.

getInterval

long getInterval()

Returns the sample interval. The period of each sample in millisends.

Returns:

The sample interval.

getSize

int getSize()

Returns the number of samples in the sample history.

Returns:

The size of the sample history.

getDescription

java.lang.String getDescription()

Returns the description of the sample.

Returns:

The description of the sample.

getType

int getType()

Returns the type of the Instrument Sample. Possible values include DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_COUNTER, DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MAXIMUM, DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MEAN, or DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MINIMUM.

Returns:

The type of the Instrument Sample.

getDescriptor

org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor getDescriptor()

Returns a Descriptor for the InstrumentSample.

Returns:

A Descriptor for the InstrumentSample.

getValue

int getValue()

Obtain the value of the sample. All samples are integers, so the profiled objects must measure quantity (numbers of items), rate (items/period), time in milliseconds, etc.

Returns:

The sample value.

getTime

long getTime()

Obtain the UNIX time of the beginning of the sample.

Returns:

The UNIX time of the beginning of the sample.

getInstrumentType

int getInstrumentType()

Returns the Type of the Instrument which can use the sample. This should be the same for all instances of a class.

Should be one of the following: DefaultInstrumentManager.INSTRUMENT_TYPE_COUNTER or DefaultInstrumentManager.INSTRUMENT_TYPE_VALUE

Returns:

The Type of the Instrument which can use the sample.

getLeaseExpirationTime

long getLeaseExpirationTime()

Returns the time that the current lease expires. Permanent samples will return a value of 0.

Returns:

The time that the current lease expires.

extendLease

long extendLease(long lease)

Extends the lease to be lease milliseconds from the current time.

Parameters:

lease - The length of the lease in milliseconds.

Returns:

The new lease expiration time. Returns 0 if the sample is permanent.

expire

void expire()

Tells the sample that its lease has expired. No new references to the sample will be made available, but clients which already have access to the sample may continue to use it.

getSnapshot

org.apache.excalibur.instrument.manager.InstrumentSampleSnapshot getSnapshot()

Obtains a static snapshot of the InstrumentSample.

Returns:

A static snapshot of the InstrumentSample.

getStateVersion

int getStateVersion()

Returns the stateVersion of the sample. The state version will be incremented each time any of the configuration of the sample is modified. Clients can use this value to tell whether or not anything has changed without having to do an exhaustive comparison.

Returns:

The state version of the sample.

addInstrumentSampleListener

void addInstrumentSampleListener(org.apache.excalibur.instrument.manager.InstrumentSampleListener listener)

Registers a InstrumentSampleListener with a InstrumentSample given a name.

Parameters:

listener - The listener which should start receiving updates from the InstrumentSample.

removeInstrumentSampleListener

void removeInstrumentSampleListener(org.apache.excalibur.instrument.manager.InstrumentSampleListener listener)

Unregisters a InstrumentSampleListener from a InstrumentSample given a name.

Parameters:

listener - The listener which should stop receiving updates from the InstrumentSample.

writeState

void writeState(java.io.PrintWriter out)

Writes the current state to a PrintWriter as XML.

Parameters:

out - The PrintWriter to which the state should be written.

loadState

void loadState(org.apache.avalon.framework.configuration.Configuration state)
               throws org.apache.avalon.framework.configuration.ConfigurationException

Loads the state into the InstrumentSample.

Parameters:

state - Configuration object to load state from.

Throws:

org.apache.avalon.framework.configuration.ConfigurationException - If there were any problems loading the state.