1 /*
2 ~ Copyright 2006-2007 Nicolas De Loof.
3 ~
4 ~ Licensed under the Apache License, Version 2.0 (the "License");
5 ~ you may not use this file except in compliance with the License.
6 ~ You may obtain a copy of the License at
7 ~
8 ~ http://www.apache.org/licenses/LICENSE-2.0
9 ~
10 ~ Unless required by applicable law or agreed to in writing, software
11 ~ distributed under the License is distributed on an "AS IS" BASIS,
12 ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 ~ See the License for the specific language governing permissions and
14 ~ limitations under the License.
15 */
16 package org.jmonit;
17
18 import java.util.Set;
19
20 import org.jmonit.events.MonitoringEvent;
21
22 /**
23 * A <b>Monitor</b> is used by an instrumented application to publish it's
24 * state to jMonit internals. The application can publish numeric datas using
25 * the <code>add(double)</code> method.
26 * <p>
27 * As an interface, Monitor allow limited intrusion of jMonit API into the
28 * application code. You can mock it using the
29 * {@link org.jmonit.monitors.NullMonitor} for testing purpose, or any custom
30 * implementation.
31 *
32 * @author <a href="mailto:nicolas.deloof@gmail.com">Nicolas De Loof</a>
33 */
34 public interface Monitor
35 {
36 /**
37 * @return the name of this monitor
38 */
39 String getName();
40
41 /**
42 * Convenience method to add a primitive numeric data to the monitor.
43 *
44 * @param value to be monitored
45 * @see #fireEvent(MonitoringEvent)
46 */
47 void add( long value );
48
49 /**
50 * To acces internal optional features or plugable extensions, application
51 * asks the monitor for the extension plublic API class. The returned object
52 * implements the requested class.
53 * <p>
54 * The monitor is expected to "do its best" to return the expected feature,
55 * including register new features on-demand. To check for a feature to be
56 * supported, use {@link #isFeatureSupported}.
57 *
58 * @return null if the monitor doesn't support the requested API
59 */
60 <T> T getFeature( Class<T> feature );
61
62 /**
63 * @return all features supported by this monitor
64 */
65 Set<Class> getFeatures();
66
67 /**
68 * @return true if the feature is supported by the monitor
69 */
70 boolean isFeatureSupported( Class clazz );
71
72 /**
73 * @param features a set of requiered features
74 * @return true if the feature are supported by the monitor
75 */
76 boolean hasFeatures( Class[] features );
77
78 /**
79 * Reset the monitor
80 */
81 void clear();
82
83 /**
84 * Tag the monitor
85 *
86 * @param tag the tag
87 * @return the tagged monitor
88 */
89 Monitor tag( String tag );
90
91 /**
92 * @return the monitor tags
93 */
94 Set<String> getTags();
95
96 /**
97 * @param tag tag to test
98 * @return true if the monitor is tagged
99 */
100 boolean isTagged( String tag );
101
102 /**
103 * Dispatches the given <code>MonitoringEvent</code> to all registred
104 * listeners.
105 *
106 * @param event
107 */
108 void fireMonitoringEvent( MonitoringEvent event );
109 }