Class used to create an arbitrary number of
RrdDef (RRD definition) objects
from a single XML template. XML template can be supplied as an XML InputSource,
XML file or XML formatted string.
Here is an example of a properly formatted XML template with all available
options in it (unwanted options can be removed):
<rrd_def>
<path>test.rrd</path>
<!-- not mandatory -->
<start>1000123456</start>
<!-- not mandatory -->
<step>300</step>
<!-- at least one datasource must be supplied -->
<datasource>
<name>input</name>
<type>COUNTER</type>
<heartbeat>300</heartbeat>
<min>0</min>
<max>U</max>
</datasource>
<datasource>
<name>temperature</name>
<type>GAUGE</type>
<heartbeat>400</heartbeat>
<min>U</min>
<max>1000</max>
</datasource>
<!-- at least one archive must be supplied -->
<archive>
<cf>AVERAGE</cf>
<xff>0.5</xff>
<steps>1</steps>
<rows>600</rows>
</archive>
<archive>
<cf>MAX</cf>
<xff>0.6</xff>
<steps>6</steps>
<rows>7000</rows>
</archive>
</rrd_def>
Notes on the template syntax:
- There is a strong relation between the XML template syntax and the syntax of
RrdDef class methods. If you are not sure what some XML tag means, check javadoc
for the corresponding class.
- starting timestamp can be supplied either as a long integer
(like: 1000243567) or as an ISO formatted string (like: 2004-02-21 12:25:45)
- whitespaces are not harmful
- floating point values: anything that cannot be parsed will be treated as Double.NaN
(like: U, unknown, 12r.23)
- comments are allowed.
Any template value (text between
<some_tag>
and
</some_tag>
) can be replaced with
a variable of the following form:
${variable_name}
. Use
XmlTemplate#setVariable(String,String)methods from the base class to replace template variables with real values
at runtime.
Typical usage scenario:
- Create your XML template and save it to a file (template.xml, for example)
- Replace hardcoded template values with variables if you want to change them during runtime.
For example, RRD path should not be hardcoded in the template - you probably want to create
many different RRD files from the same XML template. For example, your XML
template could start with:
<rrd_def>
<path>${path}</path>
<step>300</step>
...
- In your Java code, create RrdDefTemplate object using your XML template file:
RrdDefTemplate t = new RrdDefTemplate(new File(template.xml));
- Then, specify real values for template variables:
t.setVariable("path", "demo/test.rrd");
- Once all template variables are set, just use the template object to create RrdDef
object. This object is actually used to create Rrd4j RRD files:
RrdDef def = t.getRrdDef();
RrdDb rrd = new RrdDb(def);
rrd.close();
You should create new RrdDefTemplate object only once for each XML template. Single template
object can be reused to create as many RrdDef objects as needed, with different values
specified for template variables. XML synatax check is performed only once - the first
definition object gets created relatively slowly, but it will be created much faster next time.