org.apache.excalibur.instrument.manager.impl

Class InstrumentProxy

java.lang.Object

org.apache.avalon.framework.logger.AbstractLogEnabled

org.apache.excalibur.instrument.manager.impl.InstrumentProxy

All Implemented Interfaces:

org.apache.avalon.framework.configuration.Configurable, org.apache.avalon.framework.logger.LogEnabled, org.apache.excalibur.instrument.InstrumentProxy

public class InstrumentProxy
extends org.apache.avalon.framework.logger.AbstractLogEnabled
implements org.apache.excalibur.instrument.InstrumentProxy, org.apache.avalon.framework.configuration.Configurable

Instrumentables which do not implement ThreadSafe may have multiple instances created by the ComponentLocator. Each of these Instruments will share a common key and are instrumented as a group. The InstrumentProxy is used make it easy for the InstrumentManager to control groups of Instruments as one.

The type of a Instrument can not be determined at configuration time. It is resolved when the Instrumentable actually registers the Instrument.

Since:

4.1

Version:

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

Author:

Avalon Development Team

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	m_configured Configured flag.
private java.lang.String	m_description The description of the Instrumente.
private org.apache.excalibur.instrument.manager.InstrumentDescriptor	m_descriptor The Descriptor for the Instrument.
private InstrumentableProxy	m_instrumentableProxy The InstrumentableProxy which owns the InstrumentProxy.
private int	m_lastValue The most recent value set if this is a value instrument.
private org.apache.excalibur.instrument.manager.InstrumentListener[]	m_listeners Array of registered Counter/ValueInstrumentListeners.
private java.lang.String	m_name The name used to identify a Instrument.
private boolean	m_registered Registered flag.
private InstrumentSample[]	m_sampleArray Optimized array of the InstrumentSamples.
private org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor[]	m_sampleDescriptorArray Optimized array of the InstrumentSampleDescriptors.
private java.util.HashMap	m_samples Map of the maintained InstrumentSamples.
private int	m_stateVersion State Version.
private int	m_type Type of the Instrument
private org.apache.avalon.framework.logger.Logger	m_valueLogger Child logger to use for logging of new values.

Constructor Summary

Constructors

Constructor and Description
InstrumentProxy(InstrumentableProxy instrumentableProxy, java.lang.String name, java.lang.String description) Creates a new InstrumentProxy.

Method Summary

Methods

Modifier and Type	Method and Description
(package private) void	addCounterInstrumentListener(org.apache.excalibur.instrument.manager.CounterInstrumentListener listener) Adds a CounterInstrumentListener to the list of listeners which will receive updates of the value of the Instrument.
private void	addInstrumentListener(org.apache.excalibur.instrument.manager.InstrumentListener listener) Common code to add a listener to the list of listeners which will receive updates of the value of the Instrument.
private void	addInstrumentSample(InstrumentSample instrumentSample) Add a InstrumentSample to the Instrument.
(package private) void	addValueInstrumentListener(org.apache.excalibur.instrument.manager.ValueInstrumentListener listener) Adds a ValueInstrumentListener to the list of listeners which will receive updates of the value of the Instrument.
void	configure(org.apache.avalon.framework.configuration.Configuration configuration) Configures the Instrument.
(package private) InstrumentSample	createInstrumentSample(java.lang.String sampleDescription, long sampleInterval, int sampleSize, long sampleLease, int sampleType) Returns an InstrumentSampleDescriptor based on its name.
void	enableLogging(org.apache.avalon.framework.logger.Logger logger)
(package private) java.lang.String	getDescription() Gets the description of the Instrument.
(package private) org.apache.excalibur.instrument.manager.InstrumentDescriptor	getDescriptor() Returns a Descriptor for the Instrument.
(package private) InstrumentableProxy	getInstrumentableProxy() Returns the InstrumentableProxy which owns the InstrumentProxy.
(package private) InstrumentSample	getInstrumentSample(java.lang.String instrumentSampleName) Returns a InstrumentSample based on its name.
(package private) org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor[]	getInstrumentSampleDescriptors() Returns an array of Descriptors for the InstrumentSamples in the Instrument.
(package private) InstrumentSample[]	getInstrumentSamples() Returns an array of the InstrumentSamples in the Instrument.
(package private) java.lang.String	getName() Gets the name for the Instrument.
(package private) int	getStateVersion() Returns the stateVersion of the instrument.
(package private) int	getType() Returns the type of the Instrument.
static java.lang.String	getTypeName(int type) Returns the name of a Instrument type.
void	increment(int count) Increments the Instrument by a specified count.
boolean	isActive() Used by classes being instrumented so that they can avoid unnecessary code when the data from a Instrument is not being used.
(package private) boolean	isConfigured() Returns true if the Instrument was configured in the instrumentables section of the configuration.
(package private) boolean	isRegistered() Returns true if the Instrument was registered with the Instrument Manager.
(package private) InstrumentSample	loadSampleState(org.apache.avalon.framework.configuration.Configuration state) Loads the state of an Instrument Sample.
(package private) void	removeCounterInstrumentListener(org.apache.excalibur.instrument.manager.CounterInstrumentListener listener) Removes a InstrumentListener from the list of listeners which will receive events.
private void	removeInstrumentListener(org.apache.excalibur.instrument.manager.InstrumentListener listener) Common code to remove a listener from the list of listeners which will receive updates of the value of the Instrument.
(package private) void	removeInstrumentSample(InstrumentSample instrumentSample) Removes an InstrumentSample from the Instrument.
(package private) void	removeValueInstrumentListener(org.apache.excalibur.instrument.manager.ValueInstrumentListener listener) Removes a InstrumentListener from the list of listeners which will receive events.
(package private) void	setDescription(java.lang.String description) Sets the description for the Instrument.
(package private) void	setRegistered() Called by the InstrumentManager whenever an Instrument assigned to this proxy is registered.
(package private) void	setType(int type) Set the type of the Instrument.
void	setValue(int value) Sets the current value of the Instrument.
protected void	stateChanged() Called whenever the state of the instrument is changed.
private InstrumentSample[]	updateInstrumentSampleArray() Updates the cached array of InstrumentSamples taking synchronization into account.
private org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor[]	updateInstrumentSampleDescriptorArray() Updates the cached array of InstrumentSampleDescriptors taking synchronization into account.
(package private) void	writeState(java.io.PrintWriter out) Writes the current state to a PrintWriter as XML.

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

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

Field Detail

m_instrumentableProxy

private InstrumentableProxy m_instrumentableProxy

The InstrumentableProxy which owns the InstrumentProxy.

m_configured

private boolean m_configured

Configured flag.

m_registered

private boolean m_registered

Registered flag.

m_name

private java.lang.String m_name

The name used to identify a Instrument.

m_description

private java.lang.String m_description

The description of the Instrumente.

m_descriptor

private org.apache.excalibur.instrument.manager.InstrumentDescriptor m_descriptor

The Descriptor for the Instrument.

m_type

private int m_type

Type of the Instrument

m_listeners

private org.apache.excalibur.instrument.manager.InstrumentListener[] m_listeners

Array of registered Counter/ValueInstrumentListeners.

m_samples

private java.util.HashMap m_samples

Map of the maintained InstrumentSamples.

m_sampleArray

private InstrumentSample[] m_sampleArray

Optimized array of the InstrumentSamples.

m_sampleDescriptorArray

private org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor[] m_sampleDescriptorArray

Optimized array of the InstrumentSampleDescriptors.

m_valueLogger

private org.apache.avalon.framework.logger.Logger m_valueLogger

Child logger to use for logging of new values.

m_lastValue

private int m_lastValue

The most recent value set if this is a value instrument.

m_stateVersion

private int m_stateVersion

State Version.

Constructor Detail

InstrumentProxy

InstrumentProxy(InstrumentableProxy instrumentableProxy,
               java.lang.String name,
               java.lang.String description)

Creates a new InstrumentProxy.

Parameters:

instrumentableProxy - The InstrumentableProxy which owns the InstrumentProxy.

name - The name used to identify a Instrumentable.

description - The description of the the Instrumentable.

Method Detail

enableLogging

public void enableLogging(org.apache.avalon.framework.logger.Logger logger)

Specified by:

enableLogging in interface org.apache.avalon.framework.logger.LogEnabled

Overrides:

enableLogging in class org.apache.avalon.framework.logger.AbstractLogEnabled

configure

public void configure(org.apache.avalon.framework.configuration.Configuration configuration)
               throws org.apache.avalon.framework.configuration.ConfigurationException

Configures the Instrument. Called from the InstrumentManager's configure method. The class does not need to be configured to function correctly.

Specified by:

configure in interface org.apache.avalon.framework.configuration.Configurable

Parameters:

configuration - Instrument configuration element from the InstrumentManager's configuration.

Throws:

org.apache.avalon.framework.configuration.ConfigurationException - If there are any configuration problems.

isActive

public boolean isActive()

Used by classes being instrumented so that they can avoid unnecessary code when the data from a Instrument is not being used.

Specified by:

isActive in interface org.apache.excalibur.instrument.InstrumentProxy

increment

public void increment(int count)

Increments the Instrument by a specified count. This method should be optimized to be extremely light weight when there are no registered CounterInstrumentListeners.

Specified by:

increment in interface org.apache.excalibur.instrument.InstrumentProxy

Parameters:

count - A positive integer to increment the counter by.

setValue

public void setValue(int value)

Sets the current value of the Instrument. This method is optimized to be extremely light weight when there are no registered ValueInstrumentListeners.

Specified by:

setValue in interface org.apache.excalibur.instrument.InstrumentProxy

Parameters:

value - The new value for the Instrument.

getInstrumentableProxy

InstrumentableProxy getInstrumentableProxy()

Returns the InstrumentableProxy which owns the InstrumentProxy.

Returns:

The InstrumentableProxy which owns the InstrumentProxy.

isConfigured

boolean isConfigured()

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

Returns:

True if configured.

isRegistered

boolean isRegistered()

Returns true if the Instrument was registered with the Instrument Manager.

Returns:

True if registered.

setRegistered

void setRegistered()

Called by the InstrumentManager whenever an Instrument assigned to this proxy is registered.

getName

java.lang.String getName()

Gets the name for the Instrument. The Instrument Name is used to uniquely identify the Instrument during configuration and to gain access to a InstrumentDescriptor through an InstrumentManager.

Returns:

The name used to identify a Instrumentable.

setDescription

void setDescription(java.lang.String description)

Sets the description for the Instrument. This description will be set during configuration if a configuration exists for this Instrument.

Parameters:

description - The description of the Instrument.

getDescription

java.lang.String getDescription()

Gets the description of the Instrument.

Returns:

The description of the Instrument.

getDescriptor

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

Returns a Descriptor for the Instrument.

Returns:

A Descriptor for the Instrument.

setType

void setType(int type)

Set the type of the Instrument. Once set, the type can not be changed.

Parameters:

type - Type of the Instrument.

getType

int getType()

Returns the type of the Instrument.

Returns:

The type of the Instrument.

addCounterInstrumentListener

void addCounterInstrumentListener(org.apache.excalibur.instrument.manager.CounterInstrumentListener listener)

Adds a CounterInstrumentListener to the list of listeners which will receive updates of the value of the Instrument.

Parameters:

listener - CounterInstrumentListener which will start receiving updates.

Throws:

java.lang.IllegalStateException - If the Instrument's type is not InstrumentManager.INSTRUMENT_TYPE_COUNTER.

removeCounterInstrumentListener

void removeCounterInstrumentListener(org.apache.excalibur.instrument.manager.CounterInstrumentListener listener)

Removes a InstrumentListener from the list of listeners which will receive events.

Parameters:

listener - InstrumentListener which will stop receiving events.

Throws:

java.lang.IllegalStateException - If the Instrument's type is not InstrumentManager.INSTRUMENT_TYPE_COUNTER.

addValueInstrumentListener

void addValueInstrumentListener(org.apache.excalibur.instrument.manager.ValueInstrumentListener listener)

Adds a ValueInstrumentListener to the list of listeners which will receive updates of the value of the Instrument.

Parameters:

listener - ValueInstrumentListener which will start receiving updates.

Throws:

java.lang.IllegalStateException - If the Instrument's type is not InstrumentManager.INSTRUMENT_TYPE_VALUE.

removeValueInstrumentListener

void removeValueInstrumentListener(org.apache.excalibur.instrument.manager.ValueInstrumentListener listener)

Removes a InstrumentListener from the list of listeners which will receive events.

Parameters:

listener - InstrumentListener which will stop receiving events.

Throws:

java.lang.IllegalStateException - If the Instrument's type is not InstrumentManager.INSTRUMENT_TYPE_VALUE.

addInstrumentSample

private void addInstrumentSample(InstrumentSample instrumentSample)

Add a InstrumentSample to the Instrument.

Parameters:

InstrumentSample - InstrumentSample to be added.

removeInstrumentSample

void removeInstrumentSample(InstrumentSample instrumentSample)

Removes an InstrumentSample from the Instrument.

Parameters:

InstrumentSample - InstrumentSample to be removed.

getInstrumentSample

InstrumentSample getInstrumentSample(java.lang.String instrumentSampleName)

Returns a InstrumentSample based on its name.

Parameters:

instrumentSampleName - Name of the InstrumentSample being requested.

Returns:

The requested InstrumentSample or null if does not exist.

getInstrumentSamples

InstrumentSample[] getInstrumentSamples()

Returns an array of the InstrumentSamples in the Instrument.

Returns:

An array of the InstrumentSamples in the Instrument.

createInstrumentSample

InstrumentSample createInstrumentSample(java.lang.String sampleDescription,
                                      long sampleInterval,
                                      int sampleSize,
                                      long sampleLease,
                                      int sampleType)

Returns an InstrumentSampleDescriptor based on its name. If the requested sample is invalid in any way, then an expired Descriptor will be returned.

Parameters:

sampleDescription - Description to assign to the new Sample.

sampleInterval - Sample interval to use in the new Sample.

sampleLease - Requested lease time for the new Sample in milliseconds. The InstrumentManager may grant a lease which is shorter or longer than the requested period.

sampleType - Type of sample to request. Must be one of the following: DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_COUNTER, DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MINIMUM, DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MAXIMUM, DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MEAN.

Returns:

The requested InstrumentSample.

Throws:

NoSuchInstrumentSampleException - If the specified InstrumentSample does not exist.

getInstrumentSampleDescriptors

org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor[] getInstrumentSampleDescriptors()

Returns an array of Descriptors for the InstrumentSamples in the Instrument.

Returns:

An array of Descriptors for the InstrumentSamples in the Instrument.

getStateVersion

int getStateVersion()

Returns the stateVersion of the instrument. The state version will be incremented each time any of the configuration of the instrument or any of its children 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 instrument.

addInstrumentListener

private void addInstrumentListener(org.apache.excalibur.instrument.manager.InstrumentListener listener)

Common code to add a listener to the list of listeners which will receive updates of the value of the Instrument.

Parameters:

listener - InstrumentListener which will start receiving updates.

removeInstrumentListener

private void removeInstrumentListener(org.apache.excalibur.instrument.manager.InstrumentListener listener)

Common code to remove a listener from the list of listeners which will receive updates of the value of the Instrument.

Parameters:

listener - InstrumentListener which will stop receiving updates.

updateInstrumentSampleArray

private InstrumentSample[] updateInstrumentSampleArray()

Updates the cached array of InstrumentSamples taking synchronization into account.

Returns:

An array of the InstrumentSamples.

updateInstrumentSampleDescriptorArray

private org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor[] updateInstrumentSampleDescriptorArray()

Updates the cached array of InstrumentSampleDescriptors taking synchronization into account.

Returns:

An array of the InstrumentSampleDescriptors.

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.

loadSampleState

InstrumentSample loadSampleState(org.apache.avalon.framework.configuration.Configuration state)
                           throws org.apache.avalon.framework.configuration.ConfigurationException

Loads the state of an Instrument Sample. If the does not exist and the sample is leased then it will be created.

Parameters:

state - Configuration object to load state from.

Returns:

The sample into which the state was loaded. If the sample did not exist and was not created then null is returned.

Throws:

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

stateChanged

protected void stateChanged()

Called whenever the state of the instrument is changed.

getTypeName

public static java.lang.String getTypeName(int type)

Returns the name of a Instrument type.

Parameters:

type - Type whose name is wanted.

Returns:

The name of a Instrument type.