com.commsen.stopwatch
Interface StopwatchStorage

All Known Implementing Classes:

AbstractDatabaseStorage, DefaultHSQLInMemoryStorage, DefaultHSQLStorage, MemoryHSQLInMemoryStorage, MemoryHSQLStorage

public interface StopwatchStorage

Interface describes the basic functionality a Stopwatch storage should support. A storage is a place where collected measurements are stored. By implementig this interface one can provide an "in-memory", "database", "file" or any other type of storage. All classes implementing this interface are considered Stopwatch engines. By default Stopwatch uses DefaultHSQLInMemoryStorage to store data in "in-memory" HSQL database. Stopwatch can be configured to use another storage by :

• setting -Dcom.commsen.stopwatch.storage=<fully_qualified_class_name> JVM parameter
• creating "stopwatch.properties" file on classpath and seting storage=<fully_qualified_class_name>

Warning: the storage should be compatible with used engine. For example using MemoryStopwatchEngine with DefaultHSQLInMemoryStorage will work (because MemoryStopwatchEngine extends DefaultStopwatchEngine) but the reports will not contain memory usage information.

Author:

Milen Dyankov

Method Summary

void	close() Called when engine is about to be stopped or for some other reason will no more use this storage.
boolean	completeRecord(long id, java.lang.Object[] parameters) Instructs the storage to complete (at least remember the time) the record identified by given parameters.
void	freeze() Called when engine is about to be paused or for some other reason will temporary not use this storage.
Report[]	getAllByGroupReports() Implementing methods should generate and return an array of reports.
Report[]	getAllByLabelReports() Implementing methods should generate and return an array of reports.
Report[]	getGroupReports(java.lang.String group) Implementing methods should generate and return an array of reports.
Report[]	getLabelReports(java.lang.String label) Implementing methods should generate and return an array of reports.
long[]	getLoad(java.lang.String group, java.lang.String label, int periodField, int numberOfPeriods) Implementing methods should generate and return information of how many instances of the code specified by group and label ware running for the last numberOfPeriods periods.
java.util.Properties	getProperties() Returns storage properties.
Report	getReport(java.lang.String group, java.lang.String label) Implementing methods should generate and return a single report for provided group and label If there is no enough data to produce the report, method should return null
Report[]	getReports() Implementing methods should generate and return an array of reports.
long	newCompleteRecord(java.lang.Object[] startParameters, java.lang.Object[] endParameters) Instructs the storage to create new complete record and store passed parameters.
long	newRecord(java.lang.Object[] parameters) Instructs the storage to create new record and store passed parameters.
void	open() Called when engine is about to use the storage for the first time.
boolean	removeRecord(long id) Instructs the storage to remove the record identified by given parameters.
void	setDebugEnabled(boolean debugEnabled) Instructs the storage to disable/enable debug information.
void	setProperties(java.util.Properties properties) Called by Stopwatch to set storage properties .
void	unfreeze() Called when engine is about to be resumed.

Method Detail

open

void open()
          throws StopwatchStorageException

Called when engine is about to use the storage for the first time. Gives storage a chance to open connections, prepare statements, etc.

Throws:

StopwatchStorageException - if there is problem preparing the storage.

freeze

void freeze()
            throws StopwatchStorageException

Called when engine is about to be paused or for some other reason will temporary not use this storage. Gives storage a chance to free resources.

Throws:

StopwatchStorageException - if there is a problem with freezing the storage.

unfreeze

void unfreeze()
              throws StopwatchStorageException

Called when engine is about to be resumed. Simply indicates that is about to use this storage again. Gives storage a chance to re-connect, etc.

Throws:

StopwatchStorageException - if there is a problem with unfreezing the storage.

close

void close()
           throws StopwatchStorageException

Called when engine is about to be stopped or for some other reason will no more use this storage. Gives storage a chance to clean up.

Throws:

StopwatchStorageException - if there is a problem closing the storage

newRecord

long newRecord(java.lang.Object[] parameters)
               throws StopwatchStorageException

Instructs the storage to create new record and store passed parameters. Engines should know what parameters storage expects.

Parameters:

parameters -

Returns:

the id of newly created record

Throws:

StopwatchStorageException

removeRecord

boolean removeRecord(long id)
                     throws StopwatchStorageException

Instructs the storage to remove the record identified by given parameters. Engines should know what parameters storage expects. Most storages will assume that parameters passed uniquely identify only one record.

Parameters:

id - of the database record to be removed

parameters - used to find the record

Returns:

true if record was removed successfuly, false otherwise

Throws:

StopwatchStorageException - on error

completeRecord

boolean completeRecord(long id,
                       java.lang.Object[] parameters)
                       throws StopwatchStorageException

Instructs the storage to complete (at least remember the time) the record identified by given parameters. Engines should know what parameters storage expects. Most storages will assume that parameters passed uniquely identify only one record.

Parameters:

id - of the database record to be updated

parameters - used to find the record

Returns:

true if record was completed successfuly, false otherwise

Throws:

StopwatchStorageException - on error

newCompleteRecord

long newCompleteRecord(java.lang.Object[] startParameters,
                       java.lang.Object[] endParameters)
                       throws StopwatchStorageException

Instructs the storage to create new complete record and store passed parameters. It is used in DELAYED mode. Start parameters are kept in memory until the end of given measurments and then passed here together with the end parameters. Engines should know what parameters storage expects.

Parameters:

startParameters - parameters describing start condition

endParameters - parameters describing end condition

Returns:

true if record was completed successfuly, false otherwise

Throws:

StopwatchStorageException - on error

getReports

Report[] getReports()

Implementing methods should generate and return an array of reports. Array should contain exectly 1 element for each combination of group and label If there is no enough data to produce reports, method should return null

Returns:

array of reports.

getAllByGroupReports

Report[] getAllByGroupReports()

Implementing methods should generate and return an array of reports. Array should contain exectly 1 element for each group and all measurment should represent summary for all labels in that group. If there is no enough data to produce reports, method should return null

Returns:

array of reports.

getAllByLabelReports

Report[] getAllByLabelReports()

Implementing methods should generate and return an array of reports. Array should contain exectly 1 element for each label and all measurment should represent summary for all groups containing that label. If there is no enough data to produce reports, method should return null

Returns:

array of reports.

getReport

Report getReport(java.lang.String group,
                 java.lang.String label)

Implementing methods should generate and return a single report for provided group and label If there is no enough data to produce the report, method should return null

Parameters:

group - the group for which report should be generated

label - the label for which report should be generated

Returns:

single report for provided group and label.

getGroupReports

Report[] getGroupReports(java.lang.String group)

Implementing methods should generate and return an array of reports. Array shoud contain exectly 1 element for each group If there is no enough data to produce the report, method should return null

Parameters:

group - the name of group for which report should be generated

Returns:

array of reports.

getLabelReports

Report[] getLabelReports(java.lang.String label)

Implementing methods should generate and return an array of reports. Array shoud contain exectly 1 element for each label If there is no enough data to produce the report, method should return null

Parameters:

label - the label for which report should be generated

Returns:

array of reports.

getLoad

long[] getLoad(java.lang.String group,
               java.lang.String label,
               int periodField,
               int numberOfPeriods)

Implementing methods should generate and return information of how many instances of the code specified by group and label ware running for the last numberOfPeriods periods. Period length is defined by periodField which can be one of Calendar.FIELD_NAME

For example to see how many instances of code labeled "l1" in group "g1" were running per minute for the last 30 minutes, one could use:

                long[] load = Stopwatch.getLoad("g1, "l1", Calendar.MINUTE, 30);
 

which will forward the call to the appropriate storage implementation. In this case load[0] will contain the number of code instances running 30 minutes ago and load[29] number of code instances running in the last minute.

If group is null - summary load of all masurments labeled label should be returned. If label is null - summary load of all masurments in group gtroup should be returned. If both group and label are null - summary load of all masurments should be returned.

Parameters:

group - the group for which load report should be generated

label - the label for which load report should be generated

periodField - can be one of Calendar.FIELD_NAME

numberOfPeriods - number of periods

Returns:

array of length numberOfPeriods where every element represents the load for given pariod.

setDebugEnabled

void setDebugEnabled(boolean debugEnabled)

Instructs the storage to disable/enable debug information. The reason for this exist is to be able to minimize the performance impact Stopwatch may have on the measured application. Generating debug info consumes additional CPU units, which may become a problem if Stopwatch is heavily used. Setting this to false (it is false by default) should cause no debug info being generated even when log4j's level is set to DEBUG.

Parameters:

debugEnabled - should debug information be generated

setProperties

void setProperties(java.util.Properties properties)

Called by Stopwatch to set storage properties .

Parameters:

properties - the properties

getProperties

java.util.Properties getProperties()

Returns storage properties.

Returns:

storage properties