1 /*
2 * Licensed under the Apache License, Version 2.0 (the "License");
3 * you may not use this file except in compliance with the License.
4 * You may obtain a copy of the License at
5 *
6 * http://www.apache.org/licenses/LICENSE-2.0
7 *
8 * Unless required by applicable law or agreed to in writing, software
9 * distributed under the License is distributed on an "AS IS" BASIS,
10 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 * See the License for the specific language governing permissions and
12 * limitations under the License.
13 */
14
15 package net.sourceforge.basher;
16
17 import java.util.List;
18
19 /**
20 * Defines the operations required for collecting statistical information about the running tasks.
21 *
22 * @author Johan Lindquist
23 * @version 1.0
24 */
25 public interface Collector
26 {
27 /**
28 * Signals to the collector that statistics collection should start.
29 */
30 public void startCollecting();
31
32 /**
33 * Signals to the collector that collection should stop.
34 */
35 public void stopCollecting();
36
37 /**
38 * Checks if the collector is currently collecting statistics.
39 *
40 * @return True if the collector is collecting data, otherwise false.
41 */
42 public boolean isCollecting();
43
44 /**
45 * Reports a task's successful invocation together with the time elapsed for the task to run.
46 *
47 * @param taskExecutionContext The task execution context wrapping the <code>Task</code> that was invoked
48 * @param elapsedTime The time it took for the task to run
49 * @param elapsedTimeNanos
50 */
51 public void success( TaskExecutionContext taskExecutionContext, final long elapsedTime, final long elapsedTimeNanos );
52
53 /**
54 * Reports a task's failure to run together with the time time elapsed for the failure. The (possible) cause of the
55 * failure is also provided.
56 *
57 * @param taskExecutionContext The task execution context wrapping the <code>Task</code> that failed
58 * @param elapsedTime The time it took for the task to run and fail.
59 * @param elapsedTimeNanos
60 * @param throwable The cause of the failure. This may be null if the cause of the failure is not an exception.
61 */
62 public void fail( TaskExecutionContext taskExecutionContext, final long elapsedTime, final long elapsedTimeNanos, Throwable throwable );
63
64 /**
65 * Retrieves the total number of failures recorded.
66 *
67 * @return The number of failures recorded.
68 */
69 public long getFailures();
70
71 /**
72 * Retrieves the total number of successes recorded.
73 *
74 * @return The number of successes recorded.
75 */
76 public long getSuccesses();
77
78 /**
79 * Retrieves the total number of tasks that were recorded (essentially successes+failures).
80 *
81 * @return The total number of tasks recorded.
82 */
83 public long getTotal();
84
85 /**
86 * Informs the collector that a collection period has finished.
87 */
88 public Average markAverage();
89
90 /**
91 * Retrieves the list of averages calculated over time.
92 *
93 * @return A list of <code>Average</code> instances.
94 */
95 public List<Average> getAverages();
96
97 /**
98 * Reports a task's wish to not run altogether with the time time elapsed for it to determine this.
99 *
100 * @param taskExecutionContext The task execution context wrapping the <code>Task</code> that didn't wish to run
101 * @param elapsedTime The time it took for the task to run and determine it didn't want to run
102 * @param elapsedTimeNanos
103 */
104 public void notRun( TaskExecutionContext taskExecutionContext, long elapsedTime, final long elapsedTimeNanos );
105
106 /**
107 * Retrieves the total number of tasks that didn't wish to run
108 *
109 * @return The total number of tasks not wishing to run.
110 */
111 public long getNotRun();
112 }