Keel 2.1RC2

org.apache.excalibur.instrument.manager
Class InstrumentProxy

java.lang.Object
  extended byorg.apache.avalon.framework.logger.AbstractLogEnabled
      extended byorg.apache.excalibur.instrument.manager.InstrumentProxy
All Implemented Interfaces:
Configurable, InstrumentProxy, LogEnabled

public class InstrumentProxy
extends AbstractLogEnabled
implements InstrumentProxy, 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 profiled 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:

Field Summary
private  boolean m_configured
          Configured flag.
private  java.lang.String m_description
          The description of the Instrumente.
private  InstrumentDescriptorLocal 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  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  InstrumentSampleDescriptorLocal[] m_sampleDescriptorArray
          Optimized array of the InstrumentSampleDescriptorLocals.
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  Logger m_valueLogger
          Child logger to use for logging of new values.
 
Fields inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled
 
Constructor Summary
(package private) InstrumentProxy(InstrumentableProxy instrumentableProxy, java.lang.String name, java.lang.String description)
          Creates a new InstrumentProxy.
 
Method Summary
(package private)  void addCounterInstrumentListener(CounterInstrumentListener listener)
          Adds a CounterInstrumentListener to the list of listeners which will receive updates of the value of the Instrument.
private  void addInstrumentListener(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(ValueInstrumentListener listener)
          Adds a ValueInstrumentListener to the list of listeners which will receive updates of the value of the Instrument.
 void configure(Configuration configuration)
          Configures the Instrument.
(package private)  InstrumentSample createInstrumentSample(java.lang.String sampleDescription, long sampleInterval, int sampleSize, long sampleLease, int sampleType)
          Returns a InstrumentSampleDescriptorLocal based on its name.
 void enableLogging(Logger logger)
          Set the components logger.
(package private)  java.lang.String getDescription()
          Gets the description of the Instrument.
(package private)  InstrumentDescriptorLocal 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)  InstrumentSampleDescriptorLocal[] 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 profiles 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)  void loadState(Configuration state)
          Loads the state into the Instrument.
(package private)  void removeCounterInstrumentListener(CounterInstrumentListener listener)
          Removes a InstrumentListener from the list of listeners which will receive profile events.
private  void removeInstrumentListener(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(ValueInstrumentListener listener)
          Removes a InstrumentListener from the list of listeners which will receive profile events.
(package private)  Configuration saveState()
          Saves the current state into a Configuration.
(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  InstrumentSampleDescriptorLocal[] updateInstrumentSampleDescriptorArray()
          Updates the cached array of InstrumentSampleDescriptorLocals taking synchronization into account.
 
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 InstrumentDescriptorLocal m_descriptor
The Descriptor for the Instrument.


m_type

private int m_type
Type of the Instrument


m_listeners

private 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 InstrumentSampleDescriptorLocal[] m_sampleDescriptorArray
Optimized array of the InstrumentSampleDescriptorLocals.


m_valueLogger

private 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(Logger logger)
Description copied from class: AbstractLogEnabled
Set the components logger.

Specified by:
enableLogging in interface LogEnabled
Overrides:
enableLogging in class AbstractLogEnabled
Parameters:
logger - the logger

configure

public void configure(Configuration configuration)
               throws 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 Configurable
Parameters:
configuration - Instrument configuration element from the InstrumentManager's configuration.
Throws:
ConfigurationException - If there are any configuration problems.

isActive

public boolean isActive()
Used by classes being profiles so that they can avoid unnecessary code when the data from a Instrument is not being used.

Specified by:
isActive in interface InstrumentProxy
Returns:
True if listeners are registered with the Instrument.

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 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 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 the configuration of the Profiler and to gain access to a InstrumentDescriptor through a 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 the configuration of the profiler 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

InstrumentDescriptorLocal 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(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 profile updates.
Throws:
java.lang.IllegalStateException - If the Instrument's type is not InstrumentManager.INSTRUMENT_TYPE_COUNTER.

removeCounterInstrumentListener

void removeCounterInstrumentListener(CounterInstrumentListener listener)
Removes a InstrumentListener from the list of listeners which will receive profile events.

Parameters:
listener - InstrumentListener which will stop receiving profile events.
Throws:
java.lang.IllegalStateException - If the Instrument's type is not InstrumentManager.INSTRUMENT_TYPE_COUNTER.

addValueInstrumentListener

void addValueInstrumentListener(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 profile updates.
Throws:
java.lang.IllegalStateException - If the Instrument's type is not InstrumentManager.INSTRUMENT_TYPE_VALUE.

removeValueInstrumentListener

void removeValueInstrumentListener(ValueInstrumentListener listener)
Removes a InstrumentListener from the list of listeners which will receive profile events.

Parameters:
listener - InstrumentListener which will stop receiving profile 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.


removeInstrumentSample

void removeInstrumentSample(InstrumentSample instrumentSample)
Removes an InstrumentSample from the Instrument.


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 a InstrumentSampleDescriptorLocal 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: InstrumentManagerClient.INSTRUMENT_SAMPLE_TYPE_COUNTER, InstrumentManagerClient.INSTRUMENT_SAMPLE_TYPE_MINIMUM, InstrumentManagerClient.INSTRUMENT_SAMPLE_TYPE_MAXIMUM, InstrumentManagerClient.INSTRUMENT_SAMPLE_TYPE_MEAN.
Returns:
The requested InstrumentSample.
Throws:
NoSuchInstrumentSampleException - If the specified InstrumentSample does not exist.

getInstrumentSampleDescriptors

InstrumentSampleDescriptorLocal[] 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(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 profile updates.

removeInstrumentListener

private void removeInstrumentListener(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 profile updates.

updateInstrumentSampleArray

private InstrumentSample[] updateInstrumentSampleArray()
Updates the cached array of InstrumentSamples taking synchronization into account.

Returns:
An array of the InstrumentSamples.

updateInstrumentSampleDescriptorArray

private InstrumentSampleDescriptorLocal[] updateInstrumentSampleDescriptorArray()
Updates the cached array of InstrumentSampleDescriptorLocals taking synchronization into account.

Returns:
An array of the InstrumentSampleDescriptors.

saveState

Configuration saveState()
Saves the current state into a Configuration.

Returns:
The state as a Configuration. Returns null if the configuration would not contain any information.

loadState

void loadState(Configuration state)
         throws ConfigurationException
Loads the state into the Instrument.

Parameters:
state - Configuration object to load state from.
Throws:
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.

Keel 2.1RC2

Please see keelframework.org for information about new Keel releases.