jrobin-commits Mailing List for JRobin (Page 16)

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/jrobin/src/org/jrobin/core
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11576/org/jrobin/core

Added Files:
	RrdDefTemplate.java XmlTemplate.java 
Log Message:
XML templates revisited

--- NEW FILE: RrdDefTemplate.java ---
/* ============================================================
 * JRobin : Pure java implementation of RRDTool's functionality
 * ============================================================
 *
 * Project Info:  http://www.jrobin.org
 * Project Lead:  Sasa Markovic (sa...@jr...);
 *
 * (C) Copyright 2003, by Sasa Markovic.
 *
 * Developers:    Sasa Markovic (sa...@jr...)
 *                Arne Vandamme (cob...@jr...)
 *
 * 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.core;

import org.xml.sax.InputSource;
import org.w3c.dom.Node;

import java.io.IOException;
import java.io.File;

/**
 * Class to represent RrdDef XML template. Use this class to produce similar RRD definitions
 * (RrdDef objects) from the same XML template. Use <code>${placeholder_name}</code> placeholders
 * in the XML source to mark XML code which will be modified (replaced) at run time.<p>
 *
 * Here is a self-explaining example of a valid XML definition:<p>
 *
 * <pre><code>
 * &lt;rrd_def&gt;
 *     &lt;path&gt;${path}&lt;/path&gt;
 *     &lt;!-- not mandatory --&gt;
 *     &lt;start&gt;1000123456&lt;/start&gt;
 *     &lt;!-- not mandatory --&gt;
 *     &lt;step&gt;${step}&lt;/step&gt;
 *     &lt;!-- at least one datasource must be supplied --&gt;
 *     &lt;datasource&gt;
 *         &lt;name&gt;input&lt;/name&gt;
 *         &lt;type&gt;COUNTER&lt;/type&gt;
 *         &lt;heartbeat&gt;300&lt;/heartbeat&gt;
 *         &lt;min&gt;0&lt;/min&gt;
 *         &lt;max&gt;U&lt;/max&gt;
 *     &lt;/datasource&gt;
 *     &lt;datasource&gt;
 *         &lt;name&gt;temperature&lt;/name&gt;
 *         &lt;type&gt;GAUGE&lt;/type&gt;
 *         &lt;heartbeat&gt;400&lt;/heartbeat&gt;
 *         &lt;min&gt;U&lt;/min&gt;
 *         &lt;max&gt;1000&lt;/max&gt;
 *     &lt;/datasource&gt;
 *     &lt;!-- at least one archive must be supplied --&gt;
 *     &lt;archive&gt;
 *         &lt;cf&gt;AVERAGE&lt;/cf&gt;
 *         &lt;xff&gt;0.5&lt;/xff&gt;
 *         &lt;steps&gt;1&lt;/steps&gt;
 *         &lt;rows&gt;${rows}&lt;/rows&gt;
 *     &lt;/archive&gt;
 *     &lt;archive&gt;
 *         &lt;cf&gt;MAX&lt;/cf&gt;
 *         &lt;xff&gt;0.6&lt;/xff&gt;
 *         &lt;steps&gt;6&lt;/steps&gt;
 *         &lt;rows&gt;7000&lt;/rows&gt;
 *     &lt;/archive&gt;
 * &lt;/rrd_def&gt;
 * </code></pre>
 * XML template can be embedded in a String or a file - the class provides constructors in both
 * cases. <p>
 *
 * Note that the above XML definition contains three placeholders (<code>${path}</code>,
 * <code>${step}</code> and <code>${rows}</code>) - these placeholders must be replaced with
 * real values before the RrdDef object is requested by calling {@link #getRrdDef getRrdDef()}
 * method. To replace placeholders with real values at run time use inhereted
 * (and overloaded) public {@link XmlTemplate#setMapping(String, String) setMapping()}
 * methods.<p>
 *
 * You are free to use the same template object to create as many RrdDef objects as needed
 * (probably with different placeholder-value mappings).<p>
 *
 * Here is an example how to create two different RRD files using the template given above:<p>
 *
 * <pre>
 * // 'template.xml' file contains XML template already specified
 * File file = new File("template.xml");
 * RrdDefTemplate t = new RrdDefTemplate(file);
 *
 * // replace ${path} placeholder with the real value (test1.rrd)
 * t.setMapping("path", "test1.rrd");
 *
 * // replace ${step} placeholder with the real value (600)
 * t.setMapping("step", 600);
 *
 * // replace ${rows} placeholder with the real value (800)
 * t.setMapping("rows", 800);
 *
 * // get RrdDef from the template object...
 * RrdDef def = t.getRrdDef();
 *
 * // ...and use it to construct the first RRD file
 * RrdDb rrd = new RrdDb(def); rrd.close();
 *
 * // note that all mappings are still active
 * // change the value for some (or all) placeholders
 * // to construct the second database
 * // with different parameters
 * t.setMapping("path", "test2.rrd");
 * def = t.getRrdDef();
 *
 * // the second RRD file will be also created with step=600, rows=800
 * rrd = new RrdDb(def); rrd.close();
 * </pre>
 */
public class RrdDefTemplate extends XmlTemplate {
	/**
	 * Creates RrdDefTemplate object from any parsable XML input source. Read general information
	 * for this class to find an example of a properly formatted RrdDef XML source.
	 * @param xmlInputSource Xml input source
	 * @throws IOException Thrown in case of I/O error
	 * @throws RrdException Thrown in case of XML related error (parsing error, for example)
	 */
	public RrdDefTemplate(InputSource xmlInputSource) throws IOException, RrdException {
		super(xmlInputSource);
	}

	/**
	 * Creates RrdDefTemplate object from the string containing XML template.
	 * Read general information for this class to see an example of a properly formatted XML source.
	 * @param xmlString String containing XML template
	 * @throws IOException Thrown in case of I/O error
	 * @throws RrdException Thrown in case of XML related error (parsing error, for example)
	 */
	public RrdDefTemplate(String xmlString) throws IOException, RrdException {
		super(xmlString);
	}

    /**
	 * Creates RrdDefTemplate object from the file containing XML template.
	 * Read general information for this class to see an example of a properly formatted XML source.
	 * @param xmlFile File object representing file with XML template
	 * @throws IOException Thrown in case of I/O error
	 * @throws RrdException Thrown in case of XML related error (parsing error, for example)
	 */
	public RrdDefTemplate(File xmlFile) throws IOException, RrdException {
		super(xmlFile);
	}

    /**
	 * Returns RrdDef object constructed from the underlying XML template. Before this method
	 * is called, values for all non-optional placeholders must be supplied. To specify
	 * placeholder values at runtime, use some of the overloaded
	 * {@link XmlTemplate#setMapping(String, String) setMapping()} methods. Once this method
	 * returns, all placeholder values are preserved. To remove them all, call inhereted
	 * {@link XmlTemplate#clearValues() clearValues()} method explicitly.<p>
	 *
	 * @return RrdDef object constructed from the underlying XML template,
	 * with all placeholders replaced with real values. This object can be passed to the constructor
	 * of the new RrdDb object.
	 * @throws RrdException Thrown (in most cases) if the value for some placeholder
	 * was not supplied through {@link XmlTemplate#setMapping(String, String) setMapping()}
	 * method call
	 */
	public RrdDef getRrdDef() throws RrdException {
		if (!root.getTagName().equals("rrd_def")) {
			throw new RrdException("XML definition must start with <rrd_def>");
		}
		// PATH must be supplied or exception is thrown
		String path = getChildValue(root, "path");
		RrdDef rrdDef = new RrdDef(path);
		try {
			long start = getChildValueAsLong(root, "start");
			rrdDef.setStartTime(start);
		} catch (RrdException e) {
			// START is not mandatory
		}
		try {
			long step = getChildValueAsLong(root, "step");
			rrdDef.setStep(step);
		} catch (RrdException e) {
			// STEP is not mandatory
		}
		// datsources
		Node[] dsNodes = getChildNodes(root, "datasource");
		for (int i = 0; i < dsNodes.length; i++) {
			String name = getChildValue(dsNodes[i], "name");
			String type = getChildValue(dsNodes[i], "type");
			long heartbeat = getChildValueAsLong(dsNodes[i], "heartbeat");
			double min = getChildValueAsDouble(dsNodes[i], "min");
			double max = getChildValueAsDouble(dsNodes[i], "max");
			rrdDef.addDatasource(name, type, heartbeat, min, max);
		}
		// archives
		Node[] arcNodes = getChildNodes(root, "archive");
		for (int i = 0; i < arcNodes.length; i++) {
			String consolFun = getChildValue(arcNodes[i], "cf");
			double xff = getChildValueAsDouble(arcNodes[i], "xff");
			int steps = getChildValueAsInt(arcNodes[i], "steps");
			int rows = getChildValueAsInt(arcNodes[i], "rows");
			rrdDef.addArchive(consolFun, xff, steps, rows);
		}
		return rrdDef;
	}

/*
	public static void main(String[] args) throws RrdException, IOException {
		String s =
			"<rrd_def>                            " +
			"	<path>${path}</path>              " +
			"	<start>1000000000</start>         " +
			"	<step>${step}</step>              " +
			"	<datasource>                      " +
			"		<name>input</name>            " +
			"		<type>COUNTER</type>          " +
			"		<heartbeat>300</heartbeat>    " +
			"		<min>10</min>                 " +
			"		<max>U</max>                  " +
			"	</datasource>                     " +
			"	<datasource>                      " +
			"		<name>temperature</name>      " +
			"		<type>GAUGE</type>            " +
			"		<heartbeat>400</heartbeat>    " +
			"		<min>U</min>                  " +
			"		<max>1000</max>               " +
			"	</datasource>                     " +
			"	<archive>                         " +
			"		<cf>AVERAGE</cf>              " +
			"		<xff>0.5</xff>                " +
			"		<steps>1</steps>              " +
			"		<rows>${rows}</rows>          " +
			"	</archive>                        " +
			"	<archive>                         " +
			"		<cf>MAX</cf>                  " +
			"		<xff>0.6</xff>                " +
			"		<steps>6</steps>              " +
			"		<rows>7000</rows>             " +
			"	</archive>                        " +
			"</rrd_def>                           ";
		RrdDefTemplate t = new RrdDefTemplate(s);
		// works as well:
		// File f = new File("test.xml");
		// RrdDefTemplate t = new RrdDefTemplate(f);

		t.setMapping("path", "test1.rrd");
		t.setMapping("step", 310);
		t.setMapping("rows", 888);

		RrdDef def = t.getRrdDef();
		System.out.println(def.dump());
		new RrdDb(def).close();

		t.setMapping("path", "test2.rrd");
		t.setMapping("step", 320);
		t.setMapping("rows", 999);
		def = t.getRrdDef();
		System.out.println(def.dump());
		new RrdDb(def).close();
	}
*/

}

--- NEW FILE: XmlTemplate.java ---
/* ============================================================
 * JRobin : Pure java implementation of RRDTool's functionality
 * ============================================================
 *
 * Project Info:  http://www.jrobin.org
 * Project Lead:  Sasa Markovic (sa...@jr...);
 *
 * (C) Copyright 2003, by Sasa Markovic.
 *
 * Developers:    Sasa Markovic (sa...@jr...)
 *                Arne Vandamme (cob...@jr...)
 *
 * 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.core;

import org.w3c.dom.Node;
import org.w3c.dom.Element;
import org.xml.sax.InputSource;

import java.io.IOException;
import java.io.File;
import java.util.HashMap;

/**
 * Class used as a base class for various XML template related classes. Class provides
 * methods for XML source parsing and XML tree traversing. XML source may have unlimited
 * number of placeholders in the format <code>${placeholder_name}</code>. Methods are provided
 * to specify values of placeholders at runtime. Note that this class has limited functionality:
 * XML source gets parsed, and placeholder values are collected. You have to extend this class
 * to do anything more useful.<p>
 */
public abstract class XmlTemplate {
	/**
	 * root element of the DOM hierarchy representing XML source
	 */
	protected Element root;
	private HashMap valueMap = new HashMap();

	/**
	 * Creates XmlTemplate object from any parsable XML input source
	 * @param xmlSource Any parsable XML input source
	 * @throws IOException thrown in case of I/O error
	 * @throws RrdException thrown (in most cases) when the source has invalid XML syntax
	 * (cannot be parsed at all)
	 */
	protected XmlTemplate(InputSource xmlSource) throws IOException, RrdException {
		root = Util.Xml.getRootElement(xmlSource);
	}

    /**
	 * Creates XmlTemplate object from a string containing properly formatted XML
	 * @param xmlString parsable XML string
	 * @throws IOException thrown in case of I/O error
	 * @throws RrdException thrown (in most cases) when the source has invalid XML syntax
	 * (cannot be parsed at all)
	 */
	protected XmlTemplate(String xmlString) throws IOException, RrdException {
		root = Util.Xml.getRootElement(xmlString);
	}

	/**
	 * Creates XmlTemplate object from a file containing properly formatted XML
	 * @param xmlFile File object representing file containing parsable XML source
	 * @throws IOException thrown in case of I/O error
	 * @throws RrdException thrown (in most cases) when the source has invalid XML syntax
	 * (cannot be parsed at all)
	 */
	protected XmlTemplate(File xmlFile) throws IOException, RrdException {
		root = Util.Xml.getRootElement(xmlFile);
	}

	/**
	 * Removes all placeholder-value mappings.
	 */
	public void clearValues() {
		valueMap.clear();
	}

	/**
	 * Sets value for the given placeholder. Placeholder should be supplied by its name.
	 * For example, for a placeholder <code>${param}</code> specify just <code>param</code>
	 * for its name.
	 * @param name Name of the placeholder (placeholder without leading '${' and ending '}').
	 * @param value Value to replace placeholder with.
	 */
	public void setMapping(String name, String value) {
		valueMap.put(name, value);
	}

	/**
	 * Sets value for the given placeholder. Placeholder should be supplied by its name.
	 * For example, for a placeholder <code>${param}</code> specify just <code>param</code>
	 * for its name.
	 * @param name Name of the placeholder (placeholder without leading '${' and ending '}').
	 * @param value Value to replace placeholder with.
	 */
	public void setMapping(String name, int value) {
		valueMap.put(name, new Integer(value));
	}

	/**
	 * Sets value for the given placeholder. Placeholder should be supplied by its name.
	 * For example, for a placeholder <code>${param}</code> specify just <code>param</code>
	 * for its name.
	 * @param name Name of the placeholder (placeholder without leading '${' and ending '}').
	 * @param value Value to replace placeholder with.
	 */
	public void setMapping(String name, long value) {
		valueMap.put(name, new Long(value));
	}

	/**
	 * Sets value for the given placeholder. Placeholder should be supplied by its name.
	 * For example, for a placeholder <code>${param}</code> specify just <code>param</code>
	 * for its name.
	 * @param name Name of the placeholder (placeholder without leading '${' and ending '}').
	 * @param value Value to replace placeholder with.
	 */
	public void setMapping(String name, double value) {
		valueMap.put(name, new Double(value));
	}

	/**
	 * Returns all child nodes with the given tag
	 * belonging to the specified parent Node
	 * @param parentNode Parent node
	 * @param childName Child node tag
	 * @return Array of child nodes with the specified parent and with the given tag name
	 */
	protected static Node[] getChildNodes(Node parentNode, String childName) {
		return Util.Xml.getChildNodes(parentNode, childName);
	}

	/**
	 * Returns the first child node with the given parent and the given tag.
	 * @param parentNode Parent node
	 * @param childName Child node tag
	 * @return First child node with the given parent node and the given tag.
	 * @throws RrdException Thrown if no such child can be found
	 */
	protected static Node getFirstChildNode(Node parentNode, String childName) throws RrdException {
		return Util.Xml.getFirstChildNode(parentNode, childName);
	}

	/**
	 * Returns the 'value' of the child node with the given parent and the given tag name.
	 * For example, in a DOM-tree created from the following XML source:<p>
	 * <pre>
	 * ...&lt;root&gt;&lt;branch&gt;abc&lt;/branch&gt;&lt;/root&gt;...
	 * </pre>
	 * and assuming that <code>parentNode</code> points to the <code>&lt;root&gt;</code> element,
	 * the following call:<p>
	 * <pre>
	 * getChildValue(parentNode, "branch");
	 * </pre>
	 * returns:<p>
	 * <code>abc</code><p>
	 * @param parentNode Parent DOM node
	 * @param childName Child node tag
	 * @return XML 'value' of the child node (trimmed content between <childName> and </childName>
	 * tags)
	 * @throws RrdException Thrown if no such child node exists.
	 */
	protected String getChildValue(Node parentNode, String childName) throws RrdException {
		String value = Util.Xml.getChildValue(parentNode, childName);
		if(value.startsWith("${") && value.endsWith("}")) {
			// template variable found, remove leading "${" and trailing "}"
			String var = value.substring(2, value.length() - 1);
			if(valueMap.containsKey(var)) {
				// mapping found
				value = valueMap.get(var).toString();
			}
			else {
				// no mapping found - this is illegal
				throw new RrdException("No mapping found for template variable " + value);
			}
		}
		return value;
	}

	/**
	 * Returns the 'value' of the child node with the given parent and the given tag name.
	 * For example, in a DOM-tree created from the following XML source:<p>
	 * <pre>
	 * ...&lt;root&gt;&lt;branch&gt;123&lt;/branch&gt;&lt;/root&gt;...
	 * </pre>
	 * and assuming that <code>parentNode</code> points to the <code>&lt;root&gt;</code> element,
	 * the following call:<p>
	 * <pre>
	 * getChildValue(parentNode, "branch");
	 * </pre>
	 * returns:<p>
	 * <code>123</code><p>
	 * @param parentNode Parent DOM node
	 * @param childName Child node tag
	 * @return XML 'value' of the child node (trimmed content between <childName> and </childName>
	 * tags)
	 * @throws RrdException Thrown if no such child node exists.
	 */
	protected int getChildValueAsInt(Node parentNode, String childName)
		throws RrdException, NumberFormatException {
		String valueStr = getChildValue(parentNode, childName);
		return Integer.parseInt(valueStr);
	}

	/**
	 * Returns the 'value' of the child node with the given parent and the given tag name.
	 * For example, in a DOM-tree created from the following XML source:<p>
	 * <pre>
	 * ...&lt;root&gt;&lt;branch&gt;123&lt;/branch&gt;&lt;/root&gt;...
	 * </pre>
	 * and assuming that <code>parentNode</code> points to the <code>&lt;root&gt;</code> element,
	 * the following call:<p>
	 * <pre>
	 * getChildValue(parentNode, "branch");
	 * </pre>
	 * returns:<p>
	 * <code>123</code><p>
	 * @param parentNode Parent DOM node
	 * @param childName Child node tag
	 * @return XML 'value' of the child node (trimmed content between <childName> and </childName>
	 * tags)
	 * @throws RrdException Thrown if no such child node exists.
	 */
	protected long getChildValueAsLong(Node parentNode, String childName)
		throws RrdException, NumberFormatException {
		String valueStr = getChildValue(parentNode, childName);
		return Long.parseLong(valueStr);
	}

	/**
	 * Returns the 'value' of the child node with the given parent and the given tag name.
	 * For example, in a DOM-tree created from the following XML source:<p>
	 * <pre>
	 * ...&lt;root&gt;&lt;branch&gt;123.45&lt;/branch&gt;&lt;/root&gt;...
	 * </pre>
	 * and assuming that <code>parentNode</code> points to the <code>&lt;root&gt;</code> element,
	 * the following call:<p>
	 * <pre>
	 * getChildValue(parentNode, "branch");
	 * </pre>
	 * returns:<p>
	 * <code>123.45</code><p>
	 * @param parentNode Parent DOM node
	 * @param childName Child node tag
	 * @return XML 'value' of the child node (trimmed content between <childName> and </childName>
	 * tags)
	 * @throws RrdException Thrown if no such child node exists.
	 */
	protected double getChildValueAsDouble(Node parentNode, String childName) throws RrdException {
		String valueStr = getChildValue(parentNode, childName);
		return Util.parseDouble(valueStr);
	}
}

2003	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug	Sep (11)	Oct (60)	Nov (68)	Dec (10)
2004	Jan (10)	Feb (15)	Mar (30)	Apr (20)	May (32)	Jun (30)	Jul (61)	Aug (13)	Sep (14)	Oct (13)	Nov (28)	Dec (10)
2005	Jan (7)	Feb (5)	Mar	Apr (2)	May	Jun	Jul	Aug	Sep (4)	Oct	Nov	Dec
2006	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug	Sep	Oct	Nov	Dec (15)
2007	Jan	Feb	Mar	Apr	May	Jun	Jul (20)	Aug (35)	Sep (3)	Oct (2)	Nov	Dec
2008	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug (14)	Sep (2)	Oct	Nov	Dec
2010	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug	Sep	Oct	Nov	Dec (3)
2011	Jan	Feb	Mar	Apr (5)	May	Jun	Jul	Aug	Sep	Oct	Nov	Dec

jrobin-commits Mailing List for JRobin (Page 16)

jrobin-commits — Mailing list for CVS commits