/*
* $Id: StopwatchStorage.java,v 1.1 2006/03/06 11:30:53 azzazzel Exp $
*
* Copyright 2006 Commsen International
*
* Licensed under the Common Public License, Version 1.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.opensource.org/licenses/cpl1.0.txt
*
* THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
* EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS
* OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
*
*/
package com.commsen.stopwatch;
/**
* 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 {@link com.commsen.stopwatch.storages.DefaultHSQLInMemoryStorage} to
* store data in "in-memory" HSQL database.
*
* Stopwatch can be configured to use another storage by :
* <ul>
* <li>setting <code>-Dcom.commsen.stopwatch.storage=<fully_qualified_class_name></code> JVM parameter</li>
* <li>creating "stopwatch.properties" file on classpath and seting <code>storage=<fully_qualified_class_name></code></li>
* </ul>
*
* <b>Warning:</b> the <code>storage</code> should be compatible with used <code>engine</code>.
* For example using {@link com.commsen.stopwatch.engines.MemoryStopwatchEngine}
* with {@link com.commsen.stopwatch.storages.DefaultHSQLInMemoryStorage} will work
* (because {@link com.commsen.stopwatch.engines.MemoryStopwatchEngine} extends
* {@link com.commsen.stopwatch.engines.DefaultStopwatchEngine}) but the reports
* will not contain memory usage information.
*
* @author Milen Dyankov
*
*/
public interface StopwatchStorage {
/**
* 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.
*/
public void open () 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.
*/
public void freeze () 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.
*/
public void unfreeze () 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
*/
public void close () throws StopwatchStorageException;
/**
* Instructs the storage to create new record and store passed parameters.
* Engines should know what parameters storage expects.
*
* @param parameters
* @return the id of newly created record
* @throws StopwatchStorageException
*/
public long newRecord (Object[] parameters) 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.
*
* @param id of the database record to be removed
* @param parameters used to find the record
* @return <code>true</code> if record was removed successfuly, <code>false</code> otherwise
* @throws StopwatchStorageException on error
*/
public boolean removeRecord (long id) 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.
*
* @param id of the database record to be updated
* @param parameters used to find the record
* @return <code>true</code> if record was completed successfuly, <code>false</code> otherwise
* @throws StopwatchStorageException on error
*/
public boolean completeRecord (long id, Object[] parameters) 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.
*
* @param startParameters parameters describing start condition
* @param endParameters parameters describing end condition
* @return <code>true</code> if record was completed successfuly, <code>false</code> otherwise
* @throws StopwatchStorageException on error
*/
public long newCompleteRecord (Object[] startParameters, Object[] endParameters) throws StopwatchStorageException;
/**
* Implementing methods should generate and return an array of reports.
* Array should contain exectly 1 element for each combination of <b>group</b> and <b>label</b>
*
* If there is no enough data to produce reports, method should return <code>null</code>
*
* @return array of reports.
*/
public Report[] getReports ();
/**
* Implementing methods should generate and return an array of reports.
* Array should contain exectly 1 element for each <b>group</b> and all measurment should
* represent summary for all labels in that group.
*
* If there is no enough data to produce reports, method should return <code>null</code>
*
* @return array of reports.
*/
public Report[] getAllByGroupReports ();
/**
* Implementing methods should generate and return an array of reports.
* Array should contain exectly 1 element for each <b>label</b> and all measurment should
* represent summary for all groups containing that label.
*
* If there is no enough data to produce reports, method should return <code>null</code>
*
* @return array of reports.
*/
public Report[] getAllByLabelReports ();
/**
* Implementing methods should generate and return a single report for
* provided <b>group</b> and <b>label</b>
*
* If there is no enough data to produce the report, method should return <code>null</code>
*
* @param group the group for which report should be generated
* @param label the label for which report should be generated
* @return single report for provided <b>group</b> and <b>label</b>.
*/
public Report getReport (String group, String label);
/**
* Implementing methods should generate and return an array of reports.
* Array shoud contain exectly 1 element for each <b>group</b>
*
* If there is no enough data to produce the report, method should return <code>null</code>
*
* @param group the name of group for which report should be generated
* @return array of reports.
*/
public Report[] getGroupReports (String group);
/**
* Implementing methods should generate and return an array of reports.
* Array shoud contain exectly 1 element for each <b>label</b>
*
* If there is no enough data to produce the report, method should return <code>null</code>
*
* @param label the label for which report should be generated
* @return array of reports.
*/
public Report[] getLabelReports (String label);
/**
* Implementing methods should generate and return information of how many instances of the code
* specified by <code>group</code> and <code>label</code> ware running for the last <code>numberOfPeriods</code> periods.
* Period length is defined by <code>periodField</code> which can be one of {@link java.util.Calendar#FIELD_NAME}
*
* <p>
* 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:
* <pre>
* long[] load = Stopwatch.getLoad("g1, "l1", {@link java.util.Calendar#MINUTE}, 30);
* </pre>
* which will forward the call to the appropriate storage implementation. In this case <code>load[0]</code> will contain the
* number of code instances running 30 minutes ago and <code>load[29]</code> number of code instances running in the last minute.
*
* <p>
* If <code>group</code> is <code>null</code> - summary load of all masurments labeled <code>label</code> should be returned.
* If <code>label</code> is <code>null</code> - summary load of all masurments in group <code>gtroup</code> should be returned.
* If both <code>group</code> and <code>label</code> are <code>null</code> - summary load of all masurments should be returned.
*
* @param group the group for which load report should be generated
* @param label the label for which load report should be generated
* @param periodField can be one of {@link java.util.Calendar#FIELD_NAME}
* @param numberOfPeriods number of periods
* @return array of length <code>numberOfPeriods</code> where every element represents the load for given pariod.
*/
public long[] getLoad (String group, String label, int periodField, int numberOfPeriods);
/**
* 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.
*
* @param debugEnabled should debug information be generated
*/
public void setDebugEnabled(boolean debugEnabled);
}
|