1 package com.github.triceo.splitlog.api;
2
3 /**
4 * Implementors of this interface provide users with means of measuring various
5 * properties of {@link Message}s that pass through them.
6 *
7 * @param <P>
8 * Where this is getting its {@link Message}s from.
9 */
10 public interface MessageProducer<P extends MessageProducer<P>> {
11
12 /**
13 * Return the number of consumers that have been
14 * {@link #startConsuming(MessageListener)}'d and not
15 * {@link #stopConsuming(MessageConsumer)}'d.
16 *
17 * @return Always >= 0.
18 */
19 int countConsumers();
20
21 /**
22 * Return the number of metrics that have been
23 * {@link #startMeasuring(MessageMeasure, String)}'d and not
24 * {@link #stopMeasuring(String)}'d.
25 *
26 * @return Always >= 0.
27 */
28 int countMetrics();
29
30 /**
31 * Retrieve the metric for a particular ID.
32 *
33 * @param id
34 * The ID under which the metric has been requested in
35 * {@link #startMeasuring(MessageMeasure, String)}.
36 * @return Null if no such metric. Either not
37 * {@link #startMeasuring(MessageMeasure, String)}'d or already
38 * {@link #stopMeasuring(MessageMetric)}'d.
39 */
40 MessageMetric<? extends Number, P> getMetric(String id);
41
42 /**
43 * Retrieve the ID for a particular measure.
44 *
45 * @param measure
46 * The metric retrieved by
47 * {@link #startMeasuring(MessageMeasure, String)}.
48 * @return Null if no such metric. Either not
49 * {@link #startMeasuring(MessageMeasure, String)}'d or already
50 * {@link #stopMeasuring(MessageMetric)}'d.
51 */
52 String getMetricId(MessageMetric<? extends Number, P> measure);
53
54 /**
55 * Whether or not the particular message consumer is being notified of new
56 * messages.
57 *
58 * @param consumer
59 * Consumer in question.
60 * @return True if called between {@link #startConsuming(MessageListener)}
61 * and {@link #stopConsuming(MessageConsumer)}.
62 */
63 boolean isConsuming(MessageConsumer<P> consumer);
64
65 /**
66 * Whether or not particular {@link MessageMetric} is active.
67 *
68 * @param metric
69 * Metric in question.
70 * @return True after {@link #startMeasuring(MessageMeasure, String)} has
71 * been called and before {@link #stopMeasuring(MessageMetric)}.
72 */
73 boolean isMeasuring(MessageMetric<? extends Number, P> metric);
74
75 /**
76 * Whether or not particular {@link MessageMetric} is active.
77 *
78 * @param id
79 * ID of the metric in question.
80 * @return True after {@link #startMeasuring(MessageMeasure, String)} has
81 * been called and before {@link #stopMeasuring(String)}.
82 */
83 boolean isMeasuring(String id);
84
85 /**
86 * Register a listener to be notified of new messages in this producer.
87 *
88 * @param listener
89 * Listener in question.
90 * @return A newly produced consumer in case the listener is submitted for
91 * the first time, the original consumer instance in case the
92 * listener is submitted repeatedly.
93 * @throws IllegalArgumentException
94 * When <code>listener instanceof {@link MessageConsumer}</code>
95 * .
96 */
97 MessageConsumer<P> startConsuming(MessageListener<P> listener);
98
99 /**
100 * Request that a message property be tracked from now on.
101 *
102 * @param measure
103 * The class that measures the given property. It is highly
104 * recommended that a measure instance be exclusive to each
105 * metric.
106 * @param id
107 * Unique identifier by which to locate the metric later.
108 * @return The metric to query for the value of the given property.
109 * @throws IllegalArgumentException
110 * When a given ID has already been passed to
111 * {@link #startMeasuring(MessageMeasure, String)} and not to
112 * {@link #stopMeasuring(String)} or equivalents.
113 */
114 <T extends Number> MessageMetric<T, P> startMeasuring(MessageMeasure<T, P> measure, String id);
115
116 /**
117 * Tell a consumer to no longer listen to new messages in this producer.
118 *
119 * @param consumer
120 * Consumer in question.
121 * @return True, unless no longer {@link #isConsuming(MessageConsumer)}.
122 */
123 boolean stopConsuming(MessageConsumer<P> consumer);
124
125 /**
126 * Will stop the metric from being notified of new {@link Message}s. From
127 * this point on, the ID will become available for taking.
128 *
129 * @param metric
130 * The metric in question.
131 * @return True if stopped, false if unknown.
132 */
133 boolean stopMeasuring(MessageMetric<? extends Number, P> metric);
134
135 /**
136 * Will stop the metric from being notified of new {@link Message}s. From
137 * this point on, the ID will become available for taking.
138 *
139 * @param id
140 * ID of the metric in question.
141 * @return True if stopped, false if unknown.
142 */
143 boolean stopMeasuring(String id);
144
145 }