![]() |
|||||||||||||||||
|
Templates APICreating JRobin RRD files and graphs from your Java code is quite straightforward (see Core API and Graphing API pages for detailed instructions). This approach (all creation parameters are hard-coded in your java source) is probably sufficient in most cases, but in complex, live projects you will probably need something more flexible. Simply, you don't want to recompile your source code each time when you want to change the background color of the graph from white to yellow. JRobin templates should address this issue in a logical way. Now, you are able to put all RRD file/graph creation parameters and options in an external XML file and use it to create as many RRD files/graphs as needed. Template API is available since JRobin 1.3.0. Creating RRD files from XML templatesHere is a sample XML code containing all available creation parameters and options of a new RRD file: <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> This XML template will be parsed by RrdDefTemplate class. Some notes on the template syntax:
Any part of the text between Typical usage scenario:
You should create new RrdDefTemplate object only once for each XML template (this is recommended, but not mandatory). 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. If you change the XML template, you'll have to restart your Java application, but without source code recompilation. Note that RrdDefTemplate class is not thread safe: if you use the same RrdDefTemplate object in several different threads, you should synchronize their access to the template object. Creating RRD graphs from XML templatesHere 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> <first_day_of_week>SUNDAY</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> </def> <def> <name>input8</name> <rpn>input,8,*</rpn> </def> <def> <name>output8</name> <rpn>output,8,*,-1,*</rpn> </def> </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> <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> <comment>Created with JRobin</comment> </graph> </rrd_graph_def> This XML template will be parsed by RrdGraphDefTemplate class. There is a strong relation between the XML template syntax and the syntax of
Any part of the text between Typical usage scenario:
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. If you change the XML template, you'll have to restart your Java application, but without source code recompilation. Note that RrdGraphDefTemplate class is not thread safe: access to the template object from several threads should be synchronized. Templates demoTo see both template classes in action, run the the following demo (source code is provided with the distribution): java -cp jrobin-demo-{version}.jar \ org.jrobin.demo.TemplatesDemo If you run this demo in a headless environment (without X-server), be sure to specify -Djava.awt.headles=true option on the command line. Copyright © 2003, 2004 Sasa Markovic & Arne Vandamme. All Rights Reserved. |