001package org.javasimon;
002
003import java.util.List;
004
005/**
006 * Simon interface contains common functions related to Simon management - enable/disable and hierarchy.
007 * It does not contain any real action method - these are in specific interfaces that describes
008 * purpose of the particular type of monitor.
009 *
010 * @author <a href="mailto:virgo47@gmail.com">Richard "Virgo" Richter</a>
011 * @see Manager
012 * @see Counter for Simon counting some events
013 * @see Stopwatch for Simon measuring time spans
014 */
015public interface Simon extends HasAttributes {
016
017        /**
018         * Returns Simon name. Simon name is always fully qualified
019         * and determines also position of the Simon in the monitor hierarchy.
020         * Simon name can be {@code null} for anonymous Simons.
021         *
022         * @return name of the Simon
023         */
024        String getName();
025
026        /**
027         * Returns parent Simon.
028         *
029         * @return parent Simon
030         */
031        Simon getParent();
032
033        /**
034         * Returns list of children - direct sub-simons.
035         *
036         * @return list of children
037         */
038        List<Simon> getChildren();
039
040        /**
041         * Returns Simon's {@link Manager}.
042         *
043         * @return Simon's {@link Manager}
044         * @since 3.5
045         */
046        Manager getManager();
047
048        /**
049         * Returns state of the Simon that can be enabled, disabled or inherited.
050         *
051         * @return state of the Simon
052         */
053        SimonState getState();
054
055        /**
056         * Sets the state of the Simon. It must be specified whether to propagate the change
057         * and overrule states of all sub-simons which effectively sets the same state to the whole
058         * subtree. If subtree is not overruled, some Simons (with their subtrees) may not be affected
059         * by this change.
060         *
061         * @param state a new state.
062         * @param overrule specifies whether this change is forced to the whole subtree.
063         * @throws IllegalArgumentException if {@code state} is {@code null}.
064         */
065        void setState(SimonState state, boolean overrule);
066
067        /**
068         * Returns true, if the Simon is enabled or if the enabled state is inherited.
069         *
070         * @return true, if the Simon is effectively enabled
071         */
072        boolean isEnabled();
073
074        /**
075         * Returns note for the Simon. Note enables Simon with an additional information in human
076         * readable form.
077         *
078         * @return note for the Simon.
079         */
080        String getNote();
081
082        /**
083         * Sets note for the Simon. Note enables Simon with an additional information in human
084         * readable form.
085         *
086         * @param note note for the Simon.
087         */
088        void setNote(String note);
089
090        /**
091         * Returns ms timestamp of the first usage of this Simon. First and last usage
092         * are updated when monitor performs the measuring (start/stop/count/etc). They
093         * are not updated when values are obtained from the monitor.
094         *
095         * @return ms timestamp of the first usage
096         */
097        long getFirstUsage();
098
099        /**
100         * Returns ms timestamp of the last usage of this Simon. First and last usage
101         * are updated when monitor performs the measuring (start/stop/count/etc). They
102         * are not updated when values are obtained from the monitor.
103         *
104         * @return ms timestamp of the last usage
105         */
106        long getLastUsage();
107
108        /**
109         * Samples Simon values and returns them in a Java Bean derived from Sample interface.
110         *
111         * @return sample containing all Simon values
112         */
113        Sample sample();
114
115        /**
116         * Samples increment in Simon values since the previous call of this method with the
117         * same key. When the method is called the first time for the key, current values
118         * are returned (same like from {@link #sample()}. Any subsequent calls with the key
119         * provide increments.
120         * <p/>
121         * Clients can use any sampling key (any Object) which enables safe access to their own increments.
122         * Using String does not guarantee this as any client can potentially guess the key. This
123         * may or may not be an issue.
124         *
125         * @param key sampling key used to access incremental sample
126         * @return {@link org.javasimon.Sample} with value increments
127         * @since 3.5
128         */
129        Sample sampleIncrement(Object key);
130
131        /**
132         * Samples current value of incremental Simon. Works like {@link #sampleIncrement(Object)} but
133         * does not reset the incremental Simon. This method <b>does not</b> start incremental sampling
134         * and keeps returning values from {@link #sample()} for any key that was not used with
135         * {@link #sampleIncrement(Object)} before.
136         *
137         * @param key sampling key used to access incremental sample
138         * @return {@link org.javasimon.Sample} with value increments
139         * @see #sampleIncrement(Object)
140         * @since 4.1
141         */
142        Sample sampleIncrementNoReset(Object key);
143
144        /**
145         * Stops incremental sampling for the key, removing any internal information for the key.
146         * Next call to {@link #sampleIncrement(Object)} for the key will be considered the first
147         * call for the key.
148         *
149         * @param key sampling key used to access incremental sample
150         * @return true if incremental information for the key existed, false otherwise
151         * @since 3.5
152         */
153        boolean stopIncrementalSampling(Object key);
154}