com.sun.slamd.stat
Interface StatTracker

All Known Implementing Classes:

AccumulatingTracker, CategoricalTracker, FloatValueTracker, IncrementalTracker, IntegerValueTracker, LongValueTracker, PeriodicEventTracker, StackedValueTracker, TimeTracker

public interface StatTracker

This interface defines all the methods that must be implemented by a class intended to collect and manage statistical information during the course of job processing. Note that this class does not place any limitations on the kind of data that it manages or the way that it collects it. Rather, it simply defines a common set of methods that allows the SLAMD server to deal with it in a generic manner. Note that stat trackers are not threadsafe and therefore a stat tracker should only be used by a single thread. If you need to use multiple threads, then have a separate stat tracker per thread and use the aggregate method to combine the data from those trackers into a single tracker.

Method Summary

void	aggregate(StatTracker[] trackers) Aggregates the information collected by the provided set of stat trackers into a single tracker that represents the information gathered from the entire set of data.
java.awt.image.BufferedImage	createGraph(int width, int height) Creates a graph that visually depicts the information in this stat tracker using all the default settings.
java.awt.image.BufferedImage	createGraph(Job[] jobs, int width, int height, ParameterList parameters) Creates a graph that visually depicts the information in the provided set of stat trackers.
java.awt.image.BufferedImage	createGraph(Job job, int width, int height, ParameterList graphParameters) Creates a graph that visually depicts the information in the provided set of stat trackers.
java.awt.image.BufferedImage	createMonitorGraph(Job job, int width, int height, ParameterList parameters) Creates a graph that visually depicts the information collected by resource monitors associated with the provided job.
void	decode(byte[] encodedData) Decodes the provided data and uses it as the data for this stat tracker.
void	enableRealTimeStats(RealTimeStatReporter statReporter, java.lang.String jobID) Indicates that the stat tracker should enable real-time statistics collection.
byte[]	encode() Encodes the data collected by this tracker into a byte array that may be transferred over the network or written out to persistent storage.
java.lang.String	getAxisLabel() Retrieves the label that should be included along the vertical axis in a line graph for this stat tracker.
java.lang.String	getClientID() Retrieves the client ID of the client that used this stat tracker.
int	getCollectionInterval() Retrieves the collection interval (in seconds) that will be used for this stat tracker.
java.lang.String[][]	getDataForExport(boolean includeLabels) Retrieves the raw data associated with this stat tracker in a form that can be easily converted for export to CSV, tab-delimited text, or some other format for use in an external application.
java.lang.String	getDetailHTML() Retrieves a version of the verbose information for this stat tracker, formatted for display in an HTML document.
java.lang.String	getDetailString() Retrieves a detailed (potentially multi-line) string with verbose information about the data collected by this stat tracker.
java.lang.String	getDisplayName() Retrieves the user-friendly name associated with this stat tracker.
int	getDuration() Retrieves the total length of time in seconds that this stat tracker was capturing statistics.
double[]	getGraphData() Retrieves the data that represents the points in a line graph for this stat tracker.
ParameterList	getGraphParameterStubs(Job job) Retrieves the set of parameters that may be specified to customize the graph that is generated based on the statistical information in the stat trackers.
ParameterList	getGraphParameterStubs(Job[] jobs) Retrieves the set of parameters that may be specified to customize the graph that is generated based on the statistical information in the stat trackers.
ParameterList	getMonitorGraphParameterStubs(Job job) Retrieves the set of parameters that may be specified to customize the graph that is generated based on the resource monitor information in the stat trackers.
int	getNumIntervals() Retrieves the number of intervals for which data is available for this stat tracker.
java.lang.String[]	getSummaryData() Retrieves the summary string data for this stat tracker as separate values.
java.lang.String	getSummaryHTML() Retrieves a version of the summary information for this stat tracker formatted for display in an HTML document.
java.lang.String[]	getSummaryLabels() Retrieves a string array with the labels corresponding to the values returned from the getSummaryData method.
java.lang.String	getSummaryString() Retrieves brief one-line summary string with cumulative information about this stat tracker.
double	getSummaryValue() Retrieves the value associated with this stat tracker.
java.lang.String	getThreadID() Retrieves the thread ID of the client thread that used this stat tracker.
boolean	isAtLeast(double value) Indicates whether the value associated with this stat tracker is greater than or equal to the provided value.
boolean	isAtMost(double value) Indicates whether the value associated with this stat tracker is less than or equal to the provided value.
boolean	isSearchable() Indicates whether the user may search for jobs with statistics collected by this stat tracker.
StatTracker	newInstance() Creates a new instance of this stat tracker.
void	setClientID(java.lang.String clientID) Specifies the client ID of the client that used this stat tracker.
void	setCollectionInterval(int collectionInterval) Specifies the collection interval for this stat tracker.
void	setDisplayName(java.lang.String displayName) Specifies the display name for this stat tracker.
void	setDuration(int duration) Specifies the duration for this stat tracker.
void	setThreadID(java.lang.String threadID) Specifies the thread ID of the client thread that used this stat tracker.
void	startTracker() Indicates that the stat tracker is to start maintaining statistics and that it should start its internal timer.
void	stopTracker() Indicates that the stat tracker that there will not be any more statistics collection done and that it should stop its internal timer.

Method Detail

newInstance

public StatTracker newInstance()

Creates a new instance of this stat tracker. The new instance should have the same type, display name, client ID, thread ID, and collection interval as the stat tracker used to create it.

Returns:

The new instance of this stat tracker.

startTracker

public void startTracker()

Indicates that the stat tracker is to start maintaining statistics and that it should start its internal timer.

stopTracker

public void stopTracker()

Indicates that the stat tracker that there will not be any more statistics collection done and that it should stop its internal timer.

enableRealTimeStats

public void enableRealTimeStats(RealTimeStatReporter statReporter,
                                java.lang.String jobID)

Indicates that the stat tracker should enable real-time statistics collection. Note that some stat trackers may not support real-time statistics collection, in which case this method may be ignored.

Parameters:

statReporter - The stat-reporter that should be used to report real-time statistics to the SLAMD server.

jobID - The job ID of the job that will be reporting the data.

getClientID

public java.lang.String getClientID()

Retrieves the client ID of the client that used this stat tracker.

Returns:

The client ID of the client that used this stat tracker.

setClientID

public void setClientID(java.lang.String clientID)

Specifies the client ID of the client that used this stat tracker. Note that this should only be used when creating a new stat tracker based on encoded data and not when using it to collect statistics.

Parameters:

clientID - The client ID of the client that used this stat tracker.

getThreadID

public java.lang.String getThreadID()

Retrieves the thread ID of the client thread that used this stat tracker.

Returns:

The thread ID of the client thread that used this stat tracker.

setThreadID

public void setThreadID(java.lang.String threadID)

Specifies the thread ID of the client thread that used this stat tracker. Note that this should only be used when creating a new stat tracker based on encoded data and not when using it to collect statistics.

Parameters:

threadID - The thread ID of the client thread that used this stat tracker.

getDisplayName

public java.lang.String getDisplayName()

Retrieves the user-friendly name associated with this stat tracker.

Returns:

The user-friendly name associated with this stat tracker.

setDisplayName

public void setDisplayName(java.lang.String displayName)

Specifies the display name for this stat tracker. Note that this should only be used when creating a new stat tracker based on encoded data and not when using it to collect statistics.

Parameters:

displayName - The display name for this stat tracker.

getCollectionInterval

public int getCollectionInterval()

Retrieves the collection interval (in seconds) that will be used for this stat tracker.

Returns:

The collection interval (in seconds) that will be used for this stat tracker.

setCollectionInterval

public void setCollectionInterval(int collectionInterval)

Specifies the collection interval for this stat tracker. Note that this should only be used when creating a new stat tracker based on encoded data and not when using it to collect statistics.

Parameters:

collectionInterval - The collection interval in seconds to use for this stat tracker.

getDuration

public int getDuration()

Retrieves the total length of time in seconds that this stat tracker was capturing statistics.

Returns:

The total length of time in seconds that this stat tracker was capturing statistics.

setDuration

public void setDuration(int duration)

Specifies the duration for this stat tracker. Note that this should only be used when creating a new stat tracker based on encoded data and not when using it to collect statistics.

Parameters:

duration - The duration for this stat tracker.

isSearchable

public boolean isSearchable()

Indicates whether the user may search for jobs with statistics collected by this stat tracker. The search will be "greater than" and "less than" some user-specified value.

Returns:

true if statistics collected by this stat tracker should be searchable, or false if not.

isAtLeast

public boolean isAtLeast(double value)

Indicates whether the value associated with this stat tracker is greater than or equal to the provided value. This is only applicable if isSearchable returns true, and what exactly "the value of this stat tracker" means will be left up to those stat trackers that are searchable.

Parameters:

value - The value against which the value of this stat tracker is to be compared.

Returns:

true if the value of this stat tracker is greater than or equal to the provided value, or false if not.

isAtMost

public boolean isAtMost(double value)

Indicates whether the value associated with this stat tracker is less than or equal to the provided value. This is only applicable if isSearchable returns true, and what exactly "the value of this stat tracker" means will be left up to those stat trackers that are searchable.

Parameters:

value - The value against which the value of this stat tracker is to be compared.

Returns:

true if the value of this stat tracker is less than or equal to the provided value, or false if not.

getNumIntervals

public int getNumIntervals()

Retrieves the number of intervals for which data is available for this stat tracker.

Returns:

The number of intervals for which data is available for this stat tracker.

aggregate

public void aggregate(StatTracker[] trackers)

Aggregates the information collected by the provided set of stat trackers into a single tracker that represents the information gathered from the entire set of data. All of the stat trackers in the provided array must be of the same type as the instance into which the information will be aggregated.

Parameters:

trackers - The set of stat trackers whose data is to be aggregated.

getSummaryString

public java.lang.String getSummaryString()

Retrieves brief one-line summary string with cumulative information about this stat tracker.

Returns:

A brief one-line summary string containing cumulative information about this stat tracker.

getSummaryValue

public double getSummaryValue()

Retrieves the value associated with this stat tracker. This is only applicable if isSearchable returns true, and what exactly "the value associated with this stat tracker" means will be left up to those stat trackers that are searchable.

Returns:

The value associated with this stat tracker.

getDetailString

public java.lang.String getDetailString()

Retrieves a detailed (potentially multi-line) string with verbose information about the data collected by this stat tracker.

Returns:

A detailed string with verbose information about the data collected by this stat tracker.

getSummaryHTML

public java.lang.String getSummaryHTML()

Retrieves a version of the summary information for this stat tracker formatted for display in an HTML document.

Returns:

An HTML version of the summary data for this stat tracker.

getDetailHTML

public java.lang.String getDetailHTML()

Retrieves a version of the verbose information for this stat tracker, formatted for display in an HTML document.

Returns:

An HTML version of the verbose data for this stat tracker.

getSummaryLabels

public java.lang.String[] getSummaryLabels()

Retrieves a string array with the labels corresponding to the values returned from the getSummaryData method.

Returns:

A string array with the labels corresponding to the values returned from the getSummaryData method.

getSummaryData

public java.lang.String[] getSummaryData()

Retrieves the summary string data for this stat tracker as separate values.

Returns:

The summary string data for this stat tracker as separate values.

getDataForExport

public java.lang.String[][] getDataForExport(boolean includeLabels)

Retrieves the raw data associated with this stat tracker in a form that can be easily converted for export to CSV, tab-delimited text, or some other format for use in an external application. There should be one value per "cell".

Parameters:

includeLabels - Indicates whether the information being exported should contain labels.

Returns:

The raw data associated with this stat tracker in a form that can be exported to some external form.

encode

public byte[] encode()

Encodes the data collected by this tracker into a byte array that may be transferred over the network or written out to persistent storage.

Returns:

The data collected by this tracker encoded as a byte array.

decode

public void decode(byte[] encodedData)
            throws SLAMDException

Decodes the provided data and uses it as the data for this stat tracker.

Parameters:

encodedData - The encoded version of the data to use for this stat tracker.

Throws:

SLAMDException - If the provided data cannot be decoded and used with this stat tracker.

getGraphParameterStubs

public ParameterList getGraphParameterStubs(Job job)

Retrieves the set of parameters that may be specified to customize the graph that is generated based on the statistical information in the stat trackers.

Parameters:

job - The job containing the statistical information to be graphed.

Returns:

The set of parameters that may be used to customize the graph that is generated.

getMonitorGraphParameterStubs

public ParameterList getMonitorGraphParameterStubs(Job job)

Retrieves the set of parameters that may be specified to customize the graph that is generated based on the resource monitor information in the stat trackers.

Parameters:

job - The job containing the resource monitor information to be graphed.

Returns:

The set of parameters that may be used to customize the graph that is generated.

getGraphParameterStubs

public ParameterList getGraphParameterStubs(Job[] jobs)

Retrieves the set of parameters that may be specified to customize the graph that is generated based on the statistical information in the stat trackers.

Parameters:

jobs - The job containing the statistical information to be compared and graphed.

Returns:

The set of parameters that may be used to customize the graph that is generated.

getGraphData

public double[] getGraphData()

Retrieves the data that represents the points in a line graph for this stat tracker. This is only applicable if isSearchable returns true.

Returns:

The data that represents the points in a line graph for this stat tracker, or null if that data is not available.

getAxisLabel

public java.lang.String getAxisLabel()

Retrieves the label that should be included along the vertical axis in a line graph for this stat tracker. This is only applicable if isSearchable returns true.

Returns:

The lable that should be included along the vertical axis in a line graph for this stat tracker, or null if that data is not applicable.

createGraph

public java.awt.image.BufferedImage createGraph(Job job,
                                                int width,
                                                int height,
                                                ParameterList graphParameters)

Creates a graph that visually depicts the information in the provided set of stat trackers. The provided stat trackers must be the of the same type as this stat tracker.

Parameters:

job - The job containing the statistical information to be graphed.

width - The width in pixels of the graph to create.

height - The height in pixels of the graph to create.

graphParameters - The set of parameters that may be used to customize the graph that is generated.

Returns:

The graph created from the statistical information in the provided job.

createMonitorGraph

public java.awt.image.BufferedImage createMonitorGraph(Job job,
                                                       int width,
                                                       int height,
                                                       ParameterList parameters)

Creates a graph that visually depicts the information collected by resource monitors associated with the provided job.

Parameters:

job - The job containing the statistical information to be graphed.

width - The width in pixels of the graph to create.

height - The height in pixels of the graph to create.

parameters - The set of parameters that may be used to customize the graph that is generated.

Returns:

The graph created from the statistical information in the provided job.

createGraph

public java.awt.image.BufferedImage createGraph(Job[] jobs,
                                                int width,
                                                int height,
                                                ParameterList parameters)

Creates a graph that visually depicts the information in the provided set of stat trackers. The provided stat trackers must be the of the same type as this stat tracker.

Parameters:

jobs - The job containing the statistical information to be compared and graphed.

width - The width in pixels of the graph to create.

height - The height in pixels of the graph to create.

parameters - The set of parameters that may be used to customize the graph that is generated.

Returns:

The graph created from the statistical information in the provided job.

createGraph

public java.awt.image.BufferedImage createGraph(int width,
                                                int height)

Creates a graph that visually depicts the information in this stat tracker using all the default settings.

Parameters:

width - The width in pixels of the graph to create.

height - The height in pixels of the graph to create.

Returns:

The graph created from this stat tracker.