001package org.javasimon.jmx;
002
003import org.javasimon.StopwatchSample;
004
005import java.io.Serializable;
006import java.util.List;
007
008/**
009 * Interface of Simon management bean (MXBean) representing single point of access to a particular Simon
010 * {@link org.javasimon.Manager}.
011 * <p/>
012 * It provides general management tasks over all Simons for a single Manager (hierarchy of Simons)
013 * plus some useful util functions.
014 *
015 * @author Radovan Sninsky
016 * @since 2.0
017 */
018@SuppressWarnings("UnusedDeclaration")
019public interface SimonManagerMXBean extends Serializable {
020
021        /**
022         * Enables the Simon Manager, enable monitoring application by Simons.
023         *
024         * @see org.javasimon.Manager#enable()
025         */
026        void enable();
027
028        /**
029         * Disables the Simon Manager, disable monitoring application by Simons.
030         *
031         * @see org.javasimon.Manager#disable()
032         */
033        void disable();
034
035        /**
036         * Returns true if the Simon Manager is enabled, if monitoring is enabled.
037         *
038         * @return true if the Simon Manager is enabled
039         * @see org.javasimon.Manager#isEnabled()
040         */
041        boolean isEnabled();
042
043        /**
044         * Returns array containing full hierarchical names of all existing Simons.
045         *
046         * @return array of all Simon names
047         * @see org.javasimon.Manager#getSimonNames()
048         */
049        String[] getSimonNames();
050
051        /**
052         * Returns array containing full hierarchical names of all existing Simons in natural String order.
053         *
054         * @return array of all Simon names (ordered)
055         * @see org.javasimon.Manager#getSimonNames()
056         */
057        String[] getSimonNamesOrdered();
058
059        /**
060         * Returns type of Simon, either COUNTER, STOPWATCH or UNKNOWN.
061         *
062         * @param name name of Simon
063         * @return string COUNTER if Counter Simon, STOPWATCH if Stopwatch Simon
064         * or UNKNOWN if there is no Simon just undefined hierarchy node
065         */
066        String getType(String name);
067
068        /**
069         * Returns array containing names and types of all existing Simons ordered naturally by name.
070         *
071         * @return array of {@link SimonInfo} objects
072         */
073        SimonInfo[] getSimonInfos();
074
075        /**
076         * Clears the Manager (ignored if manager is disabled). All Simons are lost,
077         * but the configuration is preserved.
078         *
079         * @see org.javasimon.Manager#clear()
080         */
081        void clearManager();
082
083        /**
084         * Enables particular Simon only.
085         *
086         * @param name name of the Simon
087         * @see org.javasimon.Simon#setState(org.javasimon.SimonState, boolean)
088         */
089        void enableSimon(String name);
090
091        /**
092         * Disables particular Simon only.
093         *
094         * @param name name of the Simon
095         * @see org.javasimon.Simon#setState(org.javasimon.SimonState, boolean)
096         */
097        void disableSimon(String name);
098
099        /**
100         * Lets the Simon to inherit its enable/disable state from its parent.
101         *
102         * @param name name of the Simon
103         */
104        void inheritState(String name);
105
106        /**
107         * Retrieves sample data object for a particular Counter.
108         *
109         * @param name name of the Simon
110         * @return sample object or null if Simon with entered name doesn't exist
111         * @see org.javasimon.CounterSample
112         */
113        CounterSample getCounterSample(String name);
114
115        /**
116         * Retrieves sample data object for a particular Stopwatch.
117         *
118         * @param name name of the Simon
119         * @return sample object or null if Simon with entered name doesn't exist
120         * @see org.javasimon.StopwatchSample
121         */
122        StopwatchSample getStopwatchSample(String name);
123
124        /**
125         * Samples increment in Counter values since the previous call of this method with the
126         * same key. When the method is called the first time for the key, current values
127         * are returned (same like from {@link #getCounterSample(String)} }. Any subsequent calls with the key
128         * provide increments.
129         * <p/>
130         * Clients should use a unique key (GUID, host name, etc.), to avoid interference
131         * with other clients.
132         *
133         * @param name name of the stopwatch
134         * @param key name of an incremental sample
135         * @return sample collected for a specified key if it was created before
136         */
137        CounterSample getIncrementCounterSample(String name, String key);
138
139        /**
140         * Samples increment in Stopwatch values since the previous call of this method with the
141         * same key. When the method is called the first time for the key, current values
142         * are returned (same like from {@link #getCounterSample(String)} }. Any subsequent calls with the key
143         * provide increments.
144         * <p/>
145         * Clients should use a unique key (GUID, host name, etc.), to avoid interference
146         * with other clients.
147         *
148         * @param name name of the stopwatch
149         * @param key name of an incremental sample
150         * @return sample collected for a specified key if it was created before
151         */
152        org.javasimon.jmx.StopwatchSample getIncrementStopwatchSample(String name, String key);
153
154        /**
155         * Prints multi-line string containing Simon tree starting with the specified Simon to standard output.
156         *
157         * @see org.javasimon.utils.SimonUtils#simonTreeString(org.javasimon.Simon)
158         */
159        void printSimonTree();
160
161        /**
162         * Sample all Counters
163         *
164         * @return One Sample for each Counter
165         */
166        List<CounterSample> getCounterSamples();
167
168        /**
169         * Increment sample all Counters.
170         *
171         * @param key name of an incremental sample
172         * @return one Sample for each Counter
173         * @see #getIncrementCounterSample(String, String)
174         */
175        List<CounterSample> getIncrementCounterSamples(String key);
176
177        /**
178         * Sample all Counters whose name matches given pattern
179         *
180         * @param namePattern Name pattern, null means all Counters
181         * @return One Sample for each Counter
182         */
183        List<CounterSample> getCounterSamples(String namePattern);
184
185        /**
186         * Incremental sample for all Counters whose name matches given pattern.     *
187         *
188         * @param namePattern name pattern ({@link org.javasimon.SimonPattern}), {@code null} means all Counters
189         * @param key name of an incremental sample
190         * @return one Sample for each Counter whose name matches given pattern
191         * @see #getIncrementCounterSample(String, String)
192         */
193        List<CounterSample> getIncrementCounterSamples(String namePattern, String key);
194
195        /**
196         * Sample all Stopwatches whose name matches given pattern.
197         *
198         * @param namePattern name pattern ({@link org.javasimon.SimonPattern}), {@code null} means all Stopwatches
199         * @return one Sample for each Stopwatch
200         */
201        List<org.javasimon.jmx.StopwatchSample> getStopwatchSamples(String namePattern);
202
203        /**
204         * Increment sample all Stopwatches whose name matches given pattern.
205         *
206         * @param namePattern name pattern ({@link org.javasimon.SimonPattern}), {@code null} means all Stopwatches
207         * @param key name of an incremental sample
208         * @return one Sample for each Stopwatch whose name matches given pattern
209         * @see #getIncrementStopwatchSample(String, String)
210         */
211        List<org.javasimon.jmx.StopwatchSample> getIncrementStopwatchSamples(String namePattern, String key);
212
213        /**
214         * Sample all Stopwatches.
215         *
216         * @return one Sample for each Stopwatch
217         */
218        List<org.javasimon.jmx.StopwatchSample> getStopwatchSamples();
219
220        /**
221         * Increment sample all Stopwatches.
222         *
223         * @param key name of an incremental sample
224         * @return one Sample for each Stopwatch
225         * @see #getIncrementStopwatchSample(String, String)
226         */
227        List<org.javasimon.jmx.StopwatchSample> getIncrementStopwatchSamples(String key);
228}