1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package com.commsen.stopwatch;
18
19 import java.util.Properties;
20
21 /***
22 * Interface describes the basic functionality a Stopwatch storage should support.
23 * A storage is a place where collected measurements are stored. By implementig
24 * this interface one can provide an "in-memory", "database", "file" or any other
25 * type of storage.
26 *
27 * All classes implementing this interface are considered Stopwatch engines.
28 * By default Stopwatch uses {@link com.commsen.stopwatch.storages.DefaultHSQLInMemoryStorage} to
29 * store data in "in-memory" HSQL database.
30 *
31 * Stopwatch can be configured to use another storage by :
32 * <ul>
33 * <li>setting <code>-Dcom.commsen.stopwatch.storage=<fully_qualified_class_name></code> JVM parameter</li>
34 * <li>creating "stopwatch.properties" file on classpath and seting <code>storage=<fully_qualified_class_name></code></li>
35 * </ul>
36 *
37 * <b>Warning:</b> the <code>storage</code> should be compatible with used <code>engine</code>.
38 * For example using {@link com.commsen.stopwatch.engines.MemoryStopwatchEngine}
39 * with {@link com.commsen.stopwatch.storages.DefaultHSQLInMemoryStorage} will work
40 * (because {@link com.commsen.stopwatch.engines.MemoryStopwatchEngine} extends
41 * {@link com.commsen.stopwatch.engines.DefaultStopwatchEngine}) but the reports
42 * will not contain memory usage information.
43 *
44 * @author Milen Dyankov
45 *
46 */
47 public interface StopwatchStorage {
48
49 /***
50 * Called when engine is about to use the storage for the first time.
51 * Gives storage a chance to open connections, prepare statements, etc.
52 *
53 * @throws StopwatchStorageException if there is problem preparing the storage.
54 */
55 public void open () throws StopwatchStorageException;
56
57
58 /***
59 * Called when engine is about to be paused or for some other reason will temporary not use this storage.
60 * Gives storage a chance to free resources.
61 *
62 * @throws StopwatchStorageException if there is a problem with freezing the storage.
63 */
64 public void freeze () throws StopwatchStorageException;
65
66
67 /***
68 * Called when engine is about to be resumed. Simply indicates that is about to use this storage again.
69 * Gives storage a chance to re-connect, etc.
70 *
71 * @throws StopwatchStorageException if there is a problem with unfreezing the storage.
72 */
73 public void unfreeze () throws StopwatchStorageException;
74
75
76 /***
77 * Called when engine is about to be stopped or for some other reason will no more use this storage.
78 * Gives storage a chance to clean up.
79 *
80 * @throws StopwatchStorageException if there is a problem closing the storage
81 */
82 public void close () throws StopwatchStorageException;
83
84
85 /***
86 * Instructs the storage to create new record and store passed parameters.
87 * Engines should know what parameters storage expects.
88 *
89 * @param parameters
90 * @return the id of newly created record
91 * @throws StopwatchStorageException
92 */
93 public long newRecord (Object[] parameters) throws StopwatchStorageException;
94
95
96 /***
97 * Instructs the storage to remove the record identified by given parameters.
98 * Engines should know what parameters storage expects.
99 * Most storages will assume that parameters passed uniquely identify only one record.
100 *
101 * @param id of the database record to be removed
102 * @param parameters used to find the record
103 * @return <code>true</code> if record was removed successfuly, <code>false</code> otherwise
104 * @throws StopwatchStorageException on error
105 */
106 public boolean removeRecord (long id) throws StopwatchStorageException;
107
108
109 /***
110 * Instructs the storage to complete (at least remember the time) the record identified by given parameters.
111 * Engines should know what parameters storage expects.
112 * Most storages will assume that parameters passed uniquely identify only one record.
113 *
114 * @param id of the database record to be updated
115 * @param parameters used to find the record
116 * @return <code>true</code> if record was completed successfuly, <code>false</code> otherwise
117 * @throws StopwatchStorageException on error
118 */
119 public boolean completeRecord (long id, Object[] parameters) throws StopwatchStorageException;
120
121
122 /***
123 * Instructs the storage to create new complete record and store passed parameters.
124 * It is used in DELAYED mode. Start parameters are kept in memory until the end
125 * of given measurments and then passed here together with the end parameters.
126 * Engines should know what parameters storage expects.
127 *
128 * @param startParameters parameters describing start condition
129 * @param endParameters parameters describing end condition
130 * @return <code>true</code> if record was completed successfuly, <code>false</code> otherwise
131 * @throws StopwatchStorageException on error
132 */
133 public long newCompleteRecord (Object[] startParameters, Object[] endParameters) throws StopwatchStorageException;
134
135
136 /***
137 * Implementing methods should generate and return an array of reports.
138 * Array should contain exectly 1 element for each combination of <b>group</b> and <b>label</b>
139 *
140 * If there is no enough data to produce reports, method should return <code>null</code>
141 *
142 * @return array of reports.
143 */
144 public Report[] getReports ();
145
146
147 /***
148 * Implementing methods should generate and return an array of reports.
149 * Array should contain exectly 1 element for each <b>group</b> and all measurment should
150 * represent summary for all labels in that group.
151 *
152 * If there is no enough data to produce reports, method should return <code>null</code>
153 *
154 * @return array of reports.
155 */
156 public Report[] getAllByGroupReports ();
157
158
159 /***
160 * Implementing methods should generate and return an array of reports.
161 * Array should contain exectly 1 element for each <b>label</b> and all measurment should
162 * represent summary for all groups containing that label.
163 *
164 * If there is no enough data to produce reports, method should return <code>null</code>
165 *
166 * @return array of reports.
167 */
168 public Report[] getAllByLabelReports ();
169
170
171 /***
172 * Implementing methods should generate and return a single report for
173 * provided <b>group</b> and <b>label</b>
174 *
175 * If there is no enough data to produce the report, method should return <code>null</code>
176 *
177 * @param group the group for which report should be generated
178 * @param label the label for which report should be generated
179 * @return single report for provided <b>group</b> and <b>label</b>.
180 */
181 public Report getReport (String group, String label);
182
183
184 /***
185 * Implementing methods should generate and return an array of reports.
186 * Array shoud contain exectly 1 element for each <b>group</b>
187 *
188 * If there is no enough data to produce the report, method should return <code>null</code>
189 *
190 * @param group the name of group for which report should be generated
191 * @return array of reports.
192 */
193 public Report[] getGroupReports (String group);
194
195
196 /***
197 * Implementing methods should generate and return an array of reports.
198 * Array shoud contain exectly 1 element for each <b>label</b>
199 *
200 * If there is no enough data to produce the report, method should return <code>null</code>
201 *
202 * @param label the label for which report should be generated
203 * @return array of reports.
204 */
205 public Report[] getLabelReports (String label);
206
207 /***
208 * Implementing methods should generate and return information of how many instances of the code
209 * specified by <code>group</code> and <code>label</code> ware running for the last <code>numberOfPeriods</code> periods.
210 * Period length is defined by <code>periodField</code> which can be one of {@link java.util.Calendar#FIELD_NAME}
211 *
212 * <p>
213 * For example to see how many instances of code labeled "l1" in group "g1" were running per minute
214 * for the last 30 minutes, one could use:
215 * <pre>
216 * long[] load = Stopwatch.getLoad("g1, "l1", {@link java.util.Calendar#MINUTE}, 30);
217 * </pre>
218 * which will forward the call to the appropriate storage implementation. In this case <code>load[0]</code> will contain the
219 * number of code instances running 30 minutes ago and <code>load[29]</code> number of code instances running in the last minute.
220 *
221 * <p>
222 * If <code>group</code> is <code>null</code> - summary load of all masurments labeled <code>label</code> should be returned.
223 * If <code>label</code> is <code>null</code> - summary load of all masurments in group <code>gtroup</code> should be returned.
224 * If both <code>group</code> and <code>label</code> are <code>null</code> - summary load of all masurments should be returned.
225 *
226 * @param group the group for which load report should be generated
227 * @param label the label for which load report should be generated
228 * @param periodField can be one of {@link java.util.Calendar#FIELD_NAME}
229 * @param numberOfPeriods number of periods
230 * @return array of length <code>numberOfPeriods</code> where every element represents the load for given pariod.
231 */
232 public long[] getLoad (String group, String label, int periodField, int numberOfPeriods);
233
234
235 /***
236 * Instructs the storage to disable/enable debug information.
237 * The reason for this exist is to be able to minimize the performance impact
238 * Stopwatch may have on the measured application. Generating debug info consumes additional
239 * CPU units, which may become a problem if Stopwatch is heavily used.
240 *
241 * Setting this to false (it is false by default) should cause no debug info being generated
242 * even when log4j's level is set to DEBUG.
243 *
244 * @param debugEnabled should debug information be generated
245 */
246 public void setDebugEnabled(boolean debugEnabled);
247
248
249 /***
250 * Called by Stopwatch to set storage properties .
251 *
252 * @param properties the properties
253 */
254 public void setProperties (Properties properties);
255
256 /***
257 * Returns storage properties.
258 *
259 * @return storage properties
260 */
261 public Properties getProperties ();
262 }