rrdgraphdeftemplate.java

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

/* ============================================================
 * JRobin : Pure java implementation of RRDTool's functionality
 * ============================================================
 *
 * Project Info:  http://www.jrobin.org
 * Project Lead:  Sasa Markovic ([e-mail]);
 *
 * (C) Copyright 2003-2005, by Sasa Markovic.
 *
 * Developers:    Sasa Markovic ([e-mail])
 *
 *
 * This library is free software; you can redistribute it and/or modify it under the terms
 * of the GNU Lesser General Public License as published by the Free Software Foundation;
 * either version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License along with this
 * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307, USA.
 */
package org.jrobin.graph;

import org.jrobin.core.RrdException;
import org.jrobin.core.Util;
import org.jrobin.core.XmlTemplate;
import org.w3c.dom.Node;
import org.xml.sax.InputSource;

import java.awt.*;
import java.io.File;
import java.io.IOException;

/**
 * Class used to create an arbitrary number of RrdGraphDef (graph definition) objects
 * from a single XML template. XML template can be supplied as an XML InputSource,
 * XML file or XML formatted string.<p>
 * <p/>
 * Here is an example of a properly formatted XML template with all available options in it
 * (unwanted options can be removed/ignored):<p>
 * <pre>
 * &lt;rrd_graph_def&gt;
 *     &lt;!-- use '-' to represent in-memory graph --&gt;
 *     &lt;filename&gt;test.png&lt;/filename&gt;
 *     &lt;!--
 *         starting and ending timestamps can be specified by
 *         using at-style time specification, or by specifying
 *         exact timestamps since epoch (without milliseconds)
 *     --&gt;
 *     &lt;span&gt;
 *         &lt;start&gt;now - 1d&lt;/start&gt;
 *         &lt;end&gt;now&lt;/end&gt;
 *     &lt;/span&gt;
 *     &lt;options&gt;
 *         &lt;!--
 *             specify 'true' if you want to use RrdDbPool while
 *             creating graph
 *         --&gt;
 *         &lt;use_pool&gt;false&lt;/use_pool&gt;
 *         &lt;anti_aliasing&gt;true&lt;/anti_aliasing&gt;
 *         &lt;time_grid&gt;
 *             &lt;show_grid&gt;true&lt;/show_grid&gt;
 *             &lt;!-- allowed units: second, minute, hour, day, week, month, year --&gt;
 *             &lt;minor_grid_unit&gt;minute&lt;/minor_grid_unit&gt;
 *             &lt;minor_grid_unit_count&gt;60&lt;/minor_grid_unit_count&gt;
 *             &lt;major_grid_unit&gt;hour&lt;/major_grid_unit&gt;
 *             &lt;major_grid_unit_count&gt;2&lt;/major_grid_unit_count&gt;
 *             &lt;label_unit&gt;hour&lt;/label_unit&gt;
 *             &lt;label_unit_count&gt;2&lt;/label_unit_count&gt;
 *             &lt;label_span&gt;1200&lt;/label_span&gt;
 *             &lt;!-- use SimpleDateFormat or strftime-like format to format labels --&gt;
 *             &lt;label_format&gt;dd-MMM-yy&lt;/label_format&gt;
 *         &lt;/time_grid&gt;
 *         &lt;value_grid&gt;
 *             &lt;show_grid&gt;true&lt;/show_grid&gt;
 *             &lt;grid_step&gt;100.0&lt;/grid_step&gt;
 *             &lt;label_factor&gt;5&lt;/label_factor&gt;
 *         &lt;/value_grid&gt;
 *         &lt;no_minor_grid&gt;true&lt;/no_minor_grid&gt;
 *         &lt;alt_y_grid&gt;true&lt;/alt_y_grid&gt;
 *         &lt;alt_y_mrtg&gt;true&lt;/alt_y_mrtg&gt;
 *         &lt;alt_autoscale&gt;true&lt;/alt_autoscale&gt;
 *         &lt;alt_autoscale_max&gt;true&lt;/alt_autoscale_max&gt;
 *         &lt;units_exponent&gt;3&lt;/units_exponent&gt;
 *         &lt;units_length&gt;13&lt;/units_length&gt;
 *         &lt;vertical_label&gt;Speed (kbits/sec)&lt;/vertical_label&gt;
 *         &lt;width&gt;444&lt;/width&gt;
 *         &lt;height&gt;222&lt;/height&gt;
 *         &lt;interlaced&gt;true&lt;/interlaced&gt;
 *         &lt;image_info&gt;filename = %s, width=%d, height=%d&lt;/image_info&gt;
 *         &lt;image_format&gt;png&lt;/image_format&gt;
 *         &lt;image_quality&gt;0.8&lt;/image_quality&gt;
 *         &lt;background_image&gt;luka.png&lt;/background_image&gt;
 *         &lt;overlay_image&gt;luka.png&lt;/overlay_image&gt;
 *         &lt;unit&gt;kilos&lt;/unit&gt;
 *         &lt;lazy&gt;false&lt;/lazy&gt;
 *         &lt;min_value&gt;0&lt;/min_value&gt;
 *         &lt;max_value&gt;5000&lt;/max_value&gt;
 *         &lt;rigid&gt;true&lt;/rigid&gt;
 *         &lt;base&gt;1000&lt;/base&gt;
 *         &lt;logarithmic&gt;false&lt;/logarithmic&gt;
 *         &lt;colors&gt;
 *             &lt;canvas&gt;#FFFFFF&lt;/canvas&gt;
 *             &lt;back&gt;#FFFFFF&lt;/back&gt;
 *             &lt;shadea&gt;#AABBCC&lt;/shadea&gt;
 *             &lt;shadeb&gt;#DDDDDD&lt;/shadeb&gt;
 *             &lt;grid&gt;#FF0000&lt;/grid&gt;
 *             &lt;mgrid&gt;#00FF00&lt;/mgrid&gt;
 *             &lt;font&gt;#FFFFFF&lt;/font&gt;
 *             &lt;frame&gt;#EE00FF&lt;/frame&gt;
 *             &lt;arrow&gt;#FF0000&lt;/arrow&gt;
 *         &lt;/colors&gt;
 *         &lt;no_legend&gt;false&lt;/no_legend&gt;
 *         &lt;only_graph&gt;false&lt;/only_graph&gt;
 *         &lt;force_rules_legend&gt;false&lt;/force_rules_legend&gt;
 *         &lt;title&gt;This is a title&lt;/title&gt;
 *         &lt;step&gt;300&lt;/step&gt;
 *         &lt;fonts&gt;
 *             &lt;small_font&gt;
 *                 &lt;name&gt;Courier&lt;/name&gt;
 *                 &lt;style&gt;bold italic&lt;/style&gt;
 *                 &lt;size&gt;12&lt;/size&gt;
 *             &lt;/small_font&gt;
 *             &lt;large_font&gt;
 *                 &lt;name&gt;Courier&lt;/name&gt;
 *                 &lt;style&gt;plain&lt;/style&gt;
 *                 &lt;size&gt;11&lt;/size&gt;
 *             &lt;/large_font&gt;
 *         &lt;/fonts&gt;
 *         &lt;first_day_of_week&gt;SUNDAY&lt;/first_day_of_week&gt;
 *     &lt;/options&gt;
 *     &lt;datasources&gt;
 *         &lt;def&gt;
 *             &lt;name&gt;x&lt;/name&gt;
 *             &lt;rrd&gt;test.rrd&lt;/rrd&gt;
 *             &lt;source&gt;sun&lt;/source&gt;
 *             &lt;cf&gt;AVERAGE&lt;/cf&gt;
 *             &lt;backend&gt;FILE&lt;/backend&gt;
 *         &lt;/def&gt;
 *         &lt;def&gt;
 *             &lt;name&gt;y&lt;/name&gt;
 *             &lt;rrd&gt;test.rrd&lt;/rrd&gt;
 *             &lt;source&gt;shade&lt;/source&gt;
 *             &lt;cf&gt;AVERAGE&lt;/cf&gt;
 *         &lt;/def&gt;
 *         &lt;cdef&gt;
 *             &lt;name&gt;x_plus_y&lt;/name&gt;
 *             &lt;rpn&gt;x,y,+&lt;/rpn&gt;
 *         &lt;/cdef&gt;
 *         &lt;cdef&gt;
 *             &lt;name&gt;x_minus_y&lt;/name&gt;
 *             &lt;rpn&gt;x,y,-&lt;/rpn&gt;
 *         &lt;/cdef&gt;
 *         &lt;sdef&gt;
 *             &lt;name&gt;x_avg&lt;/name&gt;
 *             &lt;source&gt;x&lt;/source&gt;
 *             &lt;cf&gt;AVERAGE&lt;/cf&gt;
 *         &lt;/sdef&gt;
 *         &lt;sdef&gt;
 *             &lt;name&gt;y_max&lt;/name&gt;
 *             &lt;source&gt;y&lt;/source&gt;
 *             &lt;cf&gt;MAX&lt;/cf&gt;
 *         &lt;/sdef&gt;
 *     &lt;/datasources&gt;
 *     &lt;graph&gt;
 *         &lt;area&gt;
 *             &lt;datasource&gt;x&lt;/datasource&gt;
 *             &lt;color&gt;#FF0000&lt;/color&gt;
 *             &lt;legend&gt;X value\r&lt;/legend&gt;
 *         &lt;/area&gt;
 *         &lt;stack&gt;
 *             &lt;datasource&gt;y&lt;/datasource&gt;
 *             &lt;color&gt;#00FF00&lt;/color&gt;
 *             &lt;legend&gt;Y value\r&lt;/legend&gt;
 *         &lt;/stack&gt;
 *         &lt;line&gt;
 *             &lt;datasource&gt;x&lt;/datasource&gt;
 *             &lt;color&gt;#FF0000&lt;/color&gt;
 *             &lt;legend&gt;X value\r&lt;/legend&gt;
 *             &lt;width&gt;2&lt;/width&gt;
 *         &lt;/line&gt;
 *         &lt;print&gt;
 *             &lt;datasource&gt;x&lt;/datasource&gt;
 *             &lt;cf&gt;AVERAGE&lt;/cf&gt;
 *             &lt;format&gt;Average is %7.3f\c&lt;/format&gt;
 *         &lt;/print&gt;
 *         &lt;gprint&gt;
 *             &lt;datasource&gt;y&lt;/datasource&gt;
 *             &lt;cf&gt;MAX&lt;/cf&gt;
 *             &lt;format&gt;Max is %7.3f\c&lt;/format&gt;
 *         &lt;/gprint&gt;
 *         &lt;hrule&gt;
 *             &lt;value&gt;1250&lt;/value&gt;
 *             &lt;color&gt;#0000FF&lt;/color&gt;
 *             &lt;legend&gt;This is a horizontal rule&lt;/legend&gt;
 *         &lt;/hrule&gt;
 *         &lt;vrule&gt;
 *             &lt;time&gt;now-6h&lt;/time&gt;
 *             &lt;color&gt;#0000FF&lt;/color&gt;
 *             &lt;legend&gt;This is a vertical rule&lt;/legend&gt;
 *         &lt;/vrule&gt;
 *         &lt;comment&gt;Simple comment&lt;/comment&gt;
 *         &lt;comment&gt;One more comment\c&lt;/comment&gt;
 *     &lt;/graph&gt;
 * &lt;/rrd_graph_def&gt;
 * </pre>
 * Notes on the template syntax:<p>
 * <ul>
 * <li>There is a strong relation between the XML template syntax and the syntax of
 * {@link RrdGraphDef} class methods. If you are not sure what some XML tag means, check javadoc
 * for the corresponding class method.
 * <li>hard-coded timestamps in templates should be long integeres
 * (like: 1000243567) or at-style formatted strings
 * <li>whitespaces are not harmful
 * <li>use <code>true</code>, <code>on</code>, <code>yes</code>, <code>y</code>,
 * or <code>1</code> to specify boolean <code>true</code> value (anything else will
 * be treated as <code>false</code>).
 * <li>floating point values: anything that cannot be parsed will be treated as Double.NaN
 * (like: U, unknown, 12r.23)
 * <li>use #RRGGBB or #RRGGBBAA format to specify colors.
 * <li>valid font styles are: PLAIN, ITALIC, BOLD, BOLDITALIC
 * <li>comments are allowed.
 * </ul>
 * Any template value (text between <code>&lt;some_tag&gt;</code> and
 * <code>&lt;/some_tag&gt;</code>) can be replaced with
 * a variable of the following form: <code>${variable_name}</code>. Use
 * {@link XmlTemplate#setVariable(String, String) setVariable()}
 * methods from the base class to replace
 * template variables with real values at runtime.<p>
 * <p/>
 * Typical usage scenario:<p>
 * <ul>
 * <li>Create your XML template and save it to a file (template.xml, for example)
 * <li>Replace template values with variables if you want to change them during runtime.
 * For example, time span should not be hard-coded in the template - you probably want to create
 * many different graphs with different time spans from the same XML template.
 * For example, your XML template could start with:
 * <pre>
 * &lt;rrd_graph_def&gt;
 *     ...
 *     &lt;span&gt;
 *         &lt;start&gt;${start}&lt;/start&gt;
 *         &lt;end&gt;${end}&lt;/end&gt;
 *     &lt;/span&gt;
 *     ...
 * </pre>
 * <li>In your Java code, create RrdGraphDefTemplate object using your XML template file:
 * <pre>
 * RrdGraphDefTemplate t = new RrdGraphDefTemplate(new File(template.xml));
 * </pre>
 * <li>Then, specify real values for template variables:
 * <pre>
 * t.setVariable("start", new GregorianCalendar(2004, 2, 25));
 * t.setVariable("end", new GregorianCalendar(2004, 2, 26));
 * </pre>
 * <li>Once all template variables are set, just use the template object to create RrdGraphDef
 * object. This object is actually used to create JRobin grahps:
 * <pre>
 * RrdGraphDef gdef = t.getRrdGraphDef();
 * RrdGraph g = new RrdGraph(gdef);
 * </pre>
 * </ul>
 * You should create new RrdGraphDefTemplate object only once for each XML template. Single template
 * object can be reused to create as many RrdGraphDef objects as needed, with different values
 * specified for template variables. XML synatax check is performed only once - the first graph
 * definition object gets created relatively slowly, but it will be created much faster next time.
 */
public class RrdGraphDefTemplate extends XmlTemplate implements RrdGraphConstants {
	static final Color BLIND_COLOR = new Color(0, 0, 0, 0);

	private RrdGraphDef rrdGraphDef;

	/**
	 * Creates template object from any parsable XML source
	 *
	 * @param inputSource XML source
	 * @throws IOException  thrown in case of I/O error
	 * @throws RrdException usually thrown in case of XML related error
	 */
	public RrdGraphDefTemplate(InputSource inputSource) throws IOException, RrdException {
		super(inputSource);
	}

	/**
	 * Creates template object from the file containing XML template code
	 *
	 * @param xmlFile file containing XML template
	 * @throws IOException  thrown in case of I/O error
	 * @throws RrdException usually thrown in case of XML related error
	 */
	public RrdGraphDefTemplate(File xmlFile) throws IOException, RrdException {
		super(xmlFile);
	}

	/**
	 * Creates template object from the string containing XML template code
	 *
	 * @param xmlString string containing XML template
	 * @throws IOException  thrown in case of I/O error
	 * @throws RrdException usually thrown in case of XML related error
	 */
	public RrdGraphDefTemplate(String xmlString) throws IOException, RrdException {
		super(xmlString);
	}

	/**
	 * Creates RrdGraphDef object which can be used to create RrdGraph
	 * object (actual JRobin graphs). Before this method is called, all template variables (if any)
	 * must be resolved (replaced with real values).
	 * See {@link XmlTemplate#setVariable(String, String) setVariable()} method information to
	 * understand how to supply values for template variables.
	 *
	 * @return Graph definition which can be used to create RrdGraph object (actual JRobin graphs)
	 * @throws RrdException Thrown if parsed XML template contains invalid (unrecognized) tags
	 */
	public RrdGraphDef getRrdGraphDef() throws RrdException {
		// basic check
		if (!root.getTagName().equals("rrd_graph_def")) {
			throw new RrdException("XML definition must start with <rrd_graph_def>");
		}
		validateTagsOnlyOnce(root, new String[] {"filename", "span", "options", "datasources", "graph"});
		rrdGraphDef = new RrdGraphDef();
		// traverse all nodes
		Node[] childNodes = getChildNodes(root);
		for (Node childNode : childNodes) {
			String nodeName = childNode.getNodeName();