001package org.javasimon.jdbc4.jmx;
002
003import org.javasimon.jmx.StopwatchSample;
004
005/**
006 * Interface of JDBC management bean (MXBean).
007 * <p/>
008 * JDBC MXBean provides management operations for monitoring JDBC driver
009 * and operations to retrieve gathered statistics from special JDBC hierarchy of Simons.<br>
010 * This JDBC hierarchy of Simon is well known and specified in JDBC javadoc
011 * ({@link org.javasimon.jdbc4}). There is prefix of this hierarchy that is associated with
012 * one instance of monitored JDBC driver. Typically, there is only one driver instance used
013 * in application, because of connection to one type of database. If application is connected
014 * to different types of database (i.e. oracle and mysql), there is possibility to differentiate
015 * each used driver by specifying Simon hierarchy prefix for driver.<br>
016 * Jdbc mxbean has prefix associated with it. It's is initialized through mxbean implementation
017 * class constructor ({@link JdbcMXBeanImpl#JdbcMXBeanImpl(org.javasimon.Manager, String)})
018 * or later through setter ({@link #setPrefix(String)}). Then is also possible to register Jdbc mxbean
019 * for each prefix.
020 * <p/>
021 * Monitoring of the JDBC driver is enabled only if Java Simon JDBC proxy driver is used
022 * over original JDBC driver (eg. Oracle, PostgreSQL, MySQL etc.). For more details how to do
023 * that, please look at {@link org.javasimon.jdbc4.Driver} a package {@link org.javasimon.jdbc4}
024 * javadoc.
025 *
026 * @author Radovan Sninsky
027 * @author <a href="mailto:virgo47@gmail.com">Richard "Virgo" Richter</a>
028 * @see JdbcMXBeanImpl
029 * @since 2
030 */
031public interface JdbcMXBean {
032        /**
033         * Returns actual prefix associated with mxbean.
034         *
035         * @return actual prefix
036         */
037        String getPrefix();
038
039        /**
040         * Sets custom prefix of JDBC Simon hierarchy, see more {@link JdbcMXBean}.
041         *
042         * @param value new prefix
043         */
044        void setPrefix(String value);
045
046        /**
047         * Enables monitoring (gathering statistics) by associated JDBC Simon hierarchy, see
048         * ({@code org.javasimon.jdbc}). Works if SimonManager is enabled, look
049         * {@link org.javasimon.SimonManager#isEnabled()}.
050         */
051        void enableMonitoring();
052
053        /**
054         * Disables monitoring (gathering statistics) by associated JDBC Simon hierarchy, see
055         * ({@code org.javasimon.jdbc}). If SimonManager is already disabled has no effect,
056         * look {@link org.javasimon.SimonManager#disable()}.
057         */
058        void disableMonitoring();
059
060        /**
061         * Returns state of monitoring JDBC driver.
062         *
063         * @return {@code true} if associated prefix is enabled; otherwise {@code false}
064         */
065        boolean isMonitoringEnabled();
066
067        /**
068         * Retrieves summary data about JDBC connection objects.
069         *
070         * @return value object {@link JdbcObjectInfo}
071         */
072        JdbcObjectInfo connectionsStat();
073
074        /**
075         * Retrieves summary data about JDBC statement objects.
076         *
077         * @return value object {@link JdbcObjectInfo}
078         */
079        JdbcObjectInfo statementsStat();
080
081        /**
082         * Retrieves summary data about JDBC result set objects.
083         *
084         * @return value object {@link JdbcObjectInfo}
085         */
086        JdbcObjectInfo resultsetsStat();
087
088        /**
089         * Returns SQL command types ({@code select}, {@code insert}, {@code delete}, etc).
090         * If client application uses DDL commands like {@code create}, {@code alter} and other,
091         * those are included too. Special case are batch-es, they are referenced as {@code batch}.
092         *
093         * @return list of string (references to used SQL command types in monitored (simoned) application)
094         * @see #getSqlCommandStat(String)
095         * @see #getSqls(String)
096         */
097        String[] getSqlCommands();
098
099        /**
100         * Retrieves summary data about all executed SQL commands of eneterd type (for instance
101         * summary data of all executed selects).
102         *
103         * @param cmd SQL command type
104         * @return populated object {@link org.javasimon.jmx.StopwatchSample}, or {@code null} if
105         *         entered sql command type has no associated javasimon (it means, no sql of this type was
106         *         executed yet, for instance no update was executed yet)
107         * @see #connectionsStat()
108         */
109        StopwatchSample getSqlCommandStat(String cmd);
110
111        /**
112         * Returns hashs of different SQL commands of one type ({@code select}, {@code insert},
113         * {@code delete}, etc). Each hash represent one sql command with (and its many executions).
114         *
115         * @param cmd cmd SQL command type ({@code select}, {@code insert}, {@code delete}, etc)
116         * @return list of string (hash references to used SQL command in monitored (simoned) application)
117         * @see #getSqlCommands()
118         * @see #getSqlStat(String)
119         */
120        String[] getSqls(String cmd);
121
122        /**
123         * Retrieves summary data about all same executed SQLs (for instance
124         * summary data of all executed {@code select * from foo where bar => 0}).
125         *
126         * @param sql hash code of sql command
127         * @return populated object {@link org.javasimon.jmx.StopwatchSample}, or {@code null} if
128         *         entered sql has no associated javasimon (it means, no sql like this was executed yet,
129         *         for instance no update was executed yet)
130         * @see #getSqls(String)
131         */
132        StopwatchSample getSqlStat(String sql);
133}