View Javadoc

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 }