public class

RrdGraphDefTemplate

extends XmlTemplate
implements RrdGraphConstants
java.lang.Object
   ↳ org.rrd4j.core.XmlTemplate
     ↳ org.rrd4j.graph.RrdGraphDefTemplate

Class Overview

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/ignored):

 <rrd_graph_def>
     <!-- use '-' to represent in-memory graph -->
     <filename>test.png</filename>
     <!--
         starting and ending timestamps can be specified by
         using at-style time specification, or by specifying
         exact timestamps since epoch (without milliseconds)
     -->
     <span>
         <start>now - 1d</start>
         <end>now</end>
     </span>
     <options>
         <!--
             specify 'true' if you want to use RrdDbPool while
             creating graph
         -->
         <use_pool>false</use_pool>
         <anti_aliasing>true</anti_aliasing>
         <time_grid>
             <show_grid>true</show_grid>
             <!-- allowed units: second, minute, hour, day, week, month, year -->
             <minor_grid_unit>minute</minor_grid_unit>
             <minor_grid_unit_count>60</minor_grid_unit_count>
             <major_grid_unit>hour</major_grid_unit>
             <major_grid_unit_count>2</major_grid_unit_count>
             <label_unit>hour</label_unit>
             <label_unit_count>2</label_unit_count>
             <label_span>1200</label_span>
             <!-- use SimpleDateFormat or strftime-like format to format labels -->
             <label_format>dd-MMM-yy</label_format>
         </time_grid>
         <value_grid>
             <show_grid>true</show_grid>
             <grid_step>100.0</grid_step>
             <label_factor>5</label_factor>
         </value_grid>
         <no_minor_grid>true</no_minor_grid>
         <alt_y_grid>true</alt_y_grid>
         <alt_y_mrtg>true</alt_y_mrtg>
         <alt_autoscale>true</alt_autoscale>
         <alt_autoscale_max>true</alt_autoscale_max>
         <units_exponent>3</units_exponent>
         <units_length>13</units_length>
         <vertical_label>Speed (kbits/sec)</vertical_label>
         <width>444</width>
         <height>222</height>
         <interlaced>true</interlaced>
         <image_info>filename = %s, width=%d, height=%d</image_info>
         <image_format>png</image_format>
         <image_quality>0.8</image_quality>
         <background_image>luka.png</background_image>
         <overlay_image>luka.png</overlay_image>
         <unit>kilos</unit>
         <lazy>false</lazy>
         <min_value>0</min_value>
         <max_value>5000</max_value>
         <rigid>true</rigid>
         <base>1000</base>
         <logarithmic>false</logarithmic>
         <colors>
             <canvas>#FFFFFF</canvas>
             <back>#FFFFFF</back>
             <shadea>#AABBCC</shadea>
             <shadeb>#DDDDDD</shadeb>
             <grid>#FF0000</grid>
             <mgrid>#00FF00</mgrid>
             <font>#FFFFFF</font>
             <frame>#EE00FF</frame>
             <arrow>#FF0000</arrow>
         </colors>
         <no_legend>false</no_legend>
         <only_graph>false</only_graph>
         <force_rules_legend>false</force_rules_legend>
         <title>This is a title</title>
         <step>300</step>
         <fonts>
             <small_font>
                 <name>Courier</name>
                 <style>bold italic</style>
                 <size>12</size>
             </small_font>
             <large_font>
                 <name>Courier</name>
                 <style>plain</style>
                 <size>11</size>
             </large_font>
         </fonts>
         <first_day_of_week>SUNDAY</first_day_of_week>
     </options>
     <datasources>
         <def>
             <name>x</name>
             <rrd>test.rrd</rrd>
             <source>sun</source>
             <cf>AVERAGE</cf>
             <backend>FILE</backend>
         </def>
         <def>
             <name>y</name>
             <rrd>test.rrd</rrd>
             <source>shade</source>
             <cf>AVERAGE</cf>
         </def>
         <cdef>
             <name>x_plus_y</name>
             <rpn>x,y,+</rpn>
         </cdef>
         <cdef>
             <name>x_minus_y</name>
             <rpn>x,y,-</rpn>
         </cdef>
         <sdef>
             <name>x_avg</name>
             <source>x</source>
             <cf>AVERAGE</cf>
         </sdef>
         <sdef>
             <name>y_max</name>
             <source>y</source>
             <cf>MAX</cf>
         </sdef>
     </datasources>
     <graph>
         <area>
             <datasource>x</datasource>
             <color>#FF0000</color>
             <legend>X value\r</legend>
         </area>
         <stack>
             <datasource>y</datasource>
             <color>#00FF00</color>
             <legend>Y value\r</legend>
         </stack>
         <line>
             <datasource>x</datasource>
             <color>#FF0000</color>
             <legend>X value\r</legend>
             <width>2</width>
         </line>
         <print>
             <datasource>x</datasource>
             <cf>AVERAGE</cf>
             <format>Average is %7.3f\c</format>
         </print>
         <gprint>
             <datasource>y</datasource>
             <cf>MAX</cf>
             <format>Max is %7.3f\c</format>
         </gprint>
         <hrule>
             <value>1250</value>
             <color>#0000FF</color>
             <legend>This is a horizontal rule</legend>
         </hrule>
         <vrule>
             <time>now-6h</time>
             <color>#0000FF</color>
             <legend>This is a vertical rule</legend>
         </vrule>
         <comment>Simple comment</comment>
         <comment>One more comment\c</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 method.
  • hard-coded timestamps in templates should be long integeres (like: 1000243567) or at-style formatted strings
  • whitespaces are not harmful
  • 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 or #RRGGBBAA format to specify colors.
  • valid font styles are: PLAIN, ITALIC, BOLD, BOLDITALIC
  • 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 Rrd4j grahps:
     RrdGraphDef gdef = t.getRrdGraphDef();
     RrdGraph g = new RrdGraph(gdef);
     
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.

Summary

[Expand]
Inherited Constants
From interface org.rrd4j.graph.RrdGraphConstants
[Expand]
Inherited Fields
From class org.rrd4j.core.XmlTemplate
Public Constructors
RrdGraphDefTemplate(InputSource inputSource)
Creates template object from any parsable XML source
RrdGraphDefTemplate(File xmlFile)
Creates template object from the file containing XML template code
RrdGraphDefTemplate(String xmlString)
Creates template object from the string containing XML template code
Public Methods
RrdGraphDef getRrdGraphDef()
Creates RrdGraphDef object which can be used to create RrdGraph object (actual Rrd4j graphs).
[Expand]
Inherited Methods
From class org.rrd4j.core.XmlTemplate
From class java.lang.Object

Public Constructors

public RrdGraphDefTemplate (InputSource inputSource)

Creates template object from any parsable XML source

Parameters
inputSource XML source
Throws
IOException thrown in case of I/O error

public RrdGraphDefTemplate (File xmlFile)

Creates template object from the file containing XML template code

Parameters
xmlFile file containing XML template
Throws
IOException thrown in case of I/O error

public RrdGraphDefTemplate (String xmlString)

Creates template object from the string containing XML template code

Parameters
xmlString string containing XML template
Throws
IOException thrown in case of I/O error

Public Methods

public RrdGraphDef getRrdGraphDef ()

Creates RrdGraphDef object which can be used to create RrdGraph object (actual Rrd4j 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 Rrd4j graphs)