com.grandcentral.appstats
Interface Stat

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Subinterfaces:

Counter, Timer

All Known Implementing Classes:

StatImpl

public interface Stat

extends java.io.Serializable, java.lang.Cloneable

Copyright: Copyright (c) 2002

Company: Grand Central Communications

Version:

1.0

Author:

Taras Shkvarchuk, Adrian Dorsman

Field Summary

static int	AGGREGATE_AVG
static int	AGGREGATE_EXPAVG
static int	AGGREGATE_MAX
static int	AGGREGATE_MIN
static int	AGGREGATE_REPLACE
static int	AGGREGATE_SUM
static char	DELIM_STATNAME '^' == the delimiter to separate a stat name from the task hierarchy.
static char	DELIM_STATPREFIX '.' == the delimiter to separate the StatSource name from the statSuffix.
static char	DELIM_TASKPARENT '.' == the delimiter to separate parent and child tasknames -- tasknames must not contain this character
static int	DONT_AGGREGATE
static int	TYPE_DOUBLE indicates this Stat has a double value
static int	TYPE_HEIRARCH Indicates that this stat is a hierarchical view of child task’s stats.
static int	TYPE_HIDDEN a type to indicate that a Stat is hidden from view.
static int	TYPE_LONG indicates this Stat has a long value
static int	TYPE_OBJECT indicates this Stat has an Object value
static int	TYPE_UNDEFINED a Stat with no value

Method Summary

void	addAggregationMethod(int agMethod) add an aggregationMethod to this stat
void	addType(int type) add a type to this stat
java.lang.Object	clone()
boolean	containsAggregationMethod(int agMethod) returns true if this Stat is configured with param agMethod
boolean	containsType(int type) returns true if this Stat is configured with param type
void	fromStringAbbr(java.lang.String s) Allows for lightweight/partial deserialization from a readable format
int	getAggregationMethod() Returns the aggregation method for this stat.
double	getDouble()
java.lang.String	getFullName() A Stat's full name is composed of two distinct parts: a task hierarchy and a statName.
long	getLong()
java.lang.Object	getObject()
java.lang.String	getStatName() A statName can be further broken down into a prefix and a suffix, as:
java.lang.String	getStatPrefix()
java.lang.String	getStatSuffix()
java.lang.String	getTaskHierarchy() returns the task hierarchy from the full name of this stat
int	getType() Returns the type for this stat.
void	prependTaskName(java.lang.String taskname) prepends taskname + StatSource.DELIM_PARENT to the fullname of this stat
void	removeAggregationMethod(int agMethod) remove an aggregationMethod from this stat.
void	removeType(int type) remove a type from this stat.
void	setAggregationMethod(int agMethod) sets the aggregationMethod for this Stat.
void	setDouble(double aouble)
void	setFullName(java.lang.String name) sets the full name of this Stat.
void	setLong(long num)
void	setObject(java.lang.Object o)
void	setStatName(java.lang.String name) sets the stat name.
void	setStatPrefix(java.lang.String name) set the statName's prefix.
void	setStatSuffix(java.lang.String suffix)
void	setTaskHierarchy(java.lang.String name) sets the task hierarchy from the full name of this stat
void	setType(int type) sets the type for this stat.
java.lang.String	toStringAbbr() Allows for lightweight/partial serialization in a readable format
void	toStringAbbr(java.lang.StringBuffer s)

Field Detail

DELIM_STATNAME

public static final char DELIM_STATNAME

'^' == the delimiter to separate a stat name from the task hierarchy. stat names must not contain this character.

DELIM_STATPREFIX

public static final char DELIM_STATPREFIX

'.' == the delimiter to separate the StatSource name from the statSuffix. A statSuffix must not contain this character.

See Also:

getFullName(), getStatName(), getStatPrefix(), getStatSuffix()

DELIM_TASKPARENT

public static final char DELIM_TASKPARENT

'.' == the delimiter to separate parent and child tasknames -- tasknames must not contain this character

TYPE_UNDEFINED

public static final int TYPE_UNDEFINED

a Stat with no value

TYPE_LONG

public static final int TYPE_LONG

indicates this Stat has a long value

TYPE_DOUBLE

public static final int TYPE_DOUBLE

indicates this Stat has a double value

TYPE_OBJECT

public static final int TYPE_OBJECT

indicates this Stat has an Object value

TYPE_HIDDEN

public static final int TYPE_HIDDEN

a type to indicate that a Stat is hidden from view. Stats with this type are used by StatAggregators to store state information within a task.

TYPE_HEIRARCH

public static final int TYPE_HEIRARCH

Indicates that this stat is a hierarchical view of child task’s stats.

DONT_AGGREGATE

public static final int DONT_AGGREGATE

AGGREGATE_MIN

public static final int AGGREGATE_MIN

AGGREGATE_MAX

public static final int AGGREGATE_MAX

AGGREGATE_SUM

public static final int AGGREGATE_SUM

AGGREGATE_AVG

public static final int AGGREGATE_AVG

AGGREGATE_EXPAVG

public static final int AGGREGATE_EXPAVG

AGGREGATE_REPLACE

public static final int AGGREGATE_REPLACE

Method Detail

getFullName

public java.lang.String getFullName()

A Stat's full name is composed of two distinct parts: a task hierarchy and a statName. It is one of two forms:

task hierarchy + Stat.DELIM_STATNAME + statName

statName, or Stat.DELIM_STATNAME + statName

See Also:

getStatName(), Task.getName()

setFullName

public void setFullName(java.lang.String name)

sets the full name of this Stat.

Throws:

NullPointerException - if you try to set the name to a null value

See Also:

getFullName()

getStatName

public java.lang.String getStatName()

A statName can be further broken down into a prefix and a suffix, as:

prefix + Stat.DELIM_STATPREFIX + suffix

Examples:

httpTransactionLatency.min

httpTransactionLatency.max

httpTransactionLatency.avg

In the above, "httpTransactionLatency" is the prefix, and "min," "max," and "avg" are the suffixes.

Returns:

the StatSource name or "" if the statName does not contain a StatSource (i.e., it's missing a DELIM_STATPREFIX character)

See Also:

getFullName()

setStatName

public void setStatName(java.lang.String name)

sets the stat name.

Throws:

NullPointerException - if you try to set the name to a null value

java.lang.IllegalArgumentException - if the statName contains DELIM_STATNAME character

getStatPrefix

public java.lang.String getStatPrefix()

See Also:

getStatName()

setStatPrefix

public void setStatPrefix(java.lang.String name)

set the statName's prefix. This name cannot contain the DELIM_STATPREFIX character, nor the DELIM_STATNAME character.

Throws:

NullPointerException - if you try to set the name to a null value

java.lang.IllegalArgumentException - if the name is invalid

See Also:

getStatName()

getStatSuffix

public java.lang.String getStatSuffix()

Returns:

the statname's suffix or "" if one can't be found (i.e. the statName's missing a DELIM_STATPREFIX character)

See Also:

getStatName(), getStatPrefix()

setStatSuffix

public void setStatSuffix(java.lang.String suffix)

getTaskHierarchy

public java.lang.String getTaskHierarchy()

returns the task hierarchy from the full name of this stat

Returns:

"" if no task hierarchy can be found

See Also:

getFullName()

setTaskHierarchy

public void setTaskHierarchy(java.lang.String name)

sets the task hierarchy from the full name of this stat

Parameters:

name - contains the task hierarchy, or can be null to clear this Stat's taskHierarchy

See Also:

getFullName()

prependTaskName

public void prependTaskName(java.lang.String taskname)

prepends taskname + StatSource.DELIM_PARENT to the fullname of this stat

Throws:

java.lang.IllegalArgumentException - if taskname contains StatSource.DELIM_PARENT character

NullPointerException - if taskname is null

getType

public int getType()

Returns the type for this stat. A stat's type is implemented as a bitfield. Thus, a stat implemented with getType()==(TYPE_LONG|TYPE_STRING) will fail the test if(getType()==(TYPE_LONG)). For comparison, it is better to use the containsType() method.

Using multiple types in a stat allows for numerical comparison of string values, for instance, consider the case of a status Stat where you want the highest priority status of any task to filter down to the root task. You can set a numerical value along with a status String in each status Stat where numerically greater values correspond to more critical statae. Then call Stat.setAggregationMethod(AGGREGATE_MAX) and the status' stat will get filtered down in a task hierarchy so that if any child task has a high priority status the whole application will have that high priority status.

See Also:

see also the TYPE_{type} constants

setType

public void setType(int type)

sets the type for this stat. Doesn't clear any previously stored values associated with the old type

addType

public void addType(int type)

add a type to this stat

removeType

public void removeType(int type)

remove a type from this stat. Doesn't clear any previously stored values associated with the old type

containsType

public boolean containsType(int type)

returns true if this Stat is configured with param type

Returns:

getType()&type

getAggregationMethod

public int getAggregationMethod()

Returns the aggregation method for this stat. The aggregation method is implemented as a bitfield. Thus, a stat implemented with getAggregationMethod()==(AGGREGATE_MIN|AGGREGATE_MAX) will fail the test if(getAggregationMethod()==(AGGREGATE_MIN)). For comparison, it is better to use the containsAggregationMethod() method.

AggregationMethods are used by StatAggregators when a Task aggregates Stats from another Task. Using a bitfield allows for multiple calculations to occur when a Stat is aggregated. For instance, when a timer statistic is aggregated, the aggregator will calculate minimum, maximum, and an exponential average value and place it into the destination task, because all Timers by default have aggregation methods of (AGGREGATE_MIN|AGGREGATE_MAX|AGGREGATE_EXPAVG)

AppStat's standard aggregation methods are stored in this class as AGGREGATE_* public static final ints. These values map to logic inside of the StatAggregatorImpl class. If a user wants to implement their own custom aggregation methods, they may use their own values and their own StatAggregator implementation. The standard aggregation methods are meant to cover 80-90% of the use cases, and that's why they are hardcoded into this class.

Alternatively, a user may also provide a StatCalculator to calculate further statistics on aggregation. (@see Task#registerStatCalculator)

See Also:

see also the AGGREGATE_{method} constants

setAggregationMethod

public void setAggregationMethod(int agMethod)

sets the aggregationMethod for this Stat. Usually this is done immediately after the Stat is created. However, if you are modifying this after a Stat has been aggregated into a destination task, you should go an remove any Stats that the prior aggregation method might have created in the destination task (otherwise, they'll sit around forever)

addAggregationMethod

public void addAggregationMethod(int agMethod)

add an aggregationMethod to this stat

removeAggregationMethod

public void removeAggregationMethod(int agMethod)

remove an aggregationMethod from this stat. @see #setAggregationMethod for disclaimer

containsAggregationMethod

public boolean containsAggregationMethod(int agMethod)

returns true if this Stat is configured with param agMethod

Returns:

getAggregationMethod()&agMethod

setLong

public void setLong(long num)

getLong

public long getLong()

setDouble

public void setDouble(double aouble)

getDouble

public double getDouble()

setObject

public void setObject(java.lang.Object o)

getObject

public java.lang.Object getObject()

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

toStringAbbr

public java.lang.String toStringAbbr()

Allows for lightweight/partial serialization in a readable format

toStringAbbr

public void toStringAbbr(java.lang.StringBuffer s)

fromStringAbbr

public void fromStringAbbr(java.lang.String s)

Allows for lightweight/partial deserialization from a readable format