RrdDefTemplate


1   /* ============================================================
2    * JRobin : Pure java implementation of RRDTool's functionality
3    * ============================================================
4    *
5    * Project Info:  http://www.jrobin.org
6    * Project Lead:  Sasa Markovic (saxon@jrobin.org);
7    *
8    * (C) Copyright 2003, by Sasa Markovic.
9    *
10   * Developers:    Sasa Markovic (saxon@jrobin.org)
11   *                Arne Vandamme (cobralord@jrobin.org)
12   *
13   * This library is free software; you can redistribute it and/or modify it under the terms
14   * of the GNU Lesser General Public License as published by the Free Software Foundation;
15   * either version 2.1 of the License, or (at your option) any later version.
16   *
17   * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
18   * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
19   * See the GNU Lesser General Public License for more details.
20   *
21   * You should have received a copy of the GNU Lesser General Public License along with this
22   * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
23   * Boston, MA 02111-1307, USA.
24   */
25  package org.jrobin.core;
26  
27  import org.xml.sax.InputSource  ;
28  import org.w3c.dom.Node  ;
29  
30  import java.io.IOException  ;
31  import java.io.File  ;
32  import java.util.GregorianCalendar  ;
33  
34  /**
35   * Class used to create an arbitrary number of {@link RrdDef} (RRD definition) objects
36   * from a single XML template. XML template can be supplied as an XML InputSource,
37   * XML file or XML formatted string.<p>
38   *
39   * Here is an example of a properly formatted XML template with all available
40   * options in it (unwanted options can be removed):<p>
41   * <pre>
42   * &lt;rrd_def&gt;
43   *     &lt;path&gt;test.rrd&lt;/path&gt;
44   *     &lt;!-- not mandatory --&gt;
45   *     &lt;start&gt;1000123456&lt;/start&gt;
46   *     &lt;!-- not mandatory --&gt;
47   *     &lt;step&gt;300&lt;/step&gt;
48   *     &lt;!-- at least one datasource must be supplied --&gt;
49   *     &lt;datasource&gt;
50   *         &lt;name&gt;input&lt;/name&gt;
51   *         &lt;type&gt;COUNTER&lt;/type&gt;
52   *         &lt;heartbeat&gt;300&lt;/heartbeat&gt;
53   *         &lt;min&gt;0&lt;/min&gt;
54   *         &lt;max&gt;U&lt;/max&gt;
55   *     &lt;/datasource&gt;
56   *     &lt;datasource&gt;
57   *         &lt;name&gt;temperature&lt;/name&gt;
58   *         &lt;type&gt;GAUGE&lt;/type&gt;
59   *         &lt;heartbeat&gt;400&lt;/heartbeat&gt;
60   *         &lt;min&gt;U&lt;/min&gt;
61   *         &lt;max&gt;1000&lt;/max&gt;
62   *     &lt;/datasource&gt;
63   *     &lt;!-- at least one archive must be supplied --&gt;
64   *     &lt;archive&gt;
65   *         &lt;cf&gt;AVERAGE&lt;/cf&gt;
66   *         &lt;xff&gt;0.5&lt;/xff&gt;
67   *         &lt;steps&gt;1&lt;/steps&gt;
68   *         &lt;rows&gt;600&lt;/rows&gt;
69   *     &lt;/archive&gt;
70   *     &lt;archive&gt;
71   *         &lt;cf&gt;MAX&lt;/cf&gt;
72   *         &lt;xff&gt;0.6&lt;/xff&gt;
73   *         &lt;steps&gt;6&lt;/steps&gt;
74   *         &lt;rows&gt;7000&lt;/rows&gt;
75   *     &lt;/archive&gt;
76   * &lt;/rrd_def&gt;
77   * </pre>
78   * Notes on the template syntax:<p>
79   * <ul>
80   * <li>There is a strong relation between the XML template syntax and the syntax of
81   * {@link RrdDef} class methods. If you are not sure what some XML tag means, check javadoc
82   * for the corresponding class.
83   * <li>starting timestamp can be supplied either as a long integer
84   * (like: 1000243567) or as an ISO formatted string (like: 2004-02-21 12:25:45)
85   * <li>whitespaces are not harmful
86   * <li>floating point values: anything that cannot be parsed will be treated as Double.NaN
87   * (like: U, unknown, 12r.23)
88   * <li>comments are allowed.
89   * </ul>
90   * Any template value (text between <code>&lt;some_tag&gt;</code> and
91   * <code>&lt;/some_tag&gt;</code>) can be replaced with
92   * a variable of the following form: <code>${variable_name}</code>. Use
93   * {@link XmlTemplate#setVariable(String, String) setVariable()}
94   * methods from the base class to replace template variables with real values
95   * at runtime.<p>
96   *
97   * Typical usage scenario:<p>
98   * <ul>
99   * <li>Create your XML template and save it to a file (template.xml, for example)
100  * <li>Replace hardcoded template values with variables if you want to change them during runtime.
101  * For example, RRD path should not be hardcoded in the template - you probably want to create
102  * many different RRD files from the same XML template. For example, your XML
103  * template could start with:
104  * <pre>
105  * &lt;rrd_def&gt;
106  *     &lt;path&gt;${path}&lt;/path&gt;
107  *     &lt;step&gt;300&lt;/step&gt;
108  *     ...
109  * </pre>
110  * <li>In your Java code, create RrdDefTemplate object using your XML template file:
111  * <pre>
112  * RrdDefTemplate t = new RrdDefTemplate(new File(template.xml));
113  * </pre>
114  * <li>Then, specify real values for template variables:
115  * <pre>
116  * t.setVariable("path", "demo/test.rrd");
117  * </pre>
118  * <li>Once all template variables are set, just use the template object to create RrdDef
119  * object. This object is actually used to create JRobin RRD files:
120  * <pre>
121  * RrdDef def = t.getRrdDef();
122  * RrdDb rrd = new RrdDb(def);
123  * rrd.close();
124  * </pre>
125  * </ul>
126  * You should create new RrdDefTemplate object only once for each XML template. Single template
127  * object can be reused to create as many RrdDef objects as needed, with different values
128  * specified for template variables. XML synatax check is performed only once - the first
129  * definition object gets created relatively slowly, but it will be created much faster next time.
130  */
131 public class RrdDefTemplate extends XmlTemplate {
132     /**
133      * Creates RrdDefTemplate object from any parsable XML input source. Read general information
134      * for this class to find an example of a properly formatted RrdDef XML source.
135      * @param xmlInputSource Xml input source
136      * @throws IOException Thrown in case of I/O error
137      * @throws RrdException Thrown in case of XML related error (parsing error, for example)
138      */
139     public RrdDefTemplate(InputSource   xmlInputSource) throws IOException  , RrdException {
140         super(xmlInputSource);
141     }
142 
143     /**
144      * Creates RrdDefTemplate object from the string containing XML template.
145      * Read general information for this class to see an example of a properly formatted XML source.
146      * @param xmlString String containing XML template
147      * @throws IOException Thrown in case of I/O error
148      * @throws RrdException Thrown in case of XML related error (parsing error, for example)
149      */
150     public RrdDefTemplate(String   xmlString) throws IOException  , RrdException {
151         super(xmlString);
152     }
153 
154     /**
155      * Creates RrdDefTemplate object from the file containing XML template.
156      * Read general information for this class to see an example of a properly formatted XML source.
157      * @param xmlFile File object representing file with XML template
158      * @throws IOException Thrown in case of I/O error
159      * @throws RrdException Thrown in case of XML related error (parsing error, for example)
160      */
161     public RrdDefTemplate(File   xmlFile) throws IOException  , RrdException {
162         super(xmlFile);
163     }
164 
165     /**
166      * Returns RrdDef object constructed from the underlying XML template. Before this method
167      * is called, values for all non-optional placeholders must be supplied. To specify
168      * placeholder values at runtime, use some of the overloaded
169      * {@link XmlTemplate#setVariable(String, String) setVariable()} methods. Once this method
170      * returns, all placeholder values are preserved. To remove them all, call inhereted
171      * {@link XmlTemplate#clearValues() clearValues()} method explicitly.<p>
172      *
173      * @return RrdDef object constructed from the underlying XML template,
174      * with all placeholders replaced with real values. This object can be passed to the constructor
175      * of the new RrdDb object.
176      * @throws RrdException Thrown (in most cases) if the value for some placeholder
177      * was not supplied through {@link XmlTemplate#setVariable(String, String) setVariable()}
178      * method call
179      */
180     public RrdDef getRrdDef() throws RrdException {
181         if (!root.getTagName().equals("rrd_def")) {
182             throw new RrdException("XML definition must start with <rrd_def>");
183         }
184         validateTagsOnlyOnce(root, new String  [] {
185             "path", "start", "step", "datasource*", "archive*"
186         });
187         // PATH must be supplied or exception is thrown
188         String   path = getChildValue(root, "path");
189         RrdDef rrdDef = new RrdDef(path);
190         try {
191             String   startStr = getChildValue(root, "start");
192             GregorianCalendar   startGc = Util.getGregorianCalendar(startStr);
193             rrdDef.setStartTime(startGc);
194         } catch (RrdException e) {
195             // START is not mandatory
196         }
197         try {
198             long step = getChildValueAsLong(root, "step");
199             rrdDef.setStep(step);
200         } catch (RrdException e) {
201             // STEP is not mandatory
202         }
203         // datsources
204         Node  [] dsNodes = getChildNodes(root, "datasource");
205         for (int i = 0; i < dsNodes.length; i++) {
206             validateTagsOnlyOnce(dsNodes[i], new String  [] {
207                 "name", "type", "heartbeat", "min", "max"
208             });
209             String   name = getChildValue(dsNodes[i], "name");
210             String   type = getChildValue(dsNodes[i], "type");
211             long heartbeat = getChildValueAsLong(dsNodes[i], "heartbeat");
212             double min = getChildValueAsDouble(dsNodes[i], "min");
213             double max = getChildValueAsDouble(dsNodes[i], "max");
214             rrdDef.addDatasource(name, type, heartbeat, min, max);
215         }
216         // archives
217         Node  [] arcNodes = getChildNodes(root, "archive");
218         for (int i = 0; i < arcNodes.length; i++) {
219             validateTagsOnlyOnce(arcNodes[i], new String  [] {
220                 "cf", "xff", "steps", "rows"
221             });
222             String   consolFun = getChildValue(arcNodes[i], "cf");
223             double xff = getChildValueAsDouble(arcNodes[i], "xff");
224             int steps = getChildValueAsInt(arcNodes[i], "steps");
225             int rows = getChildValueAsInt(arcNodes[i], "rows");
226             rrdDef.addArchive(consolFun, xff, steps, rows);
227         }
228         return rrdDef;
229     }
230 }
231
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags