001package org.javasimon;
002
003import org.javasimon.callback.CompositeCallback;
004import org.javasimon.clock.SimonClock;
005
006import java.util.Collection;
007
008/**
009 * Manager provides access to Simons and manages them in a tree structure. Any number of Managers
010 * can be created. There is also one special Manager (called "default manager") that is accessible
011 * via convenient static utility class {@link SimonManager}.
012 * <p/>
013 * Three different implementations exist:
014 * <ul>
015 * <li>{@link EnabledManager} represents fully functional manager in the enabled state;</li>
016 * <li>{@link DisabledManager} is manager implementation in the disabled state;</li>
017 * <li>{@link SwitchingManager} is manager implementation with both enabled and disabled manager in the background,
018 * only this implementation supports {@link #enable()} and {@link #disable()} method.</li>
019 * </ul>
020 *
021 * @author <a href="mailto:virgo47@gmail.com">Richard "Virgo" Richter</a>
022 */
023public interface Manager extends SimonClock {
024
025        /** Name of the root Simon. */
026        String ROOT_SIMON_NAME = "";
027
028        /** Hierarchy delimiter in Simon name. */
029        String HIERARCHY_DELIMITER = ".";
030
031        /**
032         * Returns root Simon. Type of the Simon is unknown at the start but it can be replaced
033         * by the real Simon later. Specific get method with root Simon name constant can be used
034         * in that case.
035         *
036         * @return root Simon
037         */
038        Simon getRootSimon();
039
040        /**
041         * Returns Simon by its name if it exists.
042         *
043         * @param name name of the Simon
044         * @return Simon object
045         */
046        Simon getSimon(String name);
047
048        /**
049         * Returns existing Counter or creates new if necessary. "Anonymous" Counter can
050         * be obtained if null name is specified - then it is not added to the Simon hierarchy.
051         *
052         * @param name name of the Counter
053         * @return counter object
054         */
055        Counter getCounter(String name);
056
057        /**
058         * Returns existing Stopwatch or creates new if necessary. "Anonymous" Stopwatch can
059         * be obtained if null name is specified - then it is not added to the Simon hierarchy.
060         *
061         * @param name name of the Stopwatch
062         * @return stopwatch object
063         */
064        Stopwatch getStopwatch(String name);
065
066        /**
067         * Returns unmodifiable collection containing names of all existing Simons. Collection is not ordered.
068         *
069         * @return collection of all Simon names
070         * @since 3.1
071         */
072        Collection<String> getSimonNames();
073
074        /**
075         * Returns collection containing all existing Simons accepted by specified {@link SimonFilter}.
076         * If {@code null} filter is provided all Simons are returned in an unmodifiable Collection.
077         * Otherwise new collection with matching Simons is returned.
078         *
079         * @param simonFilter filter accepting the Simons to result collection
080         * @return collection of all Simons which pass the filter
081         * @see SimonPattern to find out more about possible patterns
082         * @since 3.2
083         */
084        Collection<Simon> getSimons(SimonFilter simonFilter);
085
086        /**
087         * Removes Simon from the Manager. If Simon has some children it will be replaced
088         * by UnknownSimon.
089         *
090         * @param name name of the Simon
091         */
092        void destroySimon(String name);
093
094        /**
095         * Clears the whole manager and starts again with a single newly created Root Simon.
096         */
097        void clear();
098
099        /**
100         * Accesses default composite callback of this manager. Default callback can't be removed or replaced,
101         * only other callbacks can be added or removed.
102         *
103         * @return Simon callback
104         */
105        CompositeCallback callback();
106
107        /**
108         * Accesses configuration of this manager.
109         *
110         * @return configuration of this manager
111         */
112        ManagerConfiguration configuration();
113
114        /**
115         * Enables the Simon Manager. Enabled manager provides real Simons.
116         * Only {@link org.javasimon.SwitchingManager} supports this operation.
117         */
118        void enable();
119
120        /**
121         * Disables the Simon Manager. Disabled manager provides null Simons that actually do nothing.
122         * Only {@link org.javasimon.SwitchingManager} supports this operation.
123         */
124        void disable();
125
126        /**
127         * Returns true if the Java Simon API is enabled.
128         *
129         * @return true if the API is enabled
130         */
131        boolean isEnabled();
132
133        /**
134         * Method propagates message to manager's {@link org.javasimon.callback.Callback}. This allows user to report any
135         * message if they implement {@link org.javasimon.callback.Callback#onManagerMessage(String)}.
136         *
137         * @param message message text
138         */
139        void message(String message);
140
141        /**
142         * Method propagates warning to manager's {@link org.javasimon.callback.Callback}. This allows user to report any
143         * warning and/or exception if they implement {@link org.javasimon.callback.Callback#onManagerWarning(String, Exception)}.
144         *
145         * @param warning arbitrary warning message
146         * @param cause exception causing this warning
147         */
148        void warning(String warning, Exception cause);
149}