View Javadoc

1   /*
2    * $Id: StopwatchEngine.java,v 1.2 2006/03/06 11:30:53 azzazzel Exp $
3    *
4    * Copyright 2006 Commsen International
5    * 
6    * Licensed under the Common Public License, Version 1.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    * 
10   *      http://www.opensource.org/licenses/cpl1.0.txt
11   * 
12   * THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 
13   * EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS 
14   * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
15   *
16   */
17  package com.commsen.stopwatch;
18  
19  import java.util.Properties;
20  
21  /***
22   * Interface describes the basic functionality a Stopwatch engine should support. All classes
23   * implementing this interface are considered Stopwatch engines. Stopwatch can be configured to use
24   * given engine by :
25   * <ul>
26   * <li>setting <code>-Dcom.commsen.stopwatch.engine=&lt;fully_qualified_class_name&gt;</code> JVM
27   * parameter</li>
28   * <li>creating "stopwatch.properties" file on classpath and seting
29   * <code>engine=&lt;fully_qualified_class_name&gt;</code></li>
30   * </ul>
31   * 
32   * @author Milen Dyankov
33   * 
34   */
35  public interface StopwatchEngine {
36  
37  	/***
38  	 * Method called by Stopwatch when initilializing Stopwatch engine.
39  	 */
40  	public void start();
41  
42  
43  	/***
44  	 * Called when Stopwatch is disabled or for any other reason it will not use this engine for
45  	 * some time. This gives engine a chance to force-close all pending measurments, invalidate
46  	 * caches, close database connections, etc.
47  	 */
48  	public void pause();
49  
50  
51  	/***
52  	 * Called when Stopwatch is enabled and before attepting to use paused engine. This gives engine
53  	 * a chance to re-initialize caches, open database connections, etc.
54  	 */
55  	public void resume();
56  
57  
58  	/***
59  	 * Called when Stopwatch's engine is changed or for any other reason Stopwatch will no longer
60  	 * use this engine. This gives engine a chance to free all used resources.
61  	 */
62  	public void stop();
63  
64  
65  	/***
66  	 * Method called when mensuration is started.
67  	 * 
68  	 * @param group the name of the group this measurment should be placed in
69  	 * @param label how this measurment should be labeled
70  	 * @return Unique ID representing current measurment.
71  	 */
72  	public long begin(String group, String label);
73  
74  
75  	/***
76  	 * Method called when mensuration is stopped. It is possible to call this method multiple times
77  	 * with the same id, however the engine should process only the first call.
78  	 * 
79  	 * @param id Unique ID representing the actual measurment that need to be stopped.
80  	 */
81  	public void end(long id);
82  
83  
84  	/***
85  	 * Method called when mensuration with id <code>id</code> is to be skipped. It is possible to
86  	 * call this method multiple times with the same id, however the engine should process only the
87  	 * first call.
88  	 * 
89  	 * @param id Unique ID representing the actual measurment that need to be stopped.
90  	 */
91  	public void skip(long id);
92  
93  
94  	/***
95  	 * Method called to instruct engine to use user defined storage
96  	 * 
97  	 * @param storage the storage to be used by this engine
98  	 */
99  	public void setStorage(StopwatchStorage storage);
100 
101 
102 	/***
103 	 * Method called to instruct engine in what mode persistence manager should work in.
104 	 * 
105 	 * @param persistenceMode the mode persistence manager should work in.
106 	 * 
107 	 * @see com.commsen.stopwatch.storages.StorageManager#NORMAL_MODE
108 	 * @see com.commsen.stopwatch.storages.StorageManager#THREAD_MODE
109 	 * @see com.commsen.stopwatch.storages.StorageManager#DELAYED_MODE
110 	 * 
111 	 */
112 	public void setPersistenceMode(int persistenceMode);
113 
114 
115 	/***
116 	 * Method called to obtain the current storage class
117 	 * 
118 	 * @return the class name of the current storage
119 	 */
120 	public String getStorageClass();
121 
122 
123 	/***
124 	 * Allows clients to get reference to the stopwatch's storage. Storage is normaly used by
125 	 * clients to generate reports.
126 	 * 
127 	 * @return reference to the storage
128 	 * 
129 	 */
130 	public StopwatchStorage getStorage();
131 
132 
133 	/***
134 	 * Instructs engine to disable/enable debug information. The reason for this exist is to be able
135 	 * to minimize the performance impact Stopwatch may have on the measured application. Generating
136 	 * debug info consumes additional CPU units, which may become a problem if Stopwatch is heavily
137 	 * used.
138 	 * 
139 	 * Setting this to false (it is false by default) should cause no debug info being generated
140 	 * even when log4j's level is set to DEBUG.
141 	 * 
142 	 * @param debugEnabled should debug information be generated
143 	 */
144 	public void setDebugEnabled(boolean debugEnabled);
145 
146 
147 	/***
148 	 * Called by Stopwatch to set engine properties .
149 	 * 
150 	 * @param properties the properties
151 	 */
152 	public void setProperties(Properties properties);
153 
154 
155 	/***
156 	 * Returns engine properties.
157 	 * 
158 	 * @return engine properties
159 	 */
160 	public Properties getProperties();
161 
162 }