001: /*
002: * $Id: StopwatchStorage.java,v 1.1 2006/03/06 11:30:53 azzazzel Exp $
003: *
004: * Copyright 2006 Commsen International
005: *
006: * Licensed under the Common Public License, Version 1.0 (the "License");
007: * you may not use this file except in compliance with the License.
008: * You may obtain a copy of the License at
009: *
010: * http://www.opensource.org/licenses/cpl1.0.txt
011: *
012: * THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
013: * EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS
014: * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
015: *
016: */
017: package com.commsen.stopwatch;
018:
019: /**
020: * Interface describes the basic functionality a Stopwatch storage should support.
021: * A storage is a place where collected measurements are stored. By implementig
022: * this interface one can provide an "in-memory", "database", "file" or any other
023: * type of storage.
024: *
025: * All classes implementing this interface are considered Stopwatch engines.
026: * By default Stopwatch uses {@link com.commsen.stopwatch.storages.DefaultHSQLInMemoryStorage} to
027: * store data in "in-memory" HSQL database.
028: *
029: * Stopwatch can be configured to use another storage by :
030: * <ul>
031: * <li>setting <code>-Dcom.commsen.stopwatch.storage=<fully_qualified_class_name></code> JVM parameter</li>
032: * <li>creating "stopwatch.properties" file on classpath and seting <code>storage=<fully_qualified_class_name></code></li>
033: * </ul>
034: *
035: * <b>Warning:</b> the <code>storage</code> should be compatible with used <code>engine</code>.
036: * For example using {@link com.commsen.stopwatch.engines.MemoryStopwatchEngine}
037: * with {@link com.commsen.stopwatch.storages.DefaultHSQLInMemoryStorage} will work
038: * (because {@link com.commsen.stopwatch.engines.MemoryStopwatchEngine} extends
039: * {@link com.commsen.stopwatch.engines.DefaultStopwatchEngine}) but the reports
040: * will not contain memory usage information.
041: *
042: * @author Milen Dyankov
043: *
044: */
045: public interface StopwatchStorage {
046:
047: /**
048: * Called when engine is about to use the storage for the first time.
049: * Gives storage a chance to open connections, prepare statements, etc.
050: *
051: * @throws StopwatchStorageException if there is problem preparing the storage.
052: */
053: public void open() throws StopwatchStorageException;
054:
055: /**
056: * Called when engine is about to be paused or for some other reason will temporary not use this storage.
057: * Gives storage a chance to free resources.
058: *
059: * @throws StopwatchStorageException if there is a problem with freezing the storage.
060: */
061: public void freeze() throws StopwatchStorageException;
062:
063: /**
064: * Called when engine is about to be resumed. Simply indicates that is about to use this storage again.
065: * Gives storage a chance to re-connect, etc.
066: *
067: * @throws StopwatchStorageException if there is a problem with unfreezing the storage.
068: */
069: public void unfreeze() throws StopwatchStorageException;
070:
071: /**
072: * Called when engine is about to be stopped or for some other reason will no more use this storage.
073: * Gives storage a chance to clean up.
074: *
075: * @throws StopwatchStorageException if there is a problem closing the storage
076: */
077: public void close() throws StopwatchStorageException;
078:
079: /**
080: * Instructs the storage to create new record and store passed parameters.
081: * Engines should know what parameters storage expects.
082: *
083: * @param parameters
084: * @return the id of newly created record
085: * @throws StopwatchStorageException
086: */
087: public long newRecord(Object[] parameters)
088: throws StopwatchStorageException;
089:
090: /**
091: * Instructs the storage to remove the record identified by given parameters.
092: * Engines should know what parameters storage expects.
093: * Most storages will assume that parameters passed uniquely identify only one record.
094: *
095: * @param id of the database record to be removed
096: * @param parameters used to find the record
097: * @return <code>true</code> if record was removed successfuly, <code>false</code> otherwise
098: * @throws StopwatchStorageException on error
099: */
100: public boolean removeRecord(long id)
101: throws StopwatchStorageException;
102:
103: /**
104: * Instructs the storage to complete (at least remember the time) the record identified by given parameters.
105: * Engines should know what parameters storage expects.
106: * Most storages will assume that parameters passed uniquely identify only one record.
107: *
108: * @param id of the database record to be updated
109: * @param parameters used to find the record
110: * @return <code>true</code> if record was completed successfuly, <code>false</code> otherwise
111: * @throws StopwatchStorageException on error
112: */
113: public boolean completeRecord(long id, Object[] parameters)
114: throws StopwatchStorageException;
115:
116: /**
117: * Instructs the storage to create new complete record and store passed parameters.
118: * It is used in DELAYED mode. Start parameters are kept in memory until the end
119: * of given measurments and then passed here together with the end parameters.
120: * Engines should know what parameters storage expects.
121: *
122: * @param startParameters parameters describing start condition
123: * @param endParameters parameters describing end condition
124: * @return <code>true</code> if record was completed successfuly, <code>false</code> otherwise
125: * @throws StopwatchStorageException on error
126: */
127: public long newCompleteRecord(Object[] startParameters,
128: Object[] endParameters) throws StopwatchStorageException;
129:
130: /**
131: * Implementing methods should generate and return an array of reports.
132: * Array should contain exectly 1 element for each combination of <b>group</b> and <b>label</b>
133: *
134: * If there is no enough data to produce reports, method should return <code>null</code>
135: *
136: * @return array of reports.
137: */
138: public Report[] getReports();
139:
140: /**
141: * Implementing methods should generate and return an array of reports.
142: * Array should contain exectly 1 element for each <b>group</b> and all measurment should
143: * represent summary for all labels in that group.
144: *
145: * If there is no enough data to produce reports, method should return <code>null</code>
146: *
147: * @return array of reports.
148: */
149: public Report[] getAllByGroupReports();
150:
151: /**
152: * Implementing methods should generate and return an array of reports.
153: * Array should contain exectly 1 element for each <b>label</b> and all measurment should
154: * represent summary for all groups containing that label.
155: *
156: * If there is no enough data to produce reports, method should return <code>null</code>
157: *
158: * @return array of reports.
159: */
160: public Report[] getAllByLabelReports();
161:
162: /**
163: * Implementing methods should generate and return a single report for
164: * provided <b>group</b> and <b>label</b>
165: *
166: * If there is no enough data to produce the report, method should return <code>null</code>
167: *
168: * @param group the group for which report should be generated
169: * @param label the label for which report should be generated
170: * @return single report for provided <b>group</b> and <b>label</b>.
171: */
172: public Report getReport(String group, String label);
173:
174: /**
175: * Implementing methods should generate and return an array of reports.
176: * Array shoud contain exectly 1 element for each <b>group</b>
177: *
178: * If there is no enough data to produce the report, method should return <code>null</code>
179: *
180: * @param group the name of group for which report should be generated
181: * @return array of reports.
182: */
183: public Report[] getGroupReports(String group);
184:
185: /**
186: * Implementing methods should generate and return an array of reports.
187: * Array shoud contain exectly 1 element for each <b>label</b>
188: *
189: * If there is no enough data to produce the report, method should return <code>null</code>
190: *
191: * @param label the label for which report should be generated
192: * @return array of reports.
193: */
194: public Report[] getLabelReports(String label);
195:
196: /**
197: * Implementing methods should generate and return information of how many instances of the code
198: * specified by <code>group</code> and <code>label</code> ware running for the last <code>numberOfPeriods</code> periods.
199: * Period length is defined by <code>periodField</code> which can be one of {@link java.util.Calendar#FIELD_NAME}
200: *
201: * <p>
202: * For example to see how many instances of code labeled "l1" in group "g1" were running per minute
203: * for the last 30 minutes, one could use:
204: * <pre>
205: * long[] load = Stopwatch.getLoad("g1, "l1", {@link java.util.Calendar#MINUTE}, 30);
206: * </pre>
207: * which will forward the call to the appropriate storage implementation. In this case <code>load[0]</code> will contain the
208: * number of code instances running 30 minutes ago and <code>load[29]</code> number of code instances running in the last minute.
209: *
210: * <p>
211: * If <code>group</code> is <code>null</code> - summary load of all masurments labeled <code>label</code> should be returned.
212: * If <code>label</code> is <code>null</code> - summary load of all masurments in group <code>gtroup</code> should be returned.
213: * If both <code>group</code> and <code>label</code> are <code>null</code> - summary load of all masurments should be returned.
214: *
215: * @param group the group for which load report should be generated
216: * @param label the label for which load report should be generated
217: * @param periodField can be one of {@link java.util.Calendar#FIELD_NAME}
218: * @param numberOfPeriods number of periods
219: * @return array of length <code>numberOfPeriods</code> where every element represents the load for given pariod.
220: */
221: public long[] getLoad(String group, String label, int periodField,
222: int numberOfPeriods);
223:
224: /**
225: * Instructs the storage to disable/enable debug information.
226: * The reason for this exist is to be able to minimize the performance impact
227: * Stopwatch may have on the measured application. Generating debug info consumes additional
228: * CPU units, which may become a problem if Stopwatch is heavily used.
229: *
230: * Setting this to false (it is false by default) should cause no debug info being generated
231: * even when log4j's level is set to DEBUG.
232: *
233: * @param debugEnabled should debug information be generated
234: */
235: public void setDebugEnabled(boolean debugEnabled);
236:
237: }
|