Monitor.java 4.59 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10
 */
11

Matt Tucker's avatar
Matt Tucker committed
12 13 14 15 16
package org.jivesoftware.net;

import java.util.Date;

/**
17 18 19
 * Monitors a network usage. Monitors measure sample totals, and sample rate
 * (samples per second). Monitor information is used at runtime to adjust
 * server behavior as well as to generate reports on server history.<p>
Matt Tucker's avatar
Matt Tucker committed
20
 *
21 22
 * Based in part on the DataMonitor from Java Distributed Computing, Jim Farley,
 * O'Reilly.
Matt Tucker's avatar
Matt Tucker committed
23 24 25 26 27 28
 *
 * @author Iain Shigeoka
 */
public interface Monitor {

    /**
29 30
     * Add the number of samples that occured between the given start and
     * end times.<p>
Matt Tucker's avatar
Matt Tucker committed
31
     *
32
     * The monitor does not check for overlapping sample times. It is
Matt Tucker's avatar
Matt Tucker committed
33 34
     * the caller's responsibility to ensure samples don't overlap. Failure
     * to prevent overlapping sample times may result in elapsed time
35
     * being falsely counted and reported.
Matt Tucker's avatar
Matt Tucker committed
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
     *
     * @param quantity The number of samples that occurred during the sample period
     * @param startTime The beginning of the sample period
     * @param endTime The end of the sample period
     */
    void addSample(long quantity, Date startTime, Date endTime);

    /**
     * <p>Add the number of samples that occured between the last sample date,
     * and the current time.</p>
     *
     * <p>A convenience method when samples occur in sequential periods.
     * Equivalent to:</p>
     * <pre><code>
     * monitor.addSample(quantity, monitor.getLastSampleDate(), new Date());
     * </code></pre>
     *
     * @param quantity The number of samples that occurred between the
     * last sample date and now
     */
    void addSample(long quantity);

    /**
     * <p>Obtain the total number of samples reported during the monitor's lifetime.</p>
     *
     * @return The total number of samples reported to the monitor
     */
    long getTotal();

    /**
     * <p>Obtain the total amount of time (in milliseconds) that the monitor
     * has samples for.</p>
     *
     * @return The total time (in milliseconds) samples have been recorded for
     */
    long getTotalTime();

    /**
     * <p>Obtain the rate of samples reported during the monitor's lifetime.</p>
     *
     * @return The average rate of samples reported to the monitor
     */
    float getRate();

    /**
     * <p>The date-time of the first sample reported to the monitor.</p>
     *
     * @return The date-time of the first sample reported to the monitor
     */
    Date getFirstSampleDate();

    /**
     * <p>The date-time of the last sample reported to the monitor.</p>
     *
     * @return The date-time of the last sample reported to the monitor
     */
    Date getLastSampleDate();

    /**
     * <p>The size of the moving frame (in sample events)
     * that provides a recent view of the data.</p>
     *
     * <p>Samples can be monitored and managed based on
     * the usage within the most recent number of samples reported
     * during the frame. Larger frame sizes 'smooths' the results
     * creating frame statistics that are less affected by outlying samples but
     * requiring larger amounts of memory to store and more resources to calculate
     * frame statistics.</p>
     *
     * @return The sample frame size in seconds
     */
    int getFrameSize();

    /**
     * <p>Sets the size of the moving frame (in sample events).</p>
     *
     * <p>Changing the frame size to a larger value will not automatically
     * include past samples that were previously outside the frame. Instead,
     * the monitor will not return accurate frame related data until the
     * new frame is filled with new data.</p>
     *
     * <p>Warning: Larger frame sizes consume larger amounts of memory
     * per monitor and increases the amount of work required to generate
     * frame statistics. Set the framesize to the smallest useful size or zero
     * to not record any frame related data.</p>
     *
     * @param frameSize The new size of the sample frame in seconds
     */
    void setFrameSize(int frameSize);

    /**
     * <p>Obtain the sample total during the frame.</p>
     *
     * @return The sample total during the frame.
     */
    long getFrameTotal();

    /**
     * <p>Obtain the total sample time during the frame.</p>
     *
     * @return The total sample time during the frame.
     */
    long getFrameTotalTime();

    /**
     * <p>Obtain the number of bytes read during the frame.</p>
     *
     * @return The number of bytes read during the frame.
     */
    float getFrameRate();
}