001: /*
002: * $Id: StopwatchEngine.java,v 1.2 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 engine should support.
021: * All classes implementing this interface are considered Stopwatch engines.
022: * Stopwatch can be configured to use given engine by :
023: * <ul>
024: * <li>setting <code>-Dcom.commsen.stopwatch.engine=<fully_qualified_class_name></code> JVM parameter</li>
025: * <li>creating "stopwatch.properties" file on classpath and seting <code>engine=<fully_qualified_class_name></code></li>
026: * </ul>
027: *
028: * @author Milen Dyankov
029: *
030: */
031: public interface StopwatchEngine {
032:
033: /**
034: * Method called by Stopwatch when initilializing Stopwatch engine.
035: */
036: public void start();
037:
038: /**
039: * Called when Stopwatch is disabled or for any other reason it will not use this engine for some time.
040: * This gives engine a chance to force-close all pending measurments, invalidate caches,
041: * close database connections, etc.
042: */
043: public void pause();
044:
045: /**
046: * Called when Stopwatch is enabled and before attepting to use paused engine.
047: * This gives engine a chance to re-initialize caches, open database connections, etc.
048: */
049: public void resume();
050:
051: /**
052: * Called when Stopwatch's engine is changed or for any other reason Stopwatch will no longer use this engine.
053: * This gives engine a chance to free all used resources.
054: */
055: public void stop();
056:
057: /**
058: * Method called when mensuration is started.
059: *
060: * @param group the name of the group this measurment should be placed in
061: * @param label how this measurment should be labeled
062: * @return Unique ID representing current measurment.
063: */
064: public long begin(String group, String label);
065:
066: /**
067: * Method called when mensuration is stopped.
068: * It is possible to call this method multiple times with the same id, however the engine should
069: * process only the first call.
070: *
071: * @param id Unique ID representing the actual measurment that need to be stopped.
072: */
073: public void end(long id);
074:
075: /**
076: * Method called when mensuration with id <code>id</code> is to be skipped.
077: * It is possible to call this method multiple times with the same id, however the engine should
078: * process only the first call.
079: *
080: * @param id Unique ID representing the actual measurment that need to be stopped.
081: */
082: public void skip(long id);
083:
084: /**
085: * Method called to instruct engine to use user defined storage
086: * @param storage the storage to be used by this engine
087: */
088: public void setStorage(StopwatchStorage storage);
089:
090: /**
091: * Method called to instruct engine in what mode persistence manager should work in.
092: * @param persistenceMode the mode persistence manager should work in.
093: *
094: * @see com.commsen.stopwatch.storages.StorageManager#NORMAL_MODE
095: * @see com.commsen.stopwatch.storages.StorageManager#THREAD_MODE
096: * @see com.commsen.stopwatch.storages.StorageManager#DELAYED_MODE
097: *
098: */
099: public void setPersistenceMode(int persistenceMode);
100:
101: /**
102: * Method called to obtain the current storage class
103: * @return the class name of the current storage
104: */
105: public String getStorageClass();
106:
107: /**
108: * Allows clients to get reference to the stopwatch's storage.
109: * Storage is normaly used by clients to generate reports.
110: *
111: * @return reference to the storage
112: *
113: */
114: public StopwatchStorage getStorage();
115:
116: /**
117: * Instructs engine to disable/enable debug information.
118: * The reason for this exist is to be able to minimize the performance impact
119: * Stopwatch may have on the measured application. Generating debug info consumes additional
120: * CPU units, which may become a problem if Stopwatch is heavily used.
121: *
122: * Setting this to false (it is false by default) should cause no debug info being generated
123: * even when log4j's level is set to DEBUG.
124: *
125: * @param debugEnabled should debug information be generated
126: */
127: public void setDebugEnabled(boolean debugEnabled);
128:
129: }
|