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

java.lang.Object
  extended by org.apache.avalon.framework.logger.AbstractLogEnabled
      extended by org.apache.excalibur.instrument.manager.impl.AbstractInstrumentSample
All Implemented Interfaces:
org.apache.avalon.framework.logger.LogEnabled, InstrumentSample
Direct Known Subclasses:
AbstractValueInstrumentSample, CounterInstrumentSample

abstract class AbstractInstrumentSample
extends org.apache.avalon.framework.logger.AbstractLogEnabled
implements InstrumentSample

An AbstractInstrumentSample contains all of the functionality common to all InstrumentSamples.

Author:
Avalon Development Team

Field Summary
private  boolean m_configured
          Configured flag.
private  java.lang.String m_description
          The description of the new InstrumentSample.
private  org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor m_descriptor
          The Descriptor for the InstrumentSample.
private  boolean m_expired
          True if the lease has expired.
private  int m_historyIndex
          The Index into the history arrays.
private  int[] m_historyNew
          The New half of the history array.
private  int[] m_historyOld
          The Old half of the history array.
private  InstrumentProxy m_instrumentProxy
          The InstrumentProxy which owns the InstrumentSample.
private  long m_interval
          The sample interval of the new InstrumentSample.
private  long m_leaseExpirationTime
          The time that the current lease expires.
private  org.apache.excalibur.instrument.manager.InstrumentSampleListener[] m_listeners
          Array of registered InstrumentSampleListeners.
private  long m_maxAge
          The maximum amount of time between updates before history will be wiped clean.
private  java.lang.String m_name
          The name of the new InstrumentSample.
private  int m_size
          The number of samples to store as history.
private  int m_stateVersion
          State Version.
protected  long m_time
          The UNIX time of the beginning of the sample.
private static long m_zoneOffset
          Stores the time-zone offset for this JVM.
 
Constructor Summary
protected AbstractInstrumentSample(InstrumentProxy instrumentProxy, java.lang.String name, long interval, int size, java.lang.String description, long lease)
          Creates a new AbstractInstrumentSample
 
Method Summary
 void addInstrumentSampleListener(org.apache.excalibur.instrument.manager.InstrumentSampleListener listener)
          Registers a InstrumentSampleListener with a InstrumentSample given a name.
protected abstract  void advanceToNextSample(boolean reset)
          The current sample has already been stored.
private  long calculateSampleTime(long time)
          Calculates the time of the sample which contains the specified time.
 void expire()
          Tells the sample that its lease has expired.
 long extendLease(long lease)
          Extends the lease to be lease milliseconds from the current time.
 java.lang.String getDescription()
          Returns the description of the sample.
 org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor getDescriptor()
          Returns a Descriptor for the InstrumentSample.
protected abstract  int getFillValue()
          Returns the value to use for filling in the buffer when time is skipped.
private  java.lang.String getHistoryList()
          Generates a comma separated list of history values.
private  int[] getHistorySnapshot()
          Gets a snapshot of the samples.
 InstrumentProxy getInstrumentProxy()
          Returns the InstrumentProxy which owns the InstrumentSample.
 long getInterval()
          Returns the sample interval.
 long getLeaseExpirationTime()
          Returns the time that the current lease expires.
 java.lang.String getName()
          Returns the name of the sample.
 int getSize()
          Returns the number of samples in the sample history.
 org.apache.excalibur.instrument.manager.InstrumentSampleSnapshot getSnapshot()
          Obtains a static snapshot of the InstrumentSample.
 int getStateVersion()
          Returns the stateVersion of the sample.
 long getTime()
          Obtain the UNIX time of the beginning of the sample.
 int getValue()
          Obtain the value of the sample.
protected abstract  int getValueInner()
          Gets the current value.
private  void init(int fillValue)
          Initializes the sample.
 boolean isConfigured()
          Returns true if the Instrument was configured in the instrumentables section of the configuration.
 void loadState(org.apache.avalon.framework.configuration.Configuration state)
          Loads the state into the InstrumentSample.
protected abstract  void loadState(int value, org.apache.avalon.framework.configuration.Configuration state)
          Used to load the state, called from AbstractInstrumentSample.loadState();
(package private)  void makePermanent()
          Called by the InstrumentProxy class during configuration to make the sample permanent.
 void removeInstrumentSampleListener(org.apache.excalibur.instrument.manager.InstrumentSampleListener listener)
          Unregisters a InstrumentSampleListener from a InstrumentSample given a name.
(package private)  void setConfigured()
          Sets the configured flag.
protected  void stateChanged()
          Called whenever the state of the sample is changed.
 java.lang.String toString()
          Returns a string representation of the sample.
protected  boolean update(long time, boolean reset)
          Brings the InstrumentSample's time up to date so that a new value can be added.
protected  void updateListeners(int value, long time)
          Notifies any listeners of a change.
 void writeState(java.io.PrintWriter out)
          Writes the current state to a PrintWriter as XML.
protected  void writeStateAttributes(java.io.PrintWriter out)
          Allow subclasses to add information into the saved state.
 
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, wait, wait, wait
 
Methods inherited from interface org.apache.excalibur.instrument.manager.impl.InstrumentSample
getInstrumentType, getType
 
Methods inherited from interface org.apache.avalon.framework.logger.LogEnabled
enableLogging
 

Field Detail

m_zoneOffset

private static long m_zoneOffset
Stores the time-zone offset for this JVM.


m_instrumentProxy

private InstrumentProxy m_instrumentProxy
The InstrumentProxy which owns the InstrumentSample.


m_configured

private boolean m_configured
Configured flag.


m_name

private java.lang.String m_name
The name of the new InstrumentSample.


m_interval

private long m_interval
The sample interval of the new InstrumentSample.


m_size

private int m_size
The number of samples to store as history.


m_description

private java.lang.String m_description
The description of the new InstrumentSample.


m_descriptor

private org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor m_descriptor
The Descriptor for the InstrumentSample.


m_maxAge

private long m_maxAge
The maximum amount of time between updates before history will be wiped clean.


m_time

protected long m_time
The UNIX time of the beginning of the sample.


m_leaseExpirationTime

private long m_leaseExpirationTime
The time that the current lease expires.


m_expired

private boolean m_expired
True if the lease has expired.


m_historyIndex

private int m_historyIndex
The Index into the history arrays.


m_historyOld

private int[] m_historyOld
The Old half of the history array.


m_historyNew

private int[] m_historyNew
The New half of the history array.


m_listeners

private org.apache.excalibur.instrument.manager.InstrumentSampleListener[] m_listeners
Array of registered InstrumentSampleListeners.


m_stateVersion

private int m_stateVersion
State Version.

Constructor Detail

AbstractInstrumentSample

protected AbstractInstrumentSample(InstrumentProxy instrumentProxy,
                                   java.lang.String name,
                                   long interval,
                                   int size,
                                   java.lang.String description,
                                   long lease)
Creates a new AbstractInstrumentSample

Parameters:
instrumentProxy - The InstrumentProxy which owns the InstrumentSample.
name - The name of the new InstrumentSample.
interval - The sample interval of the new InstrumentSample.
size - The number of samples to store as history. Assumes that size is at least 1.
description - The description of the new InstrumentSample.
lease - The length of the lease in milliseconds.
Method Detail

getInstrumentProxy

public InstrumentProxy getInstrumentProxy()
Returns the InstrumentProxy which owns the InstrumentSample.

Specified by:
getInstrumentProxy in interface InstrumentSample
Returns:
The InstrumentProxy which owns the InstrumentSample.

isConfigured

public boolean isConfigured()
Returns true if the Instrument was configured in the instrumentables section of the configuration.

Specified by:
isConfigured in interface InstrumentSample
Returns:
True if configured.

getName

public final java.lang.String getName()
Returns the name of the sample.

Specified by:
getName in interface InstrumentSample
Returns:
The name of the sample.

getInterval

public final long getInterval()
Returns the sample interval. The period of each sample in millisends.

Specified by:
getInterval in interface InstrumentSample
Returns:
The sample interval.

getSize

public final int getSize()
Returns the number of samples in the sample history.

Specified by:
getSize in interface InstrumentSample
Returns:
The size of the sample history.

getDescription

public final java.lang.String getDescription()
Returns the description of the sample.

Specified by:
getDescription in interface InstrumentSample
Returns:
The description of the sample.

getDescriptor

public org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor getDescriptor()
Returns a Descriptor for the InstrumentSample.

Specified by:
getDescriptor in interface InstrumentSample
Returns:
A Descriptor for the InstrumentSample.

getValue

public final int getValue()
Obtain the value of the sample. All samples are integers, so the profiled objects must measure quantity (numbers of items), rate (items/period), time in milliseconds, etc.

Specified by:
getValue in interface InstrumentSample
Returns:
The sample value.

getTime

public final long getTime()
Obtain the UNIX time of the beginning of the sample.

Specified by:
getTime in interface InstrumentSample
Returns:
The UNIX time of the beginning of the sample.

getLeaseExpirationTime

public long getLeaseExpirationTime()
Returns the time that the current lease expires. Permanent samples will return a value of 0.

Specified by:
getLeaseExpirationTime in interface InstrumentSample
Returns:
The time that the current lease expires.

extendLease

public long extendLease(long lease)
Extends the lease to be lease milliseconds from the current time. Ignored if the lease has already expired.

Specified by:
extendLease in interface InstrumentSample
Parameters:
lease - The length of the lease in milliseconds.
Returns:
The new lease expiration time. Returns 0 if the sample is permanent.

expire

public void expire()
Tells the sample that its lease has expired. No new references to the sample will be made available, but clients which already have access to the sample may continue to use it.

Specified by:
expire in interface InstrumentSample

getSnapshot

public final org.apache.excalibur.instrument.manager.InstrumentSampleSnapshot getSnapshot()
Obtains a static snapshot of the InstrumentSample.

Specified by:
getSnapshot in interface InstrumentSample
Returns:
A static snapshot of the InstrumentSample.

getStateVersion

public int getStateVersion()
Returns the stateVersion of the sample. The state version will be incremented each time any of the configuration of the sample 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 InstrumentSample
Returns:
The state version of the sample.

addInstrumentSampleListener

public void addInstrumentSampleListener(org.apache.excalibur.instrument.manager.InstrumentSampleListener listener)
Registers a InstrumentSampleListener with a InstrumentSample given a name.

Specified by:
addInstrumentSampleListener in interface InstrumentSample
Parameters:
listener - The listener which should start receiving updates from the InstrumentSample.

removeInstrumentSampleListener

public void removeInstrumentSampleListener(org.apache.excalibur.instrument.manager.InstrumentSampleListener listener)
Unregisters a InstrumentSampleListener from a InstrumentSample given a name.

Specified by:
removeInstrumentSampleListener in interface InstrumentSample
Parameters:
listener - The listener which should stop receiving updates from the InstrumentSample.

updateListeners

protected void updateListeners(int value,
                               long time)
Notifies any listeners of a change.

Make sure that this is called OUTSIDE of a synchrinization block.

Parameters:
value - The new value.
time - The time that the new value was set.

writeState

public void writeState(java.io.PrintWriter out)
Writes the current state to a PrintWriter as XML.

Specified by:
writeState in interface InstrumentSample
Parameters:
out - The PrintWriter to which the state should be written.

loadState

public final void loadState(org.apache.avalon.framework.configuration.Configuration state)
                     throws org.apache.avalon.framework.configuration.ConfigurationException
Loads the state into the InstrumentSample.

Specified by:
loadState in interface InstrumentSample
Parameters:
state - Configuration object to load state from.
Throws:
org.apache.avalon.framework.configuration.ConfigurationException - If there were any problems loading the state.

setConfigured

void setConfigured()
Sets the configured flag.


init

private void init(int fillValue)
Initializes the sample.

Parameters:
fillValue - The value to fill the buffer with.

writeStateAttributes

protected void writeStateAttributes(java.io.PrintWriter out)
Allow subclasses to add information into the saved state.

Parameters:
out - PrintWriter to write to.

loadState

protected abstract void loadState(int value,
                                  org.apache.avalon.framework.configuration.Configuration state)
                           throws org.apache.avalon.framework.configuration.ConfigurationException
Used to load the state, called from AbstractInstrumentSample.loadState();

Should only be called when synchronized.

Parameters:
value - Current value loaded from the state.
state - Configuration object to load state from.
Throws:
org.apache.avalon.framework.configuration.ConfigurationException - If there were any problems loading the state.

calculateSampleTime

private long calculateSampleTime(long time)
Calculates the time of the sample which contains the specified time.

Parameters:
time - Time whose sample time is requested.

getValueInner

protected abstract int getValueInner()
Gets the current value. Does not update.

Should only be called when synchronized.

Returns:
The current value.

advanceToNextSample

protected abstract void advanceToNextSample(boolean reset)
The current sample has already been stored. Reset the current sample and move on to the next.

Should only be called when synchronized.

Parameters:
reset - True if the next sample should be reset.

getFillValue

protected abstract int getFillValue()
Returns the value to use for filling in the buffer when time is skipped.

Should only be called when synchronized.


update

protected boolean update(long time,
                         boolean reset)
Brings the InstrumentSample's time up to date so that a new value can be added.

Should only be called when synchronized.

Parameters:
time - The time to which the InstrumentSample should be brought up to date.
reset - True if the next sample should be reset if an advance is necessary.
Returns:
True if listeners should be notified.

getHistorySnapshot

private int[] getHistorySnapshot()
Gets a snapshot of the samples.

Should only be called after an update when synchronized.

Returns:
A snapshot of the samples in the InstrumentSample.

getHistoryList

private java.lang.String getHistoryList()
Generates a comma separated list of history values.

Should only be called after an update when synchronized.

Returns:
The history values or null if they are all 0.

stateChanged

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


makePermanent

void makePermanent()
Called by the InstrumentProxy class during configuration to make the sample permanent.


toString

public java.lang.String toString()
Returns a string representation of the sample.

Overrides:
toString in class java.lang.Object
Returns:
A string representation of the sample.