1 package com.github.triceo.splitlog.api;
2
3 /**
4 * Allows users to track various statistics on classes implementing
5 * {@link MessageProducer}. These classes are intended for measuring only, and
6 * will therefore not store the {@link Message}s that have passed through them.
7 *
8 * @param <T>
9 * Type of the value that the metric is measuring.
10 * @param <S>
11 * Where this is getting its {@link Message}s from.
12 */
13 public interface MessageMetric<T extends Number, S extends MessageProducer<S>> extends MessageConsumer<S>,
14 SupportsExpectations<S, MessageMetricCondition<T, S>> {
15
16 /**
17 * Retrieves the measure that is used to produce the value of this metric.
18 *
19 * @return Never null.
20 */
21 MessageMeasure<T, S> getMeasure();
22
23 /**
24 * Retrieve the number of times that the metric has been invoked on a
25 * {@link Message}.
26 *
27 * @return Always 0 or more.
28 */
29 long getMessageCount();
30
31 /**
32 * Retrieve the number of times that the metric has been invoked on a
33 * {@link Message}, at the time immediately after a given message has been
34 * processed.
35 *
36 * @param timestamp
37 * The point in time after this message was processed.
38 * @return 0 when timestamp is null. -1 in case no such message was ever
39 * processed by this metric. The proper value otherwise.
40 */
41 long getMessageCount(Message timestamp);
42
43 /**
44 * Retrieve the instance that is responsible for notifying this metric of
45 * new {@link Message}s-
46 *
47 * @return Typically the instance that was used to retrieve this metric.
48 */
49 S getSource();
50
51 /**
52 * Retrieve the value of this metric, which is a sum of the return values of
53 * all of this metric's {@link MessageMeasure} invocations.
54 *
55 * @return Whatever, depends on the measure. Initial value, before any
56 * messages arrive, is null
57 */
58 T getValue();
59
60 /**
61 * Retrieve the value of this metric, which is a sum of the return values of
62 * all of this metric's {@link MessageMeasure} invocations, at the time
63 * immediately after a given message has been processed.
64 *
65 * @param timestamp
66 * The point in time after this message was processed. Null will
67 * retrieve the initial state.
68 * @return Whatever, depends on the measure. Initial state, before any
69 * messages arrive, is {@link MessageMeasure#initialValue()}. Null
70 * is returned in case no such message was ever processed by this
71 * metric.
72 */
73 T getValue(Message timestamp);
74
75 }