com.grandcentral.appstats
Interface Task

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

TaskImpl

public interface Task

extends java.io.Serializable

Description: Process Status/Performance monitoring system

Copyright: Copyright (c) 2002

Company: Grand Central Communications

- stores a list of Stats that are related
- brings stats from other sources under one view using
UpdateTaraskListeners that get invoked before stats are analyzed and child tasks.

Version:

$Version: $

Author:

Taras Shkvarchuk, Adrian Dorsman

Field Summary

static int	DEFAULT_MAXERRORS
static java.lang.String	STAT_ERRORCOUNT
static java.lang.String	TASK_STATE_DEFAULT_NAME
static java.lang.String	TASK_TIMER_DEFAULT_NAME

Method Summary

void	addChild(Task newChild) Adds a child subtask to this process.
void	addError(java.lang.Throwable ex) Adds an error to the list.
void	aggregate(Task task) Prcesses data from the finished task, updating any internal counters.
void	clear() Clears all the data for this task.
void	clearErrors() deletes all errors from this Task
Stat	exists(java.lang.String statName) Returns Stat if stat by that name exists.
void	flush() Marks that this task's job is finished and allows parent to record this task's results.
java.util.List	getChildren() Returns all child tasks, or null if none are present.
Counter	getCounter(java.lang.String name) Returns named counter, if such counter does not exist, new one will be created
java.util.List	getErrors() Returns a list of Throwable errors registered with this Task.
int	getMaxErrorDepth()
java.lang.String	getName() Displayable name
Task	getParent() Returns parent object or null iof there is no parent
java.lang.String	getProperty(java.lang.String name)
Stat	getStat(java.lang.String statname) Returns existing stat by statName, or creates a new one.
Stat	getStat(java.lang.String statname, int dataType) convenience method to provide a stat with the specified type.
StatAggregator	getStatAggregator()
Stat	getStatByFullName(java.lang.String statFullName) locates a Stat in this Task or a child task based on its fullname
java.util.List	getStatNames() Returns all statNames currently maintained by this Task
java.util.List	getStatNames(int recurseTasks) This function returns stat names visible to this task.
java.util.List	getStats() Returns stats contained in this task.
java.util.List	getStats(java.util.Collection names, int depth) Stats returned are those matching full names specified in the Collection.
java.util.List	getStats(int depth) This function returns stats visible to this task. Note: If any stats belong to the children of this they are cloned.
Timer	getTimer(java.lang.String name) Returns a Timer for a given type of operation.
void	putCounter(Counter counter) Overwrites old counter with a new one.
void	putStat(Stat stat) stores a Stat in this stat.
void	putTimer(Timer timer)
void	registerFlushListener(FlushListener l)
void	registerStatCalculator(StatCalculator c, java.lang.String statName) StatCalculator is called upon Task flush/aggregation whenever a stat is encountered with the following statName.
void	registerUpdateTaskListener(UpdateTaskListener listener) Registers an updateTaskListener with this object
void	removeChild(Task oldChild) Removes a child task from the list of active children.
void	removeCounter(java.lang.String name)
void	removeFlushListener(FlushListener l)
void	removeStat(Stat stat)
void	removeStat(java.lang.String statName)
void	removeStatCalculator(java.lang.String statName)
boolean	removeStats(java.util.Collection c) Removes all Stats that are not present in the collection.
void	removeStatsThatStartWith(java.lang.String s) removes all stats whose statNames start with s.
void	removeTimer(java.lang.String name)
void	removeUpdateTaskListener(UpdateTaskListener listener)
void	setMaxErrorDepth(int maxErrors) Alter the maximum number of most recent errors to keep in this Task.
void	setName(java.lang.String name) Sets name of the task as it will be displayed in reports. This name will also be used during aggregation to indicate where stats came from. A taskname must not contain the Stat.DELIM_TASKPARENT character and must not be null.
void	setProperty(java.lang.String name, java.lang.String value) Sets a running property of the task, these properties usually will not be viewed after task completion.
void	setStatAggregator(StatAggregator sa)
void	update() Must be called by the viewer code, before accessing stats. Causes all UpdateTaskListeners to update any fields in the task.

Field Detail

TASK_TIMER_DEFAULT_NAME

public static final java.lang.String TASK_TIMER_DEFAULT_NAME

TASK_STATE_DEFAULT_NAME

public static final java.lang.String TASK_STATE_DEFAULT_NAME

DEFAULT_MAXERRORS

public static final int DEFAULT_MAXERRORS

STAT_ERRORCOUNT

public static final java.lang.String STAT_ERRORCOUNT

Method Detail

setName

public void setName(java.lang.String name)

Sets name of the task as it will be displayed in reports.
This name will also be used during aggregation to indicate where stats came from.
A taskname must not contain the Stat.DELIM_TASKPARENT character and must not be null.

Parameters:

name - new name

Throws:

java.lang.IllegalArgumentException - if given name is not allowed

getName

public java.lang.String getName()

Displayable name

Returns:

Name of the task

getTimer

public Timer getTimer(java.lang.String name)

Returns a Timer for a given type of operation. If no timer with the given name is registered, a new one will be created and returned.
One timer should be used only for ONE logical operation, it is allowed to stop and start the same Timer if operation if logicaly the same.

Parameters:

name - operation name

putTimer

public void putTimer(Timer timer)

removeTimer

public void removeTimer(java.lang.String name)

putCounter

public void putCounter(Counter counter)

Overwrites old counter with a new one.
Use with caution since something may still be updating the old counter.

Parameters:

counter -

removeCounter

public void removeCounter(java.lang.String name)

getCounter

public Counter getCounter(java.lang.String name)

Returns named counter, if such counter does not exist, new one will be created

Parameters:

name - of the desired counter

Returns:

Counter type object

setProperty

public void setProperty(java.lang.String name,
                        java.lang.String value)

Sets a running property of the task, these properties usually will not be viewed after task completion.
Example use would be to reflect task configuration on the monitor. For numeric values that are to be recorded use of Counter is prefered.

Parameters:

name -

value -

getProperty

public java.lang.String getProperty(java.lang.String name)

putStat

public void putStat(Stat stat)

stores a Stat in this stat. Overrides any previously stored stat w/ same statName.

getStat

public Stat getStat(java.lang.String statname)

Returns existing stat by statName, or creates a new one.

Parameters:

name -

Returns:

Stat, never null

getStat

public Stat getStat(java.lang.String statname,
                    int dataType)

convenience method to provide a stat with the specified type. Will override any existing stat's type if it is different than the type passed into this method. Basic implementation:

Stat s = getStat(statname); s.setType(dataType); return s;

removeStat

public void removeStat(Stat stat)

removeStat

public void removeStat(java.lang.String statName)

removeStatsThatStartWith

public void removeStatsThatStartWith(java.lang.String s)

removes all stats whose statNames start with s. Anybody got a better naming convention?

clear

public void clear()

Clears all the data for this task. Does not remove children. Calculator's states are also cleared.

removeStats

public boolean removeStats(java.util.Collection c)

Removes all Stats that are not present in the collection.

Parameters:

c - a Collection of Stat objects that are to be retained, or a Collection of Strings that are full names of stats to be retained.

Returns:

true if this Task changed as a result of the call

getStats

public java.util.List getStats()

Returns stats contained in this task.

Returns:

List with the stats visible to this Task, or null.

getStats

public java.util.List getStats(int depth)

This function returns stats visible to this task.
Note: If any stats belong to the children of this they are cloned.

Parameters:

depth - number of levels to get stats of. [-1, 0, 1, 2, 3...) (-1)-full depth, (0)-just this task, (1)-immediate children, etc. Warning: Maximum depth may be limited to abs(Integer.MIN_VALUE)
Note: If you are a viewer you may want to call update before this call.

Returns:

new List with all requested stats, or null.

See Also:

update(), getStats()

getStats

public java.util.List getStats(java.util.Collection names,
                               int depth)

Stats returned are those matching full names specified in the Collection. Behaves like getStats(int) for the depth traversal.

Parameters:

names - a Collection of Strings that are full names of wanted stats.

depth - number of levels to get stats of. [-1, 0, 1, 2, 3...)

Returns:

a new List with matching stats, or null.

See Also:

getStats(int)

getStatByFullName

public Stat getStatByFullName(java.lang.String statFullName)

locates a Stat in this Task or a child task based on its fullname

Returns:

a Stat if one found or null if none found

See Also:

update(), Stat.getFullName()

getStatNames

public java.util.List getStatNames()

Returns all statNames currently maintained by this Task

Returns:

new List of full stat names as String

See Also:

update()

getStatNames

public java.util.List getStatNames(int recurseTasks)

This function returns stat names visible to this task.

Parameters:

depth - number of levels to get stats of. [-1, 0, 1, 2, 3...) (-1)-full depth, (0)-just this task, (1)-immediate children, etc.
Warning: Maximum depth may be limited to abs(Integer.MIN_VALUE)

Returns:

List with all requested stat names.

See Also:

update(), getStatNames()

exists

public Stat exists(java.lang.String statName)

Returns Stat if stat by that name exists. Otherwise null.

Parameters:

statName -

Returns:

Stat or null

addError

public void addError(java.lang.Throwable ex)

Adds an error to the list. Newly added error will appear 1st in the list. If maxErrorDepth is reached, last error will be removed from the list.

Parameters:

ex -

See Also:

setMaxErrorDepth()

getErrors

public java.util.List getErrors()

Returns a list of Throwable errors registered with this Task. The first error on the list will be the most recent; the last error will be the oldest.

Returns:

java.util.List

clearErrors

public void clearErrors()

deletes all errors from this Task

setMaxErrorDepth

public void setMaxErrorDepth(int maxErrors)

Alter the maximum number of most recent errors to keep in this Task. Default is 10. Set to -1 to keep all errors until explicitely cleared.

getMaxErrorDepth

public int getMaxErrorDepth()

flush

public void flush()
           throws DatatypeMismatchException

Marks that this task's job is finished and allows parent to record this task's results.
After data is recorded, all properties, counters, timers, etc are cleared. After this call task is ready to record new data.

Throws:

DatatypeMismatchException -

aggregate

public void aggregate(Task task)

Prcesses data from the finished task, updating any internal counters. Triggers internal StatAggregator @see StatAggregator

registerUpdateTaskListener

public void registerUpdateTaskListener(UpdateTaskListener listener)

Registers an updateTaskListener with this object

References to UpdateTaskListeners are not serialized along with the Task since they may or may not be serializable themselves.

Parameters:

newChild -

handler -

removeUpdateTaskListener

public void removeUpdateTaskListener(UpdateTaskListener listener)

update

public void update()
            throws DatatypeMismatchException

Must be called by the viewer code, before accessing stats.
Causes all UpdateTaskListeners to update any fields in the task.

Throws:

DatatypeMismatchException -

See Also:

UpdateTaskListener

registerFlushListener

public void registerFlushListener(FlushListener l)

removeFlushListener

public void removeFlushListener(FlushListener l)

getStatAggregator

public StatAggregator getStatAggregator()

setStatAggregator

public void setStatAggregator(StatAggregator sa)

registerStatCalculator

public void registerStatCalculator(StatCalculator c,
                                   java.lang.String statName)

StatCalculator is called upon Task flush/aggregation whenever a stat is encountered with the following statName. Future implementations might want to use a regex for pattern matching, though that seems overkill at this point.

Throws:

java.lang.IllegalArgumentException - if c instanceof FlushListener or UpdateTaskListener

removeStatCalculator

public void removeStatCalculator(java.lang.String statName)

getParent

public Task getParent()

Returns parent object or null iof there is no parent

Returns:

Process

addChild

public void addChild(Task newChild)

Adds a child subtask to this process.

removeChild

public void removeChild(Task oldChild)

Removes a child task from the list of active children.

getChildren

public java.util.List getChildren()

Returns all child tasks, or null if none are present.

Returns:

List of Task objects