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

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.excalibur.instrument.manager.impl.DefaultInstrumentManagerImpl

All Implemented Interfaces:

Configurable, DefaultInstrumentManager, Disposable, Initializable, Instrumentable, InstrumentManager, LogEnabled, java.lang.Runnable

public class DefaultInstrumentManagerImpl

extends AbstractLogEnabled

implements Configurable, Initializable, Disposable, DefaultInstrumentManager, Instrumentable, java.lang.Runnable

Since:

4.1

Version:

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

Author:

Avalon Development Team

Field Summary

Fields inherited from interface org.apache.excalibur.instrument.manager.DefaultInstrumentManager

INSTRUMENT_SAMPLE_TYPE_COUNTER, INSTRUMENT_SAMPLE_TYPE_MAXIMUM, INSTRUMENT_SAMPLE_TYPE_MEAN, INSTRUMENT_SAMPLE_TYPE_MINIMUM, INSTRUMENT_TYPE_COUNTER, INSTRUMENT_TYPE_NONE, INSTRUMENT_TYPE_VALUE

Fields inherited from interface org.apache.excalibur.instrument.InstrumentManager

ROLE

Fields inherited from interface org.apache.excalibur.instrument.Instrumentable

EMPTY_INSTRUMENT_ARRAY, EMPTY_INSTRUMENTABLE_ARRAY

Constructor Summary

DefaultInstrumentManagerImpl()
Creates a new DefaultInstrumentManagerImpl.

DefaultInstrumentManagerImpl(java.lang.String name)
Deprecated. Name should be set in the instrument configuration file.

Method Summary

void	configure(Configuration configuration) Initializes the configured instrumentables.
void	dispose() Disposes the InstrumentManager.
Instrumentable[]	getChildInstrumentables() Any Object which implements Instrumentable can also make use of other Instrumentable child objects.
java.lang.String	getDescription() Returns the description of this DefaultInstrumentManager.
InstrumentableDescriptor	getInstrumentableDescriptor(java.lang.String instrumentableName) Returns a InstrumentableDescriptor based on its name or the name of any of its children.
InstrumentableDescriptor[]	getInstrumentableDescriptors() Returns an array of Descriptors for the Instrumentables managed by this DefaultInstrumentManager.
java.lang.String	getInstrumentableName() Gets the name of the Instrumentable.
Instrument[]	getInstruments() Obtain a reference to all the Instruments that the Instrumentable object wishes to expose.
int	getLeaseSampleCount() Returns the current number of leased samples.
long	getMaxLeasedSampleLease() Returns the maximum number of milliseconds that a lease will be granted for.
int	getMaxLeasedSamples() Returns the maximum number of leased samples that will be approved.
int	getMaxLeasedSampleSize() Returns the maximum size of a leased sample.
java.lang.String	getName() Returns the name used to identify this DefaultInstrumentManager.
int	getStateVersion() Returns the stateVersion of the DefaultInstrumeManager.
void	initialize() Initializes the InstrumentManager.
void	invokeGarbageCollection() Invokes garbage collection.
void	loadStateFromConfiguration(Configuration state) Loads the Instrument Manager state from the specified Configuration.
void	loadStateFromFile(java.io.File stateFile) Loads the Instrument Manager state from the specified file.
void	loadStateFromStream(java.io.InputStream is) Loads the Instrument Manager state from the specified stream.
InstrumentableDescriptor	locateInstrumentableDescriptor(java.lang.String instrumentableName) Searches the entire instrument tree for an instrumentable with the given name.
InstrumentDescriptor	locateInstrumentDescriptor(java.lang.String instrumentName) Searches the entire instrument tree for an instrument with the given name.
InstrumentSampleDescriptor	locateInstrumentSampleDescriptor(java.lang.String sampleName) Searches the entire instrument tree for an instrument sample with the given name.
void	registerInstrumentable(Instrumentable instrumentable, java.lang.String instrumentableName) Instrumentable to be registered with the instrument manager.
void	registerNameTranslation(java.lang.String source, java.lang.String target) Registers a name translation that will be applied to all named based lookups of instrumentables, instruments, and samples.
void	run()
void	saveStateToFile(java.io.File stateFile) Saves the Instrument Manager's state to the specified file.
void	saveStateToStream(java.io.OutputStream os) Saves the Instrument Manager's state to the specified output stream.
void	setInstrumentableName(java.lang.String name) Sets the name for the Instrumentable.

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

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultInstrumentManagerImpl

public DefaultInstrumentManagerImpl(java.lang.String name)

Deprecated. Name should be set in the instrument configuration file.

Creates a new DefaultInstrumentManagerImpl.

Parameters:

name - The name used to identify this InstrumentManager. Should not contain any spaces or periods.

DefaultInstrumentManagerImpl

public DefaultInstrumentManagerImpl()

Creates a new DefaultInstrumentManagerImpl.

Method Detail

configure

public void configure(Configuration configuration)
               throws ConfigurationException

Initializes the configured instrumentables.

Specified by:

configure in interface Configurable

Parameters:

configuration - InstrumentManager configuration.

Throws:

ConfigurationException - If there are any configuration problems.

initialize

public void initialize()
                throws java.lang.Exception

Initializes the InstrumentManager.

Specified by:

initialize in interface Initializable

Throws:

java.lang.Exception - If there were any problems initializing the object.

dispose

public void dispose()

Disposes the InstrumentManager.

Specified by:

dispose in interface Disposable

registerInstrumentable

public void registerInstrumentable(Instrumentable instrumentable,
                                   java.lang.String instrumentableName)
                            throws java.lang.Exception

Instrumentable to be registered with the instrument manager. Should be called whenever an Instrumentable is created. The '.' character is used to denote a child Instrumentable and can be used to register the instrumentable at a specific point in an instrumentable hierarchy.

Specified by:

registerInstrumentable in interface InstrumentManager

Parameters:

instrumentable - Instrumentable to register with the InstrumentManager.

instrumentableName - The name to use when registering the Instrumentable.

Throws:

java.lang.Exception - If there were any problems registering the Instrumentable.

getName

public java.lang.String getName()

Returns the name used to identify this DefaultInstrumentManager.

Specified by:

getName in interface DefaultInstrumentManager

Returns:

The name used to identify this DefaultInstrumentManager.

getDescription

public java.lang.String getDescription()

Returns the description of this DefaultInstrumentManager.

Specified by:

getDescription in interface DefaultInstrumentManager

Returns:

The description of this DefaultInstrumentManager.

registerNameTranslation

public void registerNameTranslation(java.lang.String source,
                                    java.lang.String target)
                             throws java.lang.IllegalArgumentException

Registers a name translation that will be applied to all named based lookups of instrumentables, instruments, and samples. The more translations that are registered, the greater the impact on name based lookups will be.

General operation of the instrument manager will not be affected as collection on sample data is always done using direct object references.

Translations can be registered for exact name matches, or for the bases of names. Any translation which ends in a '.' will imply a translation to any name beginning with that name base. If the source ends with a '.' then the target must as well.

Parameters:

source - The source name or name base of the translation.

target - The target name or name base of the translation.

Throws:

java.lang.IllegalArgumentException - If the one but not both of the source and target parameters end in '.'.

getInstrumentableDescriptor

public InstrumentableDescriptor getInstrumentableDescriptor(java.lang.String instrumentableName)
                                                     throws NoSuchInstrumentableException

Returns a InstrumentableDescriptor based on its name or the name of any of its children.

Specified by:

getInstrumentableDescriptor in interface DefaultInstrumentManager

Parameters:

instrumentableName - Name of the Instrumentable being requested.

Returns:

A Descriptor of the requested Instrumentable.

Throws:

NoSuchInstrumentableException - If the specified Instrumentable does not exist.

getInstrumentableDescriptors

public InstrumentableDescriptor[] getInstrumentableDescriptors()

Returns an array of Descriptors for the Instrumentables managed by this DefaultInstrumentManager.

Specified by:

getInstrumentableDescriptors in interface DefaultInstrumentManager

Returns:

An array of InstrumentableDescriptors.

locateInstrumentableDescriptor

public InstrumentableDescriptor locateInstrumentableDescriptor(java.lang.String instrumentableName)
                                                        throws NoSuchInstrumentableException

Searches the entire instrument tree for an instrumentable with the given name.

Specified by:

locateInstrumentableDescriptor in interface DefaultInstrumentManager

Parameters:

instrumentableName - Name of the Instrumentable being requested.

Returns:

A Descriptor of the requested Instrumentable.

Throws:

NoSuchInstrumentableException - If the specified Instrumentable does not exist.

locateInstrumentDescriptor

public InstrumentDescriptor locateInstrumentDescriptor(java.lang.String instrumentName)
                                                throws NoSuchInstrumentException

Searches the entire instrument tree for an instrument with the given name.

Specified by:

locateInstrumentDescriptor in interface DefaultInstrumentManager

Parameters:

instrumentName - Name of the Instrument being requested.

Returns:

A Descriptor of the requested Instrument.

Throws:

NoSuchInstrumentException - If the specified Instrument does not exist.

locateInstrumentSampleDescriptor

public InstrumentSampleDescriptor locateInstrumentSampleDescriptor(java.lang.String sampleName)
                                                            throws NoSuchInstrumentSampleException

Searches the entire instrument tree for an instrument sample with the given name.

Specified by:

locateInstrumentSampleDescriptor in interface DefaultInstrumentManager

Parameters:

sampleName - Name of the Instrument Sample being requested.

Returns:

A Descriptor of the requested Instrument Sample.

Throws:

NoSuchInstrumentSampleException - If the specified Instrument Sample does not exist.

getStateVersion

public int getStateVersion()

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

Specified by:

getStateVersion in interface DefaultInstrumentManager

Returns:

The state version of the instrument manager.

invokeGarbageCollection

public void invokeGarbageCollection()

Invokes garbage collection.

Specified by:

invokeGarbageCollection in interface DefaultInstrumentManager

getLeaseSampleCount

public int getLeaseSampleCount()

Returns the current number of leased samples.

Specified by:

getLeaseSampleCount in interface DefaultInstrumentManager

Returns:

The current number of leased samples.

getMaxLeasedSamples

public int getMaxLeasedSamples()

Returns the maximum number of leased samples that will be approved.

Specified by:

getMaxLeasedSamples in interface DefaultInstrumentManager

Returns:

The maximum number of leased samples.

getMaxLeasedSampleSize

public int getMaxLeasedSampleSize()

Returns the maximum size of a leased sample.

Specified by:

getMaxLeasedSampleSize in interface DefaultInstrumentManager

Returns:

The maximum size of a leased sample.

getMaxLeasedSampleLease

public long getMaxLeasedSampleLease()

Returns the maximum number of milliseconds that a lease will be granted for.

Specified by:

getMaxLeasedSampleLease in interface DefaultInstrumentManager

Returns:

The maximum lease length.

setInstrumentableName

public void setInstrumentableName(java.lang.String name)

Sets the name for the Instrumentable. The Instrumentable Name is used to uniquely identify the Instrumentable during the configuration of the InstrumentManager and to gain access to an InstrumentableDescriptor through the InstrumentManager. The value should be a string which does not contain spaces or periods.

This value may be set by a parent Instrumentable, or by the InstrumentManager using the value of the 'instrumentable' attribute in the configuration of the component.

Specified by:

setInstrumentableName in interface Instrumentable

Parameters:

name - The name used to identify a Instrumentable.

getInstrumentableName

public java.lang.String getInstrumentableName()

Gets the name of the Instrumentable.

Specified by:

getInstrumentableName in interface Instrumentable

Returns:

The name used to identify a Instrumentable.

getInstruments

public Instrument[] getInstruments()

Obtain a reference to all the Instruments that the Instrumentable object wishes to expose. All sampling is done directly through the Instruments as opposed to the Instrumentable interface.

Specified by:

getInstruments in interface Instrumentable

Returns:

An array of the Instruments available for profiling. Should never be null. If there are no Instruments, then EMPTY_INSTRUMENT_ARRAY can be returned. This should never be the case though unless there are child Instrumentables with Instruments.

getChildInstrumentables

public Instrumentable[] getChildInstrumentables()

Any Object which implements Instrumentable can also make use of other Instrumentable child objects. This method is used to tell the InstrumentManager about them.

Specified by:

getChildInstrumentables in interface Instrumentable

Returns:

An array of child Instrumentables. This method should never return null. If there are no child Instrumentables, then EMPTY_INSTRUMENTABLE_ARRAY can be returned.

run

public void run()

Specified by:

run in interface java.lang.Runnable

loadStateFromFile

public void loadStateFromFile(java.io.File stateFile)
                       throws java.lang.Exception

Loads the Instrument Manager state from the specified file.

Parameters:

stateFile - File to read the instrument manager's state from.

Throws:

java.lang.Exception - if there are any problems loading the state.

loadStateFromStream

public void loadStateFromStream(java.io.InputStream is)
                         throws java.lang.Exception

Loads the Instrument Manager state from the specified stream.

Parameters:

is - Stream to read the instrument manager's state from.

Throws:

java.lang.Exception - if there are any problems loading the state.

loadStateFromConfiguration

public void loadStateFromConfiguration(Configuration state)
                                throws ConfigurationException

Loads the Instrument Manager state from the specified Configuration.

Parameters:

state - Configuration object to load the state from.

Throws:

ConfigurationException - If there were any problems loading the state.

saveStateToFile

public void saveStateToFile(java.io.File stateFile)
                     throws java.lang.Exception

Saves the Instrument Manager's state to the specified file. Any existing file is backed up before the save takes place and replaced in the event of an error.

Parameters:

stateFile - File to write the Instrument Manager's state to.

Throws:

java.lang.Exception - if there are any problems saving the state.

saveStateToStream

public void saveStateToStream(java.io.OutputStream os)
                       throws java.lang.Exception

Saves the Instrument Manager's state to the specified output stream.

Parameters:

os - Stream to write the Instrument Manager's state to.

Throws:

java.lang.Exception - if there are any problems saving the state.