dataprocessor.java

jrobin,使用纯java实现的RRD数据库,使用RRD数据库来统计数据.

	 *
	 * @param sourceName Datasource name
	 * @return Object containing all aggregated values
	 * @throws RrdException Thrown if invalid datasource name is specified,
	 *                      or if datasource values are not yet calculated (method {@link #processData()}
	 *                      was not called)
	 */
	public Aggregates getAggregates(String sourceName) throws RrdException {
		Source source = getSource(sourceName);
		return source.getAggregates(tStart, tEnd);
	}

	/**
	 * This method is just an alias for {@link #getPercentile(String)} method.
	 * <p/>
	 * Used by ISPs which charge for bandwidth utilization on a "95th percentile" basis.<p>
	 * <p/>
	 * The 95th percentile is the highest source value left when the top 5% of a numerically sorted set
	 * of source data is discarded. It is used as a measure of the peak value used when one discounts
	 * a fair amount for transitory spikes. This makes it markedly different from the average.<p>
	 * <p/>
	 * Read more about this topic at
	 * <a href="http://www.red.net/support/resourcecentre/leasedline/percentile.php">Rednet</a> or
	 * <a href="http://www.bytemark.co.uk/support/tech/95thpercentile.html">Bytemark</a>.
	 *
	 * @param sourceName Datasource name
	 * @return 95th percentile of fetched source values
	 * @throws RrdException Thrown if invalid source name is supplied
	 */
	public double get95Percentile(String sourceName) throws RrdException {
		return getPercentile(sourceName);
	}

	/**
	 * Used by ISPs which charge for bandwidth utilization on a "95th percentile" basis.<p>
	 * <p/>
	 * The 95th percentile is the highest source value left when the top 5% of a numerically sorted set
	 * of source data is discarded. It is used as a measure of the peak value used when one discounts
	 * a fair amount for transitory spikes. This makes it markedly different from the average.<p>
	 * <p/>
	 * Read more about this topic at
	 * <a href="http://www.red.net/support/resourcecentre/leasedline/percentile.php">Rednet</a> or
	 * <a href="http://www.bytemark.co.uk/support/tech/95thpercentile.html">Bytemark</a>.
	 *
	 * @param sourceName Datasource name
	 * @return 95th percentile of fetched source values
	 * @throws RrdException Thrown if invalid source name is supplied
	 */
	public double getPercentile(String sourceName) throws RrdException {
		return getPercentile(sourceName, DEFAULT_PERCENTILE);
	}

	/**
	 * The same as {@link #getPercentile(String)} but with a possibility to define custom percentile boundary
	 * (different from 95).
	 *
	 * @param sourceName Datasource name.
	 * @param percentile Boundary percentile. Value of 95 (%) is suitable in most cases, but you are free
	 *                   to provide your own percentile boundary between zero and 100.
	 * @return Requested percentile of fetched source values
	 * @throws RrdException Thrown if invalid sourcename is supplied, or if the percentile value makes no sense.
	 */
	public double getPercentile(String sourceName, double percentile) throws RrdException {
		if (percentile <= 0.0 || percentile > 100.0) {
			throw new RrdException("Invalid percentile [" + percentile + "], should be between 0 and 100");
		}
		Source source = getSource(sourceName);
		return source.getPercentile(tStart, tEnd, percentile);
	}

	/**
	 * Returns array of datasource names defined in this DataProcessor.
	 *
	 * @return array of datasource names
	 */
	public String[] getSourceNames() {
		return sources.keySet().toArray(new String[0]);
	}

	/**
	 * Returns an array of all datasource values for all datasources. Each row in this two-dimensional
	 * array represents an array of calculated values for a single datasource. The order of rows is the same
	 * as the order in which datasources were added to this DataProcessor object.
	 *
	 * @return All datasource values for all datasources. The first index is the index of the datasource,
	 *         the second index is the index of the datasource value. The number of datasource values is equal
	 *         to the number of timestamps returned with {@link #getTimestamps()}  method.
	 * @throws RrdException Thrown if invalid datasource name is specified,
	 *                      or if datasource values are not yet calculated (method {@link #processData()}
	 *                      was not called)
	 */
	public double[][] getValues() throws RrdException {
		String[] names = getSourceNames();
		double[][] values = new double[names.length][];
		for (int i = 0; i < names.length; i++) {
			values[i] = getValues(names[i]);
		}
		return values;
	}

	private Source getSource(String sourceName) throws RrdException {
		Source source = sources.get(sourceName);
		if (source != null) {
			return source;
		}
		throw new RrdException("Unknown source: " + sourceName);
	}

	/////////////////////////////////////////////////////////////////
	// DATASOURCE DEFINITIONS
	/////////////////////////////////////////////////////////////////

	/**
	 * <p>Adds a custom, {@link org.jrobin.data.Plottable plottable} datasource (<b>PDEF</b>).
	 * The datapoints should be made available by a class extending
	 * {@link org.jrobin.data.Plottable Plottable} class.</p>
	 *
	 * @param name	  source name.
	 * @param plottable class that extends Plottable class and is suited for graphing.
	 */
	public void addDatasource(String name, Plottable plottable) {
		PDef pDef = new PDef(name, plottable);
		sources.put(name, pDef);
	}

	/**
	 * <p>Adds complex source (<b>CDEF</b>).
	 * Complex sources are evaluated using the supplied <code>RPN</code> expression.</p>
	 * <p/>
	 * <p>Complex source <code>name</code> can be used:</p>
	 * <ul>
	 * <li>To specify sources for line, area and stack plots.</li>
	 * <li>To define other complex sources.</li>
	 * </ul>
	 * <p/>
	 * <p>JRobin supports the following RPN functions, operators and constants: +, -, *, /,
	 * %, SIN, COS, LOG, EXP, FLOOR, CEIL, ROUND, POW, ABS, SQRT, RANDOM, LT, LE, GT, GE, EQ,
	 * IF, MIN, MAX, LIMIT, DUP, EXC, POP, UN, UNKN, NOW, TIME, PI, E,
	 * AND, OR, XOR, PREV, PREV(sourceName), INF, NEGINF, STEP, YEAR, MONTH, DATE,
	 * HOUR, MINUTE, SECOND, WEEK, SIGN and RND.</p>
	 * <p/>
	 * <p>JRobin does not force you to specify at least one simple source name as RRDTool.</p>
	 * <p/>
	 * <p>For more details on RPN see RRDTool's
	 * <a href="http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/manual/rrdgraph.html" target="man">
	 * rrdgraph man page</a>.</p>
	 *
	 * @param name		  source name.
	 * @param rpnExpression RPN expression containig comma (or space) delimited simple and complex
	 *                      source names, RPN constants, functions and operators.
	 */
	public void addDatasource(String name, String rpnExpression) {
		CDef cDef = new CDef(name, rpnExpression);
		sources.put(name, cDef);
	}

	/**
	 * <p>Adds static source (<b>SDEF</b>). Static sources are the result of a consolidation function applied
	 * to *any* other source that has been defined previously.</p>
	 *
	 * @param name	  source name.
	 * @param defName   Name of the datasource to calculate the value from.
	 * @param consolFun Consolidation function to use for value calculation
	 */
	public void addDatasource(String name, String defName, String consolFun) {
		SDef sDef = new SDef(name, defName, consolFun);
		sources.put(name, sDef);
	}

	/**
	 * <p>Adds simple datasource (<b>DEF</b>). Simple source <code>name</code>
	 * can be used:</p>
	 * <ul>
	 * <li>To specify sources for line, area and stack plots.</li>
	 * <li>To define complex sources
	 * </ul>
	 *
	 * @param name	   source name.
	 * @param file	   Path to RRD file.
	 * @param dsName	 Datasource name defined in the RRD file.
	 * @param consolFunc Consolidation function that will be used to extract data from the RRD
	 *                   file ("AVERAGE", "MIN", "MAX" or "LAST" - these string constants are conveniently defined
	 *                   in the {@link org.jrobin.core.ConsolFuns ConsolFuns} class).
	 */
	public void addDatasource(String name, String file, String dsName, String consolFunc) {
		Def def = new Def(name, file, dsName, consolFunc);
		sources.put(name, def);
	}

	/**
	 * <p>Adds simple source (<b>DEF</b>). Source <code>name</code> can be used:</p>
	 * <ul>
	 * <li>To specify sources for line, area and stack plots.</li>
	 * <li>To define complex sources
	 * </ul>
	 *
	 * @param name	   Source name.
	 * @param file	   Path to RRD file.
	 * @param dsName	 Data source name defined in the RRD file.
	 * @param consolFunc Consolidation function that will be used to extract data from the RRD
	 *                   file ("AVERAGE", "MIN", "MAX" or "LAST" - these string constants are conveniently defined
	 *                   in the {@link org.jrobin.core.ConsolFuns ConsolFuns} class).
	 * @param backend	Name of the RrdBackendFactory that should be used for this RrdDb.
	 */
	public void addDatasource(String name, String file, String dsName, String consolFunc, String backend) {
		Def def = new Def(name, file, dsName, consolFunc, backend);
		sources.put(name, def);
	}

	/**
	 * Adds DEF datasource with datasource values already available in the FetchData object. This method is
	 * used internally by JRobin and probably has no purpose outside of it.
	 *
	 * @param name	  Source name.
	 * @param fetchData Fetched data containing values for the given source name.
	 */
	public void addDatasource(String name, FetchData fetchData) {
		Def def = new Def(name, fetchData);
		sources.put(name, def);
	}

	/////////////////////////////////////////////////////////////////
	// CALCULATIONS
	/////////////////////////////////////////////////////////////////

	/**
	 * Method that should be called once all datasources are defined. Data will be fetched from
	 * RRD files, RPN expressions will be calculated, etc.
	 *
	 * @throws IOException  Thrown in case of I/O error (while fetching data from RRD files)
	 * @throws RrdException Thrown in case of JRobin specific error
	 */
	public void processData() throws IOException, RrdException {
		extractDefs();
		fetchRrdData();
		fixZeroEndingTimestamp();
		chooseOptimalStep();
		createTimestamps();
		assignTimestampsToSources();
		normalizeRrdValues();
		calculateNonRrdSources();
	}

	/**
	 * Method used to calculate datasource values which should be presented on the graph
	 * based on the desired graph width. Each value returned represents a single pixel on the graph.
	 * Corresponding timestamp can be found in the array returned from {@link #getTimestampsPerPixel()}
	 * method.
	 *
	 * @param sourceName Datasource name
	 * @param pixelCount Graph width
	 * @return Per-pixel datasource values
	 * @throws RrdException Thrown if datasource values are not yet calculated (method {@link #processData()}
	 *                      was not called)
	 */
	public double[] getValuesPerPixel(String sourceName, int pixelCount) throws RrdException {
		setPixelCount(pixelCount);
		return getValuesPerPixel(sourceName);
	}

	/**
	 * Method used to calculate datasource values which should be presented on the graph
	 * based on the graph width set with a {@link #setPixelCount(int)} method call.
	 * Each value returned represents a single pixel on the graph. Corresponding timestamp can be
	 * found in the array returned from {@link #getTimestampsPerPixel()} method.
	 *
	 * @param sourceName Datasource name
	 * @return Per-pixel datasource values
	 * @throws RrdException Thrown if datasource values are not yet calculated (method {@link #processData()}
	 *                      was not called)
	 */
	public double[] getValuesPerPixel(String sourceName) throws RrdException {
		double[] values = getValues(sourceName);
		double[] pixelValues = new double[pixelCount];
		Arrays.fill(pixelValues, Double.NaN);
		long span = tEnd - tStart;
		// this is the ugliest nested loop I have ever made
		for (int pix = 0, ref = 0; pix < pixelCount; pix++) {
			double t = tStart + (double) (span * pix) / (double) (pixelCount - 1);
			while (ref < timestamps.length) {
				if (t <= timestamps[ref] - step) {
					// too left, nothing to do, already NaN
					break;
				}
				else if (t <= timestamps[ref]) {
					// in brackets, get this value
					pixelValues[pix] = values[ref];
					break;
				}
				else {
					// too right
					ref++;
				}
			}
		}
		return pixelValues;
	}