001package org.javasimon.jmx;
002
003import org.javasimon.Sample;
004
005import java.io.Serializable;
006import java.util.List;
007
008/**
009 * Interface with common methods for JMX beans for a single Simon that corresponds
010 * to AbstractSimon in the core package.
011 *
012 * @author <a href="mailto:virgo47@gmail.com">Richard "Virgo" Richter</a>
013 */
014public interface SimonSuperMXBean extends Serializable {
015
016        /**
017         * Returns Simon name. While Simon names can be {@code null} for anonymous
018         * Simons, such Simons are never registered hence this method never returns
019         * {@code null}.
020         *
021         * @return name of the Simon
022         */
023        String getName();
024
025        /**
026         * Returns name of the parent Simon.
027         *
028         * @return name of the parent Simon
029         */
030        String getParentName();
031
032        /**
033         * Returns list of children names.
034         *
035         * @return list of children names
036         */
037        List<String> getChildrenNames();
038
039        /**
040         * Returns state of the Simon that can be ENABLED, DISABLED or INHERITED. State is returned
041         * as a String that matches values of the {@link org.javasimon.SimonState} enumeration.
042         *
043         * @return state of the Simon as a String
044         */
045        String getState();
046
047        /**
048         * Sets the state of the Simon. It must be specified whether to propagate the change
049         * and overrule states of all sub-simons which effectively sets the same state to the whole
050         * subtree. If subtree is not overruled, some Simons (with their subtrees) may not be affected
051         * by this change.
052         *
053         * @param state a new state as a valid String for {@link org.javasimon.SimonState#valueOf(String)}
054         * @param overrule specifies whether this change is forced to the whole subtree.
055         */
056        void setState(String state, boolean overrule);
057
058        /**
059         * Returns true, if the Simon is enabled or if the enabled state is inherited.
060         *
061         * @return true, if the Simon is effectively enabled
062         */
063        boolean isEnabled();
064
065        /**
066         * Returns note for the Simon. Note enables Simon with an additional information in human
067         * readable form.
068         *
069         * @return note for the Simon.
070         */
071        String getNote();
072
073        /**
074         * Sets note for the Simon. Note enables Simon with an additional information in human
075         * readable form.
076         *
077         * @param note note for the Simon.
078         */
079        void setNote(String note);
080
081        /**
082         * Returns ms timestamp of the first usage of this Simon. First and last usage
083         * are updated when monitor performs the measuring (start/stop/count/etc). They
084         * are not updated when values are obtained from the monitor.
085         *
086         * @return ms timestamp of the first usage
087         */
088        long getFirstUsage();
089
090        /**
091         * Returns nicely formatted timestamp of the first usage of this Simon.
092         *
093         * @return formatted date and time of the first usage
094         */
095        String getFirstUsageAsString();
096
097        /**
098         * Returns ms timestamp of the last usage of this Simon. First and last usage
099         * are updated when monitor performs the measuring (start/stop/count/etc). They
100         * are not updated when values are obtained from the monitor.
101         *
102         * @return ms timestamp of the last usage
103         */
104        long getLastUsage();
105
106        /**
107         * Returns nicely formatted timestamp of the last usage of this Simon.
108         *
109         * @return formatted date and time of the last usage
110         */
111        String getLastUsageAsString();
112
113        /**
114         * Samples Simon values and returns them in a Java Bean derived from Sample interface.
115         *
116         * @return sample containing all Simon values
117         */
118        Sample sample();
119
120        /**
121         * Samples increment in Simon values since the previous call of this method with the
122         * same key. When the method is called the first time for the key, current values
123         * are returned (same like from {@link #sample()}. Any subsequent calls with the key
124         * provide increments.
125         * <p>
126         * Clients should use a unique key (GUID, host name, etc.), to avoid interference
127         * with other clients.
128         *
129         * @param key key used to access incremental sample
130         * @return {@link org.javasimon.Sample} with value increments
131         */
132        Sample sampleIncrement(String key);
133
134        /**
135         * Returns Simon type used as a property in the {@link javax.management.ObjectName}.
136         *
137         * @return Simon type
138         */
139        String getType();
140
141        /**
142         * Stops incremental sampling for the key, removing any internal information for the key.
143         * Next call to {@link #sampleIncrement(String)} for the key will be considered the first
144         * call for the key.
145         *
146         * @param key key used to access incremental sample
147         * @return true if incremental information for the key existed, false otherwise
148         */
149        boolean stopIncrementalSampling(String key);
150}