com.sun.slamd.stat
Class CategoricalTracker

java.lang.Object
  com.sun.slamd.stat.CategoricalTracker

All Implemented Interfaces:

StatTracker

public class CategoricalTracker
extends java.lang.Object
implements StatTracker

This class defines a stat tracker that can be used to count the number of times a given event occurs, as well as divide those occurrences into separate categories.

Author:

Neil A. Wilson

Field Summary

static int

MAX_SUMMARY_TABLE_WIDTH The maximum number of cells that will be allowed in a row of the table displayed as part of the HTML summary for this tracker.

Constructor Summary

CategoricalTracker()
Creates a new categorical tracker intended for use as a placeholder for decoding purposes.

CategoricalTracker(java.lang.String clientID, java.lang.String threadID, java.lang.String displayName, int collectionInterval)
Creates a new categorical tracker with the specified information.

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	createBarGraph(StatGrapher grapher, CategoricalTracker tracker) Generates a bar graph representation of the information in this categorical tracker.
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 parameters) 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[]	getCategoryNames() Retrieves the category names associated with 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.
int[][]	getIntervalCounts() Retrieves the set of interval counts by category for this stat tracker.
int[]	getIntervalCounts(java.lang.String categoryName) Retrieves the set of interval counts for the specified category.
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.
int	getTotalCount() Retrieves the total number of times that the tracked event occurred over the total duration.
int	getTotalCount(java.lang.String categoryName) Retrieves the total number of times that the tracked event occurred for the specified category over the total duration.
int[]	getTotalCounts() Retrieves the total number of times that the tracked event occurred for each category over the total duration.
boolean	hasBeenStarted() Indicates whether this stat tracker has been started, regardless of whether it is currently running.
void	increment(java.lang.String category) Increments the count for the specified category.
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	isRunning() Indicates whether this stat tracker is currently running.
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	setIntervalCounts(java.lang.String[] categoryNames, int[][] intervalCounts) Specifies the number of occurrences of the tracked event for each interval, separated by category names.
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.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_SUMMARY_TABLE_WIDTH

public static final int MAX_SUMMARY_TABLE_WIDTH

The maximum number of cells that will be allowed in a row of the table displayed as part of the HTML summary for this tracker.

See Also:

Constant Field Values

Constructor Detail

CategoricalTracker

public CategoricalTracker()

Creates a new categorical tracker intended for use as a placeholder for decoding purposes. This version of the constructor should not be used by job classes.

CategoricalTracker

public CategoricalTracker(java.lang.String clientID,
                          java.lang.String threadID,
                          java.lang.String displayName,
                          int collectionInterval)

Creates a new categorical tracker with the specified information.

Parameters:

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

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

displayName - The display name to use for this stat tracker.

collectionInterval - The collection interval in seconds that should be used for this stat tracker.

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.

Specified by:

newInstance in interface StatTracker

Returns:

The new instance of this stat tracker.

increment

public void increment(java.lang.String category)

Increments the count for the specified category.

Parameters:

category - The category in which to increment the count.

startTracker

public void startTracker()

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

Specified by:

startTracker in interface StatTracker

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.

Specified by:

stopTracker in interface StatTracker

hasBeenStarted

public boolean hasBeenStarted()

Indicates whether this stat tracker has been started, regardless of whether it is currently running.

Specified by:

hasBeenStarted in interface StatTracker

Returns:

true if this stat tracker has been started, or false if it has not yet been started.

isRunning

public boolean isRunning()

Indicates whether this stat tracker is currently running.

Specified by:

isRunning in interface StatTracker

Returns:

true if this stat tracker is currently running, or false if not.

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.

Specified by:

enableRealTimeStats in interface StatTracker

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.

getTotalCount

public int getTotalCount()

Retrieves the total number of times that the tracked event occurred over the total duration.

Returns:

The total number of times that the tracked event occurred over the total duration.

getTotalCount

public int getTotalCount(java.lang.String categoryName)

Retrieves the total number of times that the tracked event occurred for the specified category over the total duration.

Parameters:

categoryName - The name of the category for which to determine the total.

Returns:

The total number of times that the tracked event occurred for the specified category over the total duration.

getTotalCounts

public int[] getTotalCounts()

Retrieves the total number of times that the tracked event occurred for each category over the total duration. The order of the elements in the returned array will correspond to the order of the elements returned from the getCategoryNames() method.

Returns:

The total number of times that the tracked event occurred for each category over the total duration.

getCategoryNames

public java.lang.String[] getCategoryNames()

Retrieves the category names associated with this stat tracker.

Returns:

The category names associated with this stat tracker.

getIntervalCounts

public int[][] getIntervalCounts()

Retrieves the set of interval counts by category for this stat tracker. Note that each element of the array will itself be an array of the counts, with the elements in the same order as the category names.

Returns:

The set of interval counts by category for this stat tracker.

getIntervalCounts

public int[] getIntervalCounts(java.lang.String categoryName)

Retrieves the set of interval counts for the specified category.

Parameters:

categoryName - The name of the category for which to retrieve the interval counts.

Returns:

The interval counts for the specified category, or an empty array if the specified category is not defined for this tracker.

setIntervalCounts

public void setIntervalCounts(java.lang.String[] categoryNames,
                              int[][] intervalCounts)

Specifies the number of occurrences of the tracked event for each interval, separated by category names.

Parameters:

categoryNames - The names of the categories corresponding to the values in the interval counts.

intervalCounts - The number of occurrences of the tracked event by category by interval.

getClientID

public java.lang.String getClientID()

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

Specified by:

getClientID in interface StatTracker

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.

Specified by:

setClientID in interface StatTracker

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.

Specified by:

getThreadID in interface StatTracker

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.

Specified by:

setThreadID in interface StatTracker

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.

Specified by:

getDisplayName in interface StatTracker

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.

Specified by:

setDisplayName in interface StatTracker

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.

Specified by:

getCollectionInterval in interface StatTracker

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.

Specified by:

setCollectionInterval in interface StatTracker

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.

Specified by:

getDuration in interface StatTracker

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.

Specified by:

setDuration in interface StatTracker

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.

Specified by:

isSearchable in interface StatTracker

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.

Specified by:

isAtLeast in interface StatTracker

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.

Specified by:

isAtMost in interface StatTracker

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.

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.

Specified by:

getSummaryValue in interface StatTracker

Returns:

The value associated with this stat tracker.

getNumIntervals

public int getNumIntervals()

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

Specified by:

getNumIntervals in interface StatTracker

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.

Specified by:

aggregate in interface StatTracker

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.

Specified by:

getSummaryString in interface StatTracker

Returns:

A brief one-line summary string containing cumulative information about 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.

Specified by:

getDetailString in interface StatTracker

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.

Specified by:

getSummaryHTML in interface StatTracker

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.

Specified by:

getDetailHTML in interface StatTracker

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.

Specified by:

getSummaryLabels in interface StatTracker

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.

Specified by:

getSummaryData in interface StatTracker

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

Specified by:

getDataForExport in interface StatTracker

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.

Specified by:

encode in interface StatTracker

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.

Specified by:

decode in interface StatTracker

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.

Specified by:

getGraphParameterStubs in interface StatTracker

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.

Specified by:

getMonitorGraphParameterStubs in interface StatTracker

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.

Specified by:

getGraphParameterStubs in interface StatTracker

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.

createGraph

public java.awt.image.BufferedImage createGraph(Job job,
                                                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 of the same type as this stat tracker.

Specified by:

createGraph in interface StatTracker

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.

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.

Specified by:

createMonitorGraph in interface StatTracker

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.

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.

Specified by:

getGraphData in interface StatTracker

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.

Specified by:

getAxisLabel in interface StatTracker

Returns:

The label 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[] 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.

Specified by:

createGraph in interface StatTracker

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.

createBarGraph

public java.awt.image.BufferedImage createBarGraph(StatGrapher grapher,
                                                   CategoricalTracker tracker)

Generates a bar graph representation of the information in this categorical tracker.

Parameters:

grapher - The stat grapher that will be used to generate the graph.

tracker - The categorical tracker containing the data to be graphed.

Returns:

The bar graph generated from the provided stat tracker.

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.

Specified by:

createGraph in interface StatTracker

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.