statsviewer.java

openfire 服务器源码下载

/**
 * $Revision  $
 * $Date  $
 *
 * Copyright (C) 2008 Jive Software. All rights reserved.
 *
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution, or a commercial license
 * agreement with Jive.
 */

package org.jivesoftware.openfire.reporting.stats;

import org.jivesoftware.openfire.stats.Statistic;

/**
 * Provides a view into the stats being tracked by the stats engine.
 *
 * @author Alexander Wenckus
 */
public interface StatsViewer {

    /**
     * Returns any multistat group keys and any keys that are not part of a multistat.
     *
     * @return any multistat group names and any stats that are not part of a multistat.
     */
    String [] getAllHighLevelStatKeys();

    /**
     * Returns all statistic objects for a related key. For instance if the key is a multistat
     * more than one Statistic will be returned. Statistic objects contain the meta information
     * for a stat.
     *
     * @param statKey the key of the stat.
     * @return all statistic objects for a related key.
     * @throws IllegalArgumentException if the stat related to the statKey does not exist.
     */
    Statistic[] getStatistic(String statKey);

    /**
     * Returns the last time this statistic was sampled.
     *
     * @param key the key for the statistic.
     * @return the last time this statistic was sampled in milliseconds since the epoch.
     */
    long getLastSampleTime(String key);

    /**
     * Retrieves the data for the related stat between the specified time period.
     *
     * @param key the key for the stat of which the data is being retrieved.
     * @param startTime the lower bound of the time period in milliseconds since the epoch.
     * @param endTime the upper bound of the time period in milliseconds since the epoch.
     * @return an array of doubles representing the stat. If the stat is a multistat,
     *      more than one array is returned.
     */
    double[][] getData(String key, long startTime, long endTime);

    /**
     * Retrieves the data for the related stat between the time period specified. The number
     * of datapoints indicates how many doubles are to be returned for each stat, the
     * statviewer will make a best effort ot conform to this, but if the backing datastore doesn't
     * have a resolution for that particular amount of points then the closest match will be
     * returned.
     *
     * @param key the key for the stat of which the data is being retrieved.
     * @param startTime the lower bound of the time period.
     * @param endTime the upper bound of the time period.
     * @param dataPoints the number of desired datapoints
     * @return an array of doubles representing the stat. If the stat is a multistat,
     *      more than one array is returned.
     * @deprecated will be removed pending the completion of #getData(String, TimePeriod)
     */
    double[][] getData(String key, long startTime, long endTime, int dataPoints);

    /**
     * Retrieves the data for the related stat for the time period.
     *
     * @param key the key for the statistic.
     * @param timePeriod the timeperiod for which the data is desired.
     * @return an array of doubles representing the stat. If the stat is a multistat,
     *      more than one array is returned.
     * @see #getData(String, long, long)
     */
    StatView getData(String key, TimePeriod timePeriod);

    /**
     * Returns an array of doubles which is the max value between the time periods.
     * If the provided key relates to a multistat, each array element relates to a max
     * for that particular stat. If it is not a multistat, the array will be of length 1.
     *
     * @param key the multistat or stat key related to the stat.
     * @param startTime the start time or lower range.
     * @param endTime the end time or upper range
     * @return an array of doubles which is the max value between the time periods.
     */
    double[] getMax(String key, long startTime, long endTime);

    double[] getMax(String key, long startTime, long endTime, int dataPoints);

    /**
     * Returns an array of doubles which is the max value for a time period.
     * If the provided key relates to a multistat, each array element relates to a max
     * for that particular stat. If it is not a multistat, the array will be of length 1.
     *
     * @param key the multistat or stat key related to the stat.
     * @param timePeriod the time period over which the max should be returned.
     * @return an array of doubles which is the max value for the time period.
     */
    double[] getMax(String key, TimePeriod timePeriod);

    /**
     * Returns an array of doubles which is the minimum value between the time periods.
     * If the provided key relates to a multistat, each array element relates to a minimum
     * for that particular stat. If it is not a multistat, the array will be of length 1.
     *
     * @param key the multistat or stat key related to the stat.
     * @param startTime the start time or lower range.
     * @param endTime the end time or upper range
     * @return an array of doubles which is the min value between the time periods.
     */
    double[] getMin(String key, long startTime, long endTime);

    double[] getMin(String key, long startTime, long endTime, int dataPoints);

    /**
     * Returns an array of doubles which is the minimum value for a time period.
     * If the provided key relates to a multistat, each array element relates to a minimum
     * for that particular stat. If it is not a multistat, the array will be of length 1.
     *
     * @param key the multistat or stat key related to the stat.
     * @param timePeriod the time period over which the min should be returned.
     * @return an array of doubles which is the min value for the time period.
     */
    double[] getMin(String key, TimePeriod timePeriod);

    /**
     * Returns the last recorded value for a stat.
     *
     * @param key the key for the stat.
     * @return the last value for a stat.
     * @see #getLastSampleTime(String)
     */
    double[] getCurrentValue(String key);

    /**
     * An enumeration for time period choices. A time period helps the stats viewer
     * determine the period of time which data should be  returned, it also provides a
     * suggestion on the number of datapoints that should be provided.
     */
    public enum TimePeriod {
        last_hour(3600, 15),
        last_day(43200, 15);

        private long timePeriod;
        private int dataPoints;

        private TimePeriod(long timePeriod, int dataPoints) {
            this.timePeriod = timePeriod;
            this.dataPoints = dataPoints;
        }

        /**
         * Takes an end time and returns a relative start time based off of the time period
         * this method is being operated off of.
         *
         * @param endTime the end time, the time period is substracted from this to
         *      determine the start time.
         * @return the determined start time.
         */
        public long getStartTime(long endTime) {
            return endTime - timePeriod;
        }

        /**
         * A suggestion for the number of data points that should be returned.
         *
         * @return a suggestion for the number of data points that should be returned.
         */
        public int getDataPoints() {
            return dataPoints;
        }

        public long getTimePeriod() {
            return timePeriod;
        }
    }

    /**
     * A snapshot of a stat in time.
     */
    public final class StatView {
        private long startTime;
        private long endTime;
        private double[][] data;

        public StatView(long startTime, long endTime, double[][] data) {
            this.startTime = startTime;
            this.endTime = endTime;
            this.data = data;
        }

        /**
         * The starting time of the snap shot.
         *
         * @return the starting time of the snap shot.
         */
        public long getStartTime() {
            return startTime;
        }

        /**
         * The end time of the snap shot.
         *
         * @return the end time of the snap shot.
         */
        public long getEndTime() {
            return endTime;
        }

        /**
         * The data related to the snap shot.
         *
         * @return The data related to the snap shot.
         */
        public double[][] getData() {
            return data;
        }
    }
}