HOME | Library | JRobin API | Utilities | Support | About Us | Forum

Main library
Simple demo
Complex demo
Stress test
Other demos
Playing with ANT

# Other demos

### LazyDemo

Like with Rrdtool, the lazy option can be used to make sure images only get generated if they are outdated. In other words, if the RRD datasources have a last update time that is after the last graph generation time. The last graph generation time is determined by the 'last modified' timestamp of the file.

This demo also demonstrates how to use RrdOpener class for centralized menagment of RrdDb instances.

To run the demo, issue the following command from the command line:

    java -cp jrobin-demo-{version}.jar org.jrobin.demo.graph.LazyDemo

In a windowless environment be sure to specify `-Djava.awt.headless=true` option. When the program finishes you'll find a set of images named lazy-graph*.png in the jrobin-demo subdirectory of your home directory.

### SwingDemo

A new method was added to RrdGraph allowing you to render a JRobin graph onto a Graphics2D object you pass yourself. The method is of the form renderImage(Graphics2D, width, height). Additionally an extra method was added to retrieve a JRobin graph directly as its underlying BufferedImage: getBufferedImage(width, height). In both cases auto-sizing of the graph is done by specifying a width and height of 0.

Since 1.4.0 version JRobin also offers an entirely new datasource, internally called Sdef. This datasource represents the result of a consolidation function applied to another datasource, much like the gprint() method does. A specified Sdef datasource can be used in any Cdef datasource with RPN calculation, and can be derived from any other datasource. It can also be used in the normal way for plotting or drawing comments. Example code:

    graphDef.datasource( "in", RRD_FILE, "input", "AVERAGE" );
    graphDef.datasource( "avgIn", "in", "AVERAGE" ); // Sdef
    graphDef.datasource( "deviation", "in,avgIn,-" );
    graphDef.area( "deviation", Color.BLUE, "Deviation from average" );
    graphDef.line( "avgIn", Color.RED, "Average incoming" );

and the corrseponding code in the XML template would be:

    <datasources>
      ...
      <def>
        <name>avgIn</name>
        <datasource>in</datasource>
        <cf>AVERAGE</cf>
      </def>
      ...
    </datasources>

You can also plot a timestamp with a specified format on a JRobin graph. You can either specify the timestamp in several ways, or you can omit the timestamp, in which case the 'current time' will be plotted. The current time in this case would be the time when the graph generation encounters the Time command. The format of the text is like normal comment, only it should contain a @t marker to specficy where the timestamp should be. The timestamp will then be printed according to the provided pattern. The pattern can be a pattern string for a SimpleDateFormat object, or it can be any DateFormat object you created:

    // Specific time
    rrdGraphDef.time("First day of the year: @t@l", "dd-MM-yyyy",
        new GregorianCalendar(2004, Calendar.JANUARY, 1));
    // Current time
    rrdGraphDef.time( "@lGenerated: @t@c", "HH:mm:ss");

There is a set of corresponding XML tags for the RrdGraphDef template. If the value tag is omitted, the current time will be used. Otherwise, the value tag can be specified like the start and end time of the graph: as an absolute time in seconds since the epoch, or as an ISO timestamp of the form: `yyyy-MM-dd HH:mm:ss`.

    <!-- This would print out the current time -->
    <time>
        <format>Current time: @t</format>
        <pattern>MMM dd, yyyy   HH:mm:ss</pattern>
    </time>

    <!-- This would print out: january 2004 (in your locale) -->
    <time>
        <format>Month: @t</format>
        <pattern>MMMM yyyy</pattern>
        <value>2004-01-01 12:00:00</value>
    </time></graph>

The demo also illustrates how to use in-memory RRDs for storing RRD data (data gets lost as soon as the application finishes).

To run the demo, issue the following command from the command line:

    java -cp jrobin-demo-{version}.jar org.jrobin.demo.graph.SwingDemo

### XPORT demo

JRobin now supports data export functionality, much like the original RRDtool does, with a few extra touches ofcourse.

Since 1.4.0 export has been introduced in the form of RrdExport, RrdExportDef and ExportData classes. It works very much like graphing does, here's a quick example:

    // Create a def for export specification
    RrdExportDef def = new RrdExportDef( startTime, endTime );
    def.datasource( "ds", "test.rrd", "datasource", "AVERAGE" );
    def.export( "ds", "A single datasource" );

    // Pass the def to the exporter, fetch the export data, but no more than 50 rows
    // If you don't specify the maximum number of rows to retrieve, 400 will be used
    RrdExport export = new RrdExport( def );
    ExportData data = export.fetch( 50 );

    // Dump the exported data to XML in a file
    data.exportXml( "export-data.xml" );

    // Or request a value directly from the exported data
    double value = data.getAggregate( "ds", "MAX" );

    // We can also request the value as a string, much like with GPRINT
    System.out.println( data.print( "ds", "MAX", "Maximum: @5.2" ) );

The ExportData class corresponds to the public RrdDataSet interface, as does the FetchData class (the result of a direct fetch on an RRD). The RrdDataSet interface gives you a number of useful methods that can be used to retrieve and calculate data or for example pass it on to an external graphing or charting library.

UNLIKE with RRDtool, it is not necessary to specify what data to export, by default all datasources requested will be exported. However, as soon you specify a datasource to export, using the export() construct, by default the system will revert to the so called 'strict' export like RRDtool, and only export the datasources you explicitly specified. You can override this behaviour by calling setStrictExport(boolean) method manually. If you disable strict export, you can set legends for only a few datasources, but still have all datasources in the ExportData set.

The RrdExportDef is a subset of the RrdGraphDef and introduces a new XML Template very much alike. An example:

    <rrd_export_def>
      <span>
        <start>${start}</start>
        <end>${end}</end>
      </span>
      <datasources>
        <def>
          <name>bytesIn</name>
          <rrd>${rrd}</rrd>
          <source>ifInOctets</source>
          <cf>AVERAGE</cf>
        </def>
        <def>
          <name>bitsIn</name>
          <rpn>bytesIn,8,*</rpn>
        </def>
      </datasources>
      <exports>
        <export>
          <datasource>bitsIn</datasource>
          <legend>Bits Incoming</legend>
        </export>
        <export>
          <datasource>bytesIn</datasource>
          <legend>Bytes Incoming</legend>
         </export>
      </exports>
    </rrd_export_def>

An ExportData object can directly be recreated from an export XML file, like:

    ExportData data = new ExportData( new File("export-data.xml"), true );

The second parameter determines if the legends in the export XML should be used to name the datasources. If set to false, the datasources will get named sequentially of the form 'd1', 'd2'... unless you specify a different prefix in the ExportData constructor, like in:

    ExportData data = new ExportData( new File("export-data.xml"), "mydata");
    // The imported datasources will be named 'mydata1', 'mydata2' ...

Because of the XML import functionality, you can easily import regular RRDtool XPORT xml data into a JRobin ExportData set. Furthermore, ExportData can be set as a datasource in a normal RrdGraphDef, allowing you to generate graphs directly from RRDtool exported data. Simply add a number of ExportData objects to a RrdGraphDef:

    RrdGraphDef graphDef = new RrdGraphDef();
    ...
    graphDef.addExportData( exportData1 );
    graphDef.addExportData( exportData2 );
    ...

And there is the RrdGraphDefTemplate XML variation:

    <datasources>
      ...
      <export_data>
        <file>/export_data/exportdata1.xml</file>
        <ds_name_prefix>traffic</ds_name_prefix>
      </export_data>

      <export_data>
        <file>/export_data/exportdata2.xml</file>
        <use_legend_names>true</use_legend_names>
      </export_data>

      <export_data>
        <file>/export_data/exportdata3.xml</file>
      </export_data>
      ...
    </datasources>

Every RrdGraphDef is also a RrdExportDef. This means you can pass a RrdGraphDef directly to an RrdExport, you can generate the ExportData from the corresponding graph. However, if you are interested in both generating the graph and retrieving the ExportData, it is better to use the export functionality of RrdGraph, in order to generate the data only once. A simple example:

    RrdGraphDef graphDef = new RrdGraphDef( startTime, endTime );
    ...
    RrdGraph graph = new RrdGraph( graphDef );

    // Save the graph image
    graph.saveAsPNG( graphFile );

    // Get the export data
    ExportData data = graph.getExportData();

    // Do something with the exported data
    // Store max values in a relational database for example.

Note: RrdGraph also contains two fetchExportData methods. These will calculate the ExportData again based on the passed RrdGraphDef. Use the getExportData() method after creating the image to save a calculation roundtrip, it can save you many CPU cycles, use fetchExportData() if you want to retrieve the export data without generating the graph, or if you want to re-generate it after changing the graphDef or with a lower maxRows limit.

The workings of JRobin export are demonstrated in the combined ExportDemo. The ExportDemo is actually two different apps: ExportExportDemo, that exports data from two rrd files and dumps the result in some XML files:

    java -cp jrobin-demo-{version}.jar org.jrobin.demo.graph.ExportExportDemo

...and the ExportImportDemo that reads in the output from ExportExportDemo and generates a graph from it:

    java -cp jrobin-demo-{version}.jar org.jrobin.demo.graph.ExportImportDemo

When the demo finishes, you'll find XPORT-ed RRD data in the jrobin-demo subdirectory of your home directory (look for files named export*.xml) and the graph created from the exported data (export-graph.png).

### Demo utilities: GraphTemplate and ExportTemplate

JRobin 1.4.0 comes with two new demo applications: GraphTemplate and ExportTemplate. These are command-line utilities that allow you to generate output (a graph or export data) based on a template XML file (RrdGraphDefTemplate or RrdExportDefTemplate). The programs are very similar, and if they detect parameters in the template XML (${param}), they will ask for the values of these parameters interactively.

    java -cp jrobin-demo-{version}.jar \
        org.jrobin.demo.graph.GraphTemplate \
        [-img (png|gif|jpg)] [-w width] [-h height] [-q jpegQuality] \
        <template_file> <image_name>

Command parameters are:

- -img Specifies the image format of the target graph
- -width Width in pixels of the target graph
- -height Height in pixels of the target graph
- -q If JPEG is used as image format, specify the quality as float
- <template_file> File containing XML RrdGraphDef template
- <image_name> Name the image should be saved as

    java -cp jrobin-demo-1.4.0.jar \
        org.jrobin.demo.graph.ExportTemplate \
        [-m maxRows] [-f <dump_file>] \
        <template_file>

Command parameters are:

- -m Maximum number of rows to have in the exported data (similar to RRDtool XPORT -m)
- -f File where to dump the exported data in XML format, if not specified, the export XML is printed on stdout
- <template_file> File containing XML RrdExportDef template

Back to the top

Copyright © 2003, 2004 Sasa Markovic & Arne Vandamme. All Rights Reserved.