## org.jrobin.graph
Class RrdGraphDefTemplate

    java.lang.Object
      org.jrobin.core.XmlTemplate
          org.jrobin.graph.RrdGraphDefTemplate

public class RrdGraphDefTemplate
extends XmlTemplate

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.

Here is an example of a properly formatted XML template with all available options in it (unwanted options can be removed):

     <rrd_graph_def>
         <span>
             <!-- ISO FORMAT: yyyy-MM-dd HH:mm:ss -->
             <start>2004-02-27 13:35:00</start>
             <!-- timestamp in seconds is also allowed -->
             <end>1234567890</end>
         </span>
         <options>
             <anti_aliasing>true</anti_aliasing>
             <arrow_color>#FF0000</arrow_color>
             <axis_color>#00FF00</axis_color>
             <back_color>#00FF00</back_color>
             <background>#FFFFFF</background>
             <base_value>1024</base_value>
             <canvas>#112211</canvas>
             <left_padding>55</left_padding>
             <default_font>
                 <name>Times</name>
                 <style>BOLD ITALIC</style>
                 <size>15</size>
             </default_font>
             <default_font_color>#000000</default_font_color>
             <frame_color>#0000FF</frame_color>
             <front_grid>true</front_grid>
             <grid_range>
                 <lower>100</lower>
                 <upper>200</upper>
                 <rigid>false</rigid>
             </grid_range>
             <grid_x>true</grid_x>
             <grid_y>false</grid_y>
             <border>
                 <color>#00FFFF</color>
                 <width>2</width>
             </border>
             <major_grid_color>#00FF00</major_grid_color>
             <major_grid_x>true</major_grid_x>
             <major_grid_y>false</major_grid_y>
             <minor_grid_color>#00FFFF</minor_grid_color>
             <minor_grid_x>true</minor_grid_x>
             <minor_grid_y>false</minor_grid_y>
             <overlay>overlay_image.png</overlay>
             <show_legend>true</show_legend>
             <show_signature>false</show_signature>
             <time_axis>
                 <!-- ALLOWED TIME UNITS: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR -->
                 <min_grid_time_unit>HOUR</min_grid_time_unit>
                 <min_grid_unit_steps>4</min_grid_unit_steps>
                 <maj_grid_time_unit>DAY</maj_grid_time_unit>
                 <maj_grid_unit_steps>2</maj_grid_unit_steps>
                 <date_format>HH:mm</date_format>
                 <center_labels>true</center_labels>
                 <!-- ALLOWED DAYS OF WEEK: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY -->
                 <first_day_of_week>MONDAY</first_day_of_week>
             </time_axis>
             <time_axis_label>time</time_axis_label>
             <title>Graph title</title>
             <title_font>
                 <name>Verdana</name>
                 <style>BOLD</style>
                 <size>17</size>
             </title_font>
             <title_font_color>#FF0000</title_font_color>
             <units_exponent>6</units_exponent>
             <value_axis>
                 <grid_step>100</grid_step>
                 <label_step>200</label_step>
             </value_axis>
             <vertical_label>voltage [V]</vertical_label>
         </options>
         <datasources>
             <def>
                 <name>input</name>
                 <rrd>test1.rrd</rrd>
                 <source>inOctets</source>
                 <cf>AVERAGE</cf>
             </def>
             <def>
                 <name>output</name>
                 <rrd>test2.rrd</rrd>
                 <source>outOctets</source>
                 <cf>MAX</cf>
                 <backend>FILE</backend>
             </def>
             <def>
                 <name>input8</name>
                 <rpn>input,8,*</rpn>
             </def>
             <def>
                 <name>output8</name>
                 <rpn>output,8,*,-1,*</rpn>
             </def>
             <def>
                 <name>avgOutput8</name>
                 <datasource>output8</datasource>
                 <cf>AVERAGE</cf>
             </def>
             <export_data>
                 <file>exportdata1.xml</file>
                 <ds_name_prefix>traffic</ds_name_prefix>
             </export_data>
             <export_data>
                 <file>exportdata2.xml</file>
                 <use_legend_names>true</use_legend_names>
             </export_data>
             <export_data>
                 <file>exportdata3.xml</file>
             </export_data>
         </datasources>
         <graph>
             <area>
                 <datasource>input</datasource>
                 <color>#FF0000</color>
                 <legend>Input traffic</legend>
             </area>
             <area>
                 <datasource>output</datasource>
                 <color>#00FF00</color>
                 <legend>Output traffic</legend>
             </area>
             <stack>
                 <datasource>input8</datasource>
                 <color>#AA00AA</color>
                 <legend>Stacked input@r</legend>
             </stack>
             <line>
                 <datasource>input</datasource>
                 <color>#AB7777</color>
                 <legend>Input traffic@l</legend>
             </line>
             <line>
                 <datasource>output</datasource>
                 <color>#AA00AA</color>
                 <legend>Output traffic@r</legend>
                 <width>2</width>
             </line>
             <area>
                 <time1>2004-02-25 12:00:01</time1>
                 <time2>1000222333</time2>
                 <value1>1001.23</value1>
                 <value2>2765.45</value2>
                 <color>#AABBCC</color>
                 <legend>simeple two point area</legend>
             </area>
             <line>
                 <time1>1000111444</time1>
                 <time2>2004-02-25 12:00:01</time2>
                 <value1>1009.23</value1>
                 <value2>9002.45</value2>
                 <color>#AABB33</color>
                 <legend>simple two point line</legend>
                 <width>5</width>
             </line>
             <gprint>
                 <datasource>input</datasource>
                 <cf>AVERAGE</cf>
                 <format>Average input: @2@c</format>
             </gprint>
             <gprint>
                 <datasource>output</datasource>
                 <cf>TOTAL</cf>
                 <format>total output: @2@r</format>
                 <-- optional base value -->
                 <base>1024</base>
             </gprint>
             <hrule>
                 <value>1234.5678</value>
                 <color>#112233</color>
                 <legend>horizontal rule</legend>
                 <width>3</width>
             </hrule>
             <vrule>
                 <time>2004-02-22 17:43:57</time>
                 <color>#112299</color>
                 <legend>vertical rule</legend>
                 <width>6</width>
             </vrule>
             <time>
                 <format>Current time: @t</format>
                 <pattern>MMM dd, yyyy   HH:mm:ss</pattern>
             </time>
             <time>
                 <format>Month: @t</format>
                 <pattern>MMMM yyyy</pattern>
                 <value>2004-01-01 12:00:00</value>
             </time>
             <comment>Created with JRobin</comment>
         </graph>
     </rrd_graph_def>

Notes on the template syntax:

- There is a strong relation between the XML template syntax and the syntax of `RrdGraphDef` class methods. If you are not sure what some XML tag means, check javadoc for the corresponding class.
- hard-coded timestamps in templates should be long integeres (like: 1000243567) or ISO formatted strings (like: 2004-02-21 12:25:45)
- whitespaces are not harmful, however, whitespaces do get special treatment in case of printed text: it is not necessary to use CDATA blocks to specify fixed whitespace with `comment`,`title`, `time`, `gprint` or `legend` tags
- use `true`, `on`, `yes`, `y`, or `1` to specify boolean `true` value (anything else will be treated as `false`).
- floating point values: anything that cannot be parsed will be treated as Double.NaN (like: U, unknown, 12r.23)
- use #RRGGBB format to specify colors.
- valid font styles are: PLAIN, ITALIC, BOLD, BOLD ITALIC
- 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 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:

       <rrd_graph_def>
           <span>
               <start>${start}</start>
               <end>${end}</end>
           </span>
           ...

- In your Java code, create RrdGraphDefTemplate object using your XML template file:

       RrdGraphDefTemplate t = new RrdGraphDefTemplate(new File(template.xml));

- Then, specify real values for template variables:

       t.setVariable("start", new GregorianCalendar(2004, 2, 25));
       t.setVariable("end", new GregorianCalendar(2004, 2, 26));

- Once all template variables are set, just use the template object to create RrdGraphDef object. This object is actually used to create JRobin grahps:

       RrdGraphDef gdef = t.getRrdGraphDef();
       RrdGraph g = new RrdGraph(gdef);
       g.saveAsPNG("graph.png");

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.

Field Summary

Fields inherited from class org.jrobin.core.XmlTemplate
`root`

Constructor Summary
`RrdGraphDefTemplate(java.io.File xmlFile)` Creates template object from the file containing XML template code
`RrdGraphDefTemplate(org.xml.sax.InputSource inputSource)` Creates template object from any parsable XML source
`RrdGraphDefTemplate(java.lang.String xmlString)` Creates template object from the string containing XML template code

Method Summary
`RrdGraphDef` `getRrdGraphDef()` Creates RrdGraphDef object which can be used to create RrdGraph object (actual JRobin graphs).

Methods inherited from class org.jrobin.core.XmlTemplate

`clearValues, getChildNodes, getChildNodes, getChildValue, getChildValue, getChildValueAsBoolean, getChildValueAsDouble, getChildValueAsInt, getChildValueAsLong, getFirstChildNode, getValue, getValue, getValueAsBoolean, 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

### RrdGraphDefTemplate

    public RrdGraphDefTemplate(org.xml.sax.InputSource inputSource)
                        throws java.io.IOException,
                               RrdException

  Creates template object from any parsable XML source

Parameters:
  `inputSource` - XML source
Throws:
  `java.io.IOException` - thrown in case of I/O error
  `RrdException` - usually thrown in case of XML related error

### RrdGraphDefTemplate

    public RrdGraphDefTemplate(java.io.File xmlFile)
                        throws java.io.IOException,
                               RrdException

  Creates template object from the file containing XML template code

Parameters:
  `xmlFile` - file containing XML template
Throws:
  `java.io.IOException` - thrown in case of I/O error
  `RrdException` - usually thrown in case of XML related error

### RrdGraphDefTemplate

    public RrdGraphDefTemplate(java.lang.String xmlString)
                        throws java.io.IOException,
                               RrdException

  Creates template object from the string containing XML template code

Parameters:
  `xmlString` - string containing XML template
Throws:
  `java.io.IOException` - thrown in case of I/O error
  `RrdException` - usually thrown in case of XML related error

Method Detail

### getRrdGraphDef

    public RrdGraphDef getRrdGraphDef()
                               throws RrdException

  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 `setVariable()` method information to understand how to supply values for template variables.

  Returns:
    Graph definition which can be used to create RrdGraph object (actual JRobin graphs)
  Throws:
    `RrdException` - Thrown if parsed XML template contains invalid (unrecognized) tags