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

java.lang.Object
  extended by org.apache.avalon.framework.logger.AbstractLogEnabled
      extended by 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
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
InstrumentProxy(InstrumentableProxy instrumentableProxy, java.lang.String name, java.lang.String description)
          Creates a new InstrumentProxy.
 
Method Summary
(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.