com.cisco.services.tracing
Class TraceMessageThread

java.lang.Object
  extended by java.lang.Thread
      extended by com.cisco.services.tracing.TraceMessageThread
All Implemented Interfaces:
java.lang.Runnable

public abstract class TraceMessageThread
extends java.lang.Thread


Nested Class Summary
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
static int DEFAULT_STATISTICS_REPORTING_INTERVAL
           
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
TraceMessageThread(java.lang.String name)
           
 
Method Summary
 boolean getBatchMessages()
           
 boolean getCatchExceptions()
           
 boolean getCollectStatistics()
           
 boolean getPeriodicWakeupEnabled()
           
 long getPeriodicWakeupInterval()
           
 int getStatisticsReportingInterval()
           
protected  boolean initialize()
          Invoked when the run method has just begun.
 boolean isRunning()
          Returns the state of the TraceMessageThread.
 void run()
          Subclasses of TraceMessageThread do not override the run method.
 void sendTraceMessage(java.lang.Object myTraceMessage)
           
 void setBatchMessages(boolean enabled)
          Enable or disable trace message batching, that is, the ability for the TraceMessageThread to extract and process vectors of trace messages rather than single trace message at a time.
 void setCatchExceptions(boolean enabled)
          Enable or disable exception handling when invoking the subclass's traceMessageReceived method.
 void setCollectStatistics(boolean enabled)
          Enable or disable statistics gathering.
 void setPeriodicWakeupEnabled(boolean enabled)
          Enable or disable periodic wakeups (for diagnostic purposes)
 void setPeriodicWakeupInterval(long interval)
          Enable or disable periodic wakeups (for diagnostic purposes)
 void setStatisticsReportingInterval(int interval)
          Set the statisticsReportingInterval, in iterations.
 void shutdown()
           
protected  void shutdownComplete()
          Invoked when the shutdown method has run to completion.
protected  void shutdownCompletePending()
          Invoked when the shutdown method has run, but thread may still be alive.
protected  void statisticsGathered(int maxQueueDepth)
          Invoked when the statistics gathering interval has expired.
 java.lang.String toString()
           
protected abstract  void traceMessageReceived(java.lang.Object traceMessage)
          Invoked every time the run method receives a trace message from its queue.
protected  void uninitialize()
          Invoked when the run method is about to exit, if and only if initialize succeeded.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, yield
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_STATISTICS_REPORTING_INTERVAL

public static final int DEFAULT_STATISTICS_REPORTING_INTERVAL
See Also:
Constant Field Values
Constructor Detail

TraceMessageThread

public TraceMessageThread(java.lang.String name)
Method Detail

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Thread

shutdown

public final void shutdown()

sendTraceMessage

public final void sendTraceMessage(java.lang.Object myTraceMessage)

setPeriodicWakeupEnabled

public final void setPeriodicWakeupEnabled(boolean enabled)
Enable or disable periodic wakeups (for diagnostic purposes)


getPeriodicWakeupEnabled

public final boolean getPeriodicWakeupEnabled()
Returns:
the periodicWakeups property

setPeriodicWakeupInterval

public final void setPeriodicWakeupInterval(long interval)
Enable or disable periodic wakeups (for diagnostic purposes)


getPeriodicWakeupInterval

public final long getPeriodicWakeupInterval()
Returns:
the periodicWakeups property

setBatchMessages

public final void setBatchMessages(boolean enabled)
Enable or disable trace message batching, that is, the ability for the TraceMessageThread to extract and process vectors of trace messages rather than single trace message at a time.


getBatchMessages

public final boolean getBatchMessages()
Returns:
the batchMessages property

setCatchExceptions

public final void setCatchExceptions(boolean enabled)
Enable or disable exception handling when invoking the subclass's traceMessageReceived method. Useful for some debugging scenarios.


getCatchExceptions

public final boolean getCatchExceptions()
Returns:
the catchExceptions property

setCollectStatistics

public final void setCollectStatistics(boolean enabled)
Enable or disable statistics gathering. Statistics are reported on a regular basis via the subclass's statisticsGathered method.


getCollectStatistics

public final boolean getCollectStatistics()
Returns:
the collectStatistics property

setStatisticsReportingInterval

public final void setStatisticsReportingInterval(int interval)
Set the statisticsReportingInterval, in iterations.


getStatisticsReportingInterval

public final int getStatisticsReportingInterval()
Returns:
the statisticsReportingInterval property

isRunning

public final boolean isRunning()
Returns the state of the TraceMessageThread.


run

public final void run()
Subclasses of TraceMessageThread do not override the run method. Instead, they should override the initialize, traceMessageReceived, and uninitialize methods.

Specified by:
run in interface java.lang.Runnable
Overrides:
run in class java.lang.Thread

initialize

protected boolean initialize()
Invoked when the run method has just begun. Subclass returns true to indicate that initialization succeeded and that it's okay for the run method to continue. If initialize returns false, the run method will not attempt to process any trace message and will instead exit immediately. This method will be invoked at most once.

Returns:
true if initialization succeeded, false if not

traceMessageReceived

protected abstract void traceMessageReceived(java.lang.Object traceMessage)
Invoked every time the run method receives a trace message from its queue.


uninitialize

protected void uninitialize()
Invoked when the run method is about to exit, if and only if initialize succeeded. This method will be invoked at most once.


shutdownComplete

protected void shutdownComplete()
Invoked when the shutdown method has run to completion. When the shutdownComplete method has been invoked, the TraceMessageThread is no longer alive. This method will be invoked at most once. Provided as a hook for subclasses to know when shutdown has fully completed.


shutdownCompletePending

protected void shutdownCompletePending()
Invoked when the shutdown method has run, but thread may still be alive. This is true whenever the shutdown method is invoked by the TraceMessageThread itself. This method will be invoked at most once. Provided as a hook for subclasses to know when shutdown has initiated as has completed as much as possible.


statisticsGathered

protected void statisticsGathered(int maxQueueDepth)
Invoked when the statistics gathering interval has expired.

Parameters:
maxQueueDepth - maximum number of trace messages in queue over the interval