org.rrd4j.core

## Class RrdDefTemplate

- java.lang.Object
- - org.rrd4j.core.XmlTemplate
  - - org.rrd4j.core.RrdDefTemplate

-     public class RrdDefTemplate
      extends XmlTemplate

  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.
  - the path to the rrd can be specified either as a file path using path element or as an uri using a url tag
  - 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 `setVariable()` 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 syntax check is performed only once - the first definition object gets created relatively slowly, but it will be created much faster next time.

- - ### Field Summary

    - ### Fields inherited from class org.rrd4j.core.XmlTemplate

      `root`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RrdDefTemplate(File xmlFile)` Creates RrdDefTemplate object from the file containing XML template.
    `RrdDefTemplate(InputSource xmlInputSource)` Creates RrdDefTemplate object from any parsable XML input source.
    `RrdDefTemplate(String xmlString)` Creates RrdDefTemplate object from the string containing XML template.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `RrdDef` | `getRrdDef()` Returns RrdDef object constructed from the underlying XML template.

    - ### Methods inherited from class org.rrd4j.core.XmlTemplate

      `clearValues, getChildNodes, getChildNodes, getChildValue, getChildValue, getChildValueAsBoolean, getChildValueAsDouble, getChildValueAsInt, getChildValueAsLong, getFirstChildNode, getValue, getValue, getValueAsBoolean, getValueAsColor, getValueAsDouble, getValueAsInt, getValueAsLong, getVariables, hasChildNode, hasVariables, isEmptyNode, setVariable, setVariable, setVariable, setVariable, setVariable, setVariable, setVariable, setVariable, validateTagsOnlyOnce`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### RrdDefTemplate

          public RrdDefTemplate(File xmlFile)
                         throws IOException

      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.
      Parameters:
        `xmlFile` - File object representing file with XML template
      Throws:
        `IOException` - Thrown in case of I/O error
        `IllegalArgumentException` - Thrown in case of XML related error (parsing error, for example)

    - #### RrdDefTemplate

          public RrdDefTemplate(InputSource xmlInputSource)
                         throws IOException

      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.
      Parameters:
        `xmlInputSource` - Xml input source
      Throws:
        `IOException` - Thrown in case of I/O error
        `IllegalArgumentException` - Thrown in case of XML related error (parsing error, for example)

    - #### RrdDefTemplate

          public RrdDefTemplate(String xmlString)
                         throws IOException

      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.
      Parameters:
        `xmlString` - String containing XML template
      Throws:
        `IOException` - Thrown in case of I/O error
        `IllegalArgumentException` - Thrown in case of XML related error (parsing error, for example)

  - ### Method Detail

    - #### getRrdDef

          public RrdDef getRrdDef()

      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 `setVariable()` methods. Once this method returns, all placeholder values are preserved. To remove them all, call inherited `clearValues()` method explicitly.

      Returns:
        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:
        `IllegalArgumentException` - Thrown (in most cases) if the value for some placeholder was not supplied through `setVariable()` method call