Keel 2.1RC2

org.apache.excalibur.instrument.manager
Class DefaultInstrumentManager

java.lang.Object
  extended byorg.apache.avalon.framework.logger.AbstractLogEnabled
      extended byorg.apache.excalibur.instrument.manager.DefaultInstrumentManager
All Implemented Interfaces:
Configurable, Disposable, Initializable, Instrumentable, InstrumentManager, LogEnabled, java.lang.Runnable

public class DefaultInstrumentManager
extends AbstractLogEnabled
implements Configurable, Initializable, Disposable, InstrumentManager, Instrumentable, java.lang.Runnable

Since:
4.1
Version:
CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:25 $
Author:

Field Summary
static java.lang.String INSTRUMENT_ACTIVE_THREAD_COUNT
           
static java.lang.String INSTRUMENT_FREE_MEMORY
           
static java.lang.String INSTRUMENT_MEMORY
           
static java.lang.String INSTRUMENT_TOTAL_MEMORY
           
private  ValueInstrument m_activeThreadCountInstrument
          Instrument used to profile the active thread count of the JVM.
private  Configuration m_configuration
          Configuration for the InstrumentManager
private  java.util.ArrayList m_connectors
          List of configured connectors.
private  java.lang.String m_description
          The description of this InstrumentManager.
private  ValueInstrument m_freeMemoryInstrument
          Instrument used to profile the free memory.
private  InstrumentableDescriptorLocal[] m_instrumentableDescriptorArray
          Optimized array of the InstrumentableDescriptorLocals.
private  java.lang.String m_instrumentableName
          Instrumentable Name assigned to this Instrumentable
private  java.util.HashMap m_instrumentableProxies
          HashMap of all of the registered InstrumentableProxies by their keys.
private  InstrumentableProxy[] m_instrumentableProxyArray
          Optimized array of the InstrumentableProxies.
private  long m_lastStateSave
          Last time that the state was saved.
private  InstrumentSample[] m_leasedInstrumentSampleArray
          Optimized array of the leased InstrumentSamples.
private  java.util.ArrayList m_leasedInstrumentSamples
          List of leased InstrumentSamples.
private  ValueInstrument m_memoryInstrument
          Instrument used to profile the in use memory.
private  java.lang.String m_name
          The name used to identify this InstrumentManager.
private  java.lang.Thread m_runner
          Thread used to keep the instruments published by the InstrumentManager up to date.
private  java.lang.Object m_semaphore
          Semaphore for actions which must be synchronized
private  java.io.File m_stateFile
          State file.
private  long m_stateInterval
          Save state interval.
private  int m_stateVersion
          State Version.
private  ValueInstrument m_totalMemoryInstrument
          Instrument used to profile the total memory.
 
Fields inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled
 
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
DefaultInstrumentManager()
          Creates a new DefaultInstrumentManager.
DefaultInstrumentManager(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 InstrumentManager.
 InstrumentableDescriptorLocal getInstrumentableDescriptor(java.lang.String instrumentableName)
          Returns an InstrumentableDescriptorLocal based on its name or the name of any of its children.
 InstrumentableDescriptorLocal[] getInstrumentableDescriptors()
          Returns an array of Descriptors for the Instrumentables managed by this InstrumentManager.
 java.lang.String getInstrumentableName()
          Gets the name of the Instrumentable.
private  InstrumentableProxy getInstrumentableProxy(java.lang.String instrumentableName)
          Returns a InstrumentableDescriptor based on its name or the name of any of its children.
 Instrument[] getInstruments()
          Obtain a reference to all the Instruments that the Instrumentable object wishes to expose.
 java.lang.String getName()
          Returns the name used to identify this InstrumentManager.
(package private)  int getStateVersion()
          Returns the stateVersion of the instrument manager.
 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.
private  InstrumentableProxy locateDeepestInstrumentableProxy(java.lang.String instrumentableName)
          Given the name of an instrumentable proxy, locate the deepest child instrumentable given the name.
 InstrumentableDescriptorLocal locateInstrumentableDescriptor(java.lang.String instrumentableName)
          Searches the entire instrument tree an instrumentable with the given name.
 InstrumentDescriptorLocal locateInstrumentDescriptor(java.lang.String instrumentName)
          Searches the entire instrument tree an instrument with the given name.
 InstrumentSampleDescriptorLocal locateInstrumentSampleDescriptor(java.lang.String sampleName)
          Searches the entire instrument tree an instrument sample with the given name.
private  void memoryInstruments()
          Updates the Memory based Profile Points published by the InstrumentManager.
private  void registerDummyInstrumentableInner(Instrumentable instrumentable, InstrumentableProxy instrumentableProxy, java.lang.String instrumentableName, java.lang.String childName)
          Called as a place holder to handle the registration of instrumentables that do not really exist.
 void registerInstrumentable(Instrumentable instrumentable, java.lang.String instrumentableName)
          Instrumentable to be registered with the instrument manager.
private  void registerInstrumentableInner(Instrumentable instrumentable, InstrumentableProxy instrumentableProxy, java.lang.String instrumentableName)
          Examines a instrumentable and Registers all of its child Instrumentables and Instruments.
(package private)  void registerLeasedInstrumentSample(InstrumentSample instrumentSample)
          Registers an InstrumentSample which has been leased so that the Instrument Manager can efficiently purge it when it has expired.
 void run()
           
private  void saveState()
          Saves the state to the current state file if configured.
 Configuration saveStateToConfiguration()
          Returns the Instrument Manager's state as a Configuration object.
 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.
protected  void stateChanged()
          Called whenever the state of the instrument manager is changed.
private  void testInstrumentSampleLeases()
          Handles the maintenance of all Instrument Samples which have been leased by a client.
private  void threadInstruments()
          Updates the Thread based Profile Points published by the InstrumentManager.
private  InstrumentableDescriptorLocal[] updateInstrumentableDescriptorArray()
          Updates the cached array of InstrumentableDescriptorLocals taking synchronization into account.
private  InstrumentableProxy[] updateInstrumentableProxyArray()
          Updates the cached array of InstrumentableProxies taking synchronization into account.
 
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
 

Field Detail

INSTRUMENT_TOTAL_MEMORY

public static final java.lang.String INSTRUMENT_TOTAL_MEMORY
See Also:
Constant Field Values

INSTRUMENT_FREE_MEMORY

public static final java.lang.String INSTRUMENT_FREE_MEMORY
See Also:
Constant Field Values

INSTRUMENT_MEMORY

public static final java.lang.String INSTRUMENT_MEMORY
See Also:
Constant Field Values

INSTRUMENT_ACTIVE_THREAD_COUNT

public static final java.lang.String INSTRUMENT_ACTIVE_THREAD_COUNT
See Also:
Constant Field Values

m_name

private java.lang.String m_name
The name used to identify this InstrumentManager.


m_description

private java.lang.String m_description
The description of this InstrumentManager.


m_configuration

private Configuration m_configuration
Configuration for the InstrumentManager


m_connectors

private java.util.ArrayList m_connectors
List of configured connectors.


m_stateFile

private java.io.File m_stateFile
State file.


m_stateInterval

private long m_stateInterval
Save state interval.


m_lastStateSave

private long m_lastStateSave
Last time that the state was saved.


m_semaphore

private java.lang.Object m_semaphore
Semaphore for actions which must be synchronized


m_instrumentableProxies

private java.util.HashMap m_instrumentableProxies
HashMap of all of the registered InstrumentableProxies by their keys.


m_instrumentableProxyArray

private InstrumentableProxy[] m_instrumentableProxyArray
Optimized array of the InstrumentableProxies.


m_instrumentableDescriptorArray

private InstrumentableDescriptorLocal[] m_instrumentableDescriptorArray
Optimized array of the InstrumentableDescriptorLocals.


m_leasedInstrumentSamples

private java.util.ArrayList m_leasedInstrumentSamples
List of leased InstrumentSamples.


m_leasedInstrumentSampleArray

private InstrumentSample[] m_leasedInstrumentSampleArray
Optimized array of the leased InstrumentSamples.


m_runner

private java.lang.Thread m_runner
Thread used to keep the instruments published by the InstrumentManager up to date.


m_instrumentableName

private java.lang.String m_instrumentableName
Instrumentable Name assigned to this Instrumentable


m_totalMemoryInstrument

private ValueInstrument m_totalMemoryInstrument
Instrument used to profile the total memory.


m_freeMemoryInstrument

private ValueInstrument m_freeMemoryInstrument
Instrument used to profile the free memory.


m_memoryInstrument

private ValueInstrument m_memoryInstrument
Instrument used to profile the in use memory.


m_activeThreadCountInstrument

private ValueInstrument m_activeThreadCountInstrument
Instrument used to profile the active thread count of the JVM.


m_stateVersion

private int m_stateVersion
State Version.

Constructor Detail

DefaultInstrumentManager

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

Creates a new DefaultInstrumentManager.

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

DefaultInstrumentManager

public DefaultInstrumentManager()
Creates a new DefaultInstrumentManager.

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 InstrumentManager.

Returns:
The name used to identify this InstrumentManager.

getDescription

public java.lang.String getDescription()
Returns the description of this InstrumentManager.

Returns:
The description of this InstrumentManager.

getInstrumentableDescriptor

public InstrumentableDescriptorLocal getInstrumentableDescriptor(java.lang.String instrumentableName)
                                                          throws NoSuchInstrumentableException
Returns an InstrumentableDescriptorLocal based on its name or the name of any of its children.

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 InstrumentableDescriptorLocal[] getInstrumentableDescriptors()
Returns an array of Descriptors for the Instrumentables managed by this InstrumentManager.

Returns:
An array of Descriptors for the Instrumentables managed by this InstrumentManager.

locateInstrumentableDescriptor

public InstrumentableDescriptorLocal locateInstrumentableDescriptor(java.lang.String instrumentableName)
                                                             throws NoSuchInstrumentableException
Searches the entire instrument tree an instrumentable with the given name.

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 InstrumentDescriptorLocal locateInstrumentDescriptor(java.lang.String instrumentName)
                                                     throws NoSuchInstrumentException
Searches the entire instrument tree an instrument with the given name.

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 InstrumentSampleDescriptorLocal locateInstrumentSampleDescriptor(java.lang.String sampleName)
                                                                 throws NoSuchInstrumentSampleException
Searches the entire instrument tree an instrument sample with the given name.

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

int getStateVersion()
Returns the stateVersion of the instrument manager. 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.

Returns:
The state version of the instrument manager.

invokeGarbageCollection

public void invokeGarbageCollection()
Invokes garbage collection.


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.

saveStateToConfiguration

public Configuration saveStateToConfiguration()
Returns the Instrument Manager's state as a Configuration object.

Returns:
The Instrument Manager's state as a Configuration object.

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

saveState

private void saveState()
Saves the state to the current state file if configured.


getInstrumentableProxy

private InstrumentableProxy getInstrumentableProxy(java.lang.String instrumentableName)
Returns a InstrumentableDescriptor based on its name or the name of any of its children.

Parameters:
instrumentableName - Name of the Instrumentable being requested.
Returns:
A Proxy of the requested Instrumentable or null if not found.

locateDeepestInstrumentableProxy

private InstrumentableProxy locateDeepestInstrumentableProxy(java.lang.String instrumentableName)
Given the name of an instrumentable proxy, locate the deepest child instrumentable given the name. The name can be the name of an instrumentable or of any of its children.

Parameters:
instrumentableName - Fully qualified name of the instrumentable being requested, or of any of its children.
Returns:
The requested instrumentable, or null if not found.

memoryInstruments

private void memoryInstruments()
Updates the Memory based Profile Points published by the InstrumentManager.


threadInstruments

private void threadInstruments()
Updates the Thread based Profile Points published by the InstrumentManager.


testInstrumentSampleLeases

private void testInstrumentSampleLeases()
Handles the maintenance of all Instrument Samples which have been leased by a client. Any Samples whose leases which have expired are cleaned up.


registerLeasedInstrumentSample

void registerLeasedInstrumentSample(InstrumentSample instrumentSample)
Registers an InstrumentSample which has been leased so that the Instrument Manager can efficiently purge it when it has expired.

Parameters:
instrumentSample - Leased InstrumentSample to register.

updateInstrumentableProxyArray

private InstrumentableProxy[] updateInstrumentableProxyArray()
Updates the cached array of InstrumentableProxies taking synchronization into account.

Returns:
An array of the InstrumentableProxies.

updateInstrumentableDescriptorArray

private InstrumentableDescriptorLocal[] updateInstrumentableDescriptorArray()
Updates the cached array of InstrumentableDescriptorLocals taking synchronization into account.

Returns:
An array of the InstrumentableDescriptors.

registerDummyInstrumentableInner

private void registerDummyInstrumentableInner(Instrumentable instrumentable,
                                              InstrumentableProxy instrumentableProxy,
                                              java.lang.String instrumentableName,
                                              java.lang.String childName)
                                       throws java.lang.Exception
Called as a place holder to handle the registration of instrumentables that do not really exist. This makes it possible to register instrumentables at arbitrary locations in the instrumentable hierarchy.

Parameters:
instrumentable - The instrumentable that was registered below a dummy parent.
instrumentableProxy - The proxy assigned to the current placeholder instrumentable.
instrumentableName - The name of the current placeholder instrumentable.
childName - The name of the child instrumentable to register. May contain further '.' characters.
Throws:
java.lang.Exception

registerInstrumentableInner

private void registerInstrumentableInner(Instrumentable instrumentable,
                                         InstrumentableProxy instrumentableProxy,
                                         java.lang.String instrumentableName)
                                  throws java.lang.Exception
Examines a instrumentable and Registers all of its child Instrumentables and Instruments.

Only called when m_semaphore is locked.

Throws:
java.lang.Exception

stateChanged

protected void stateChanged()
Called whenever the state of the instrument manager is changed.


Keel 2.1RC2

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