org.jrobin.core

Class RrdDb

public class RrdDb extends Object implements RrdUpdater

Main class used to create and manipulate round robin databases (RRDs). Use this class to perform update and fetch operations on exisiting RRDs, to create new RRD from the definition (object of class RrdDef) or from XML file (dumped content of RRDTool's or JRobin's RRD file).

Each RRD is backed with some kind of storage. For example, RRDTool supports only one kind of storage (disk file). On the contrary, JRobin gives you freedom to use other storage (backend) types even to create your own backend types for some special purposes. JRobin by default stores RRD data in files (as RRDTool), but you might choose to store RRD data in memory (this is supported in JRobin), to use java.nio.* instead of java.io.* package for file manipulation (also supported) or to store whole RRDs in the SQL database (you'll have to extend some classes to do this).

Note that JRobin uses binary format different from RRDTool's format. You cannot use this class to manipulate RRD files created with RRDTool. However, if you perform the same sequence of create, update and fetch operations, you will get exactly the same results from JRobin and RRDTool.

You will not be able to use JRobin API if you are not familiar with basic RRDTool concepts. Good place to start is the official RRD tutorial and relevant RRDTool man pages: rrdcreate, rrdupdate, rrdfetch and rrdgraph. For RRDTool's advanced graphing capabilities (RPN extensions), also supported in JRobin, there is an excellent CDEF tutorial.

See Also: RrdBackend RrdBackendFactory

Field Summary
static StringPREFIX_RRDTool
prefix to identify external RRDTool file source used in various RrdDb constructors
static StringPREFIX_XML
prefix to identify external XML file source used in various RrdDb constructors
Constructor Summary
RrdDb(RrdDef rrdDef)

Constructor used to create new RRD object from the definition.

RrdDb(RrdDef rrdDef, RrdBackendFactory factory)

Constructor used to create new RRD object from the definition object but with a storage (backend) different from default.

JRobin uses factories to create RRD backend objecs.

RrdDb(String path, boolean readOnly)

Constructor used to open already existing RRD.

RrdDb(String path, boolean readOnly, RrdBackendFactory factory)

Constructor used to open already existing RRD backed with a storage (backend) different from default.

RrdDb(String path)

Constructor used to open already existing RRD in R/W mode, with a default storage (backend) type (file on the disk).

RrdDb(String path, RrdBackendFactory factory)

Constructor used to open already existing RRD in R/W mode with a storage (backend) type different from default.

RrdDb(String rrdPath, String externalPath)

Constructor used to create RRD files from external file sources.

RrdDb(String rrdPath, String externalPath, RrdBackendFactory factory)

Constructor used to create RRD files from external file sources with a backend type different from default.

Method Summary
voidclose()
Closes RRD.
booleancontainsDs(String dsName)
Checks presence of a specific datasource.
voidcopyStateTo(RrdUpdater other)
Copies object's internal state to another RrdDb object.
FetchRequestcreateFetchRequest(String consolFun, long fetchStart, long fetchEnd, long resolution)

Prepares fetch request to be executed on this RRD.

FetchRequestcreateFetchRequest(String consolFun, long fetchStart, long fetchEnd)

Prepares fetch request to be executed on this RRD.

SamplecreateSample(long time)

Creates new sample with the given timestamp and all datasource values set to 'unknown'.

SamplecreateSample()

Creates new sample with the current timestamp and all data source values set to 'unknown'.

Stringdump()

Returns string representing complete internal RRD state.

voiddumpXml(OutputStream destination)

Writes the RRD content to OutputStream using XML format.

voiddumpXml(String filename)

Dumps internal RRD state to XML file.

voidexportXml(OutputStream destination)
This method is just an alias for dumpXml method.
StringexportXml()
This method is just an alias for getXml method.
voidexportXml(String filename)
This method is just an alias for dumpXml(String) method.
protected voidfinalize()
ArchivefindMatchingArchive(FetchRequest request)
ArchivefindStartMatchArchive(String consolFun, long startTime, long resolution)
Finds the archive that best matches to the start time (time period being start-time until now) and requested resolution.
intgetArcCount()
Returns the number of RRA arcihves defined in the file
ArchivegetArchive(int arcIndex)
Returns Archive object for the given archive index.
ArchivegetArchive(String consolFun, int steps)
Returns Archive object with the given consolidation function and the number of steps.
intgetArcIndex(String consolFun, int steps)
Returns index of Archive object with the given consolidation function and the number of steps.
byte[]getBytes()
Returns an array of bytes representing the whole RRD.
StringgetCanonicalPath()
Returns canonical path to the underlying RRD file.
DatasourcegetDatasource(int dsIndex)
Returns Datasource object for the given datasource index.
DatasourcegetDatasource(String dsName)
Returns Datasource object corresponding to the given datasource name.
intgetDsCount()
Returns the number of datasources defined in the file
intgetDsIndex(String dsName)

Returns internal index number for the given datasource name.

String[]getDsNames()

Returns an array of datasource names defined in RRD.

HeadergetHeader()
Returns RRD header.
StringgetInfo()
longgetLastArchiveUpdateTime()
Returns the last time when some of the archives in this RRD was updated.
doublegetLastDatasourceValue(String dsName)
Returns the last stored value for the given datasource.
double[]getLastDatasourceValues()
Returns an array of last datasource values.
longgetLastUpdateTime()
Returns time of last update operation as timestamp (in seconds).
StringgetPath()
Returns path to this RRD.
RrdAllocatorgetRrdAllocator()
Required to implement RrdUpdater interface.
RrdBackendgetRrdBackend()
Returns backend object for this RRD which performs actual I/O operations.
RrdDefgetRrdDef()

Returns RRD definition object which can be used to create new RRD with the same creation parameters but with no data in it.

Example:

 RrdDb rrd1 = new RrdDb("original.rrd");
 RrdDef def = rrd1.getRrdDef();
 // fix path
 def.setPath("empty_copy.rrd");
 // create new RRD file
 RrdDb rrd2 = new RrdDb(def);
 
StringgetXml()

Returns string representing internal RRD state in XML format.

booleanisClosed()
Returns true if the RRD is closed.
static voidmain(String[] args)
static voidsetDefaultFactory(String factoryName)
Sets default backend factory to be used.
voidsetInfo(String info)

Field Detail

PREFIX_RRDTool

public static final String PREFIX_RRDTool
prefix to identify external RRDTool file source used in various RrdDb constructors

PREFIX_XML

public static final String PREFIX_XML
prefix to identify external XML file source used in various RrdDb constructors

Constructor Detail

RrdDb

public RrdDb(RrdDef rrdDef)

Constructor used to create new RRD object from the definition. This RRD object will be backed with a storage (backend) of the default type. Initially, storage type defaults to "NIO" (RRD bytes will be put in a file on the disk). Default storage type can be changed with a static setDefaultFactory method call.

New RRD file structure is specified with an object of class RrdDef. The underlying RRD storage is created as soon as the constructor returns.

Typical scenario:

 // create new RRD definition
 RrdDef def = new RrdDef("test.rrd", 300);
 def.addDatasource("input", DsTypes.DT_COUNTER, 600, 0, Double.NaN);
 def.addDatasource("output", DsTypes.DT_COUNTER, 600, 0, Double.NaN);
 def.addArchive(ConsolFuns.CF_AVERAGE, 0.5, 1, 600);
 def.addArchive(ConsolFuns.CF_AVERAGE, 0.5, 6, 700);
 def.addArchive(ConsolFuns.CF_AVERAGE, 0.5, 24, 797);
 def.addArchive(ConsolFuns.CF_AVERAGE, 0.5, 288, 775);
 def.addArchive(ConsolFuns.CF_MAX, 0.5, 1, 600);
 def.addArchive(ConsolFuns.CF_MAX, 0.5, 6, 700);
 def.addArchive(ConsolFuns.CF_MAX, 0.5, 24, 797);
 def.addArchive(ConsolFuns.CF_MAX, 0.5, 288, 775);
 

// RRD definition is now completed, create the database! RrdDb rrd = new RrdDb(def); // new RRD file has been created on your disk

Parameters: rrdDef Object describing the structure of the new RRD file.

Throws: IOException Thrown in case of I/O error. RrdException Thrown if invalid RrdDef object is supplied.

RrdDb

public RrdDb(RrdDef rrdDef, RrdBackendFactory factory)

Constructor used to create new RRD object from the definition object but with a storage (backend) different from default.

JRobin uses factories to create RRD backend objecs. There are three different backend factories supplied with JRobin, and each factory has its unique name:

For example, to create RRD in memory, use the following code

 RrdBackendFactory factory = RrdBackendFactory.getFactory("MEMORY");
 RrdDb rrdDb = new RrdDb(rrdDef, factory);
 rrdDb.close();
 

New RRD file structure is specified with an object of class RrdDef. The underlying RRD storage is created as soon as the constructor returns.

Parameters: rrdDef RRD definition object factory The factory which will be used to create storage for this RRD

Throws: RrdException Thrown if invalid factory or definition is supplied IOException Thrown in case of I/O error

See Also: RrdBackendFactory

RrdDb

public RrdDb(String path, boolean readOnly)

Constructor used to open already existing RRD. This RRD object will be backed with a storage (backend) of the default type (file on the disk). Constructor obtains read or read/write access to this RRD.

Parameters: path Path to existing RRD. readOnly Should be set to false if you want to update the underlying RRD. If you want just to fetch data from the RRD file (read-only access), specify true. If you try to update RRD file open in read-only mode (readOnly set to true), IOException will be thrown.

Throws: IOException Thrown in case of I/O error. RrdException Thrown in case of JRobin specific error.

RrdDb

public RrdDb(String path, boolean readOnly, RrdBackendFactory factory)

Constructor used to open already existing RRD backed with a storage (backend) different from default. Constructor obtains read or read/write access to this RRD.

Parameters: path Path to existing RRD. readOnly Should be set to false if you want to update the underlying RRD. If you want just to fetch data from the RRD file (read-only access), specify true. If you try to update RRD file open in read-only mode (readOnly set to true), IOException will be thrown. factory Backend factory which will be used for this RRD.

Throws: FileNotFoundException Thrown if the requested file does not exist. IOException Thrown in case of general I/O error (bad RRD file, for example). RrdException Thrown in case of JRobin specific error.

See Also: RrdBackendFactory

RrdDb

public RrdDb(String path)

Constructor used to open already existing RRD in R/W mode, with a default storage (backend) type (file on the disk).

Parameters: path Path to existing RRD.

Throws: IOException Thrown in case of I/O error. RrdException Thrown in case of JRobin specific error.

RrdDb

public RrdDb(String path, RrdBackendFactory factory)

Constructor used to open already existing RRD in R/W mode with a storage (backend) type different from default.

Parameters: path Path to existing RRD. factory Backend factory used to create this RRD.

Throws: IOException Thrown in case of I/O error. RrdException Thrown in case of JRobin specific error.

See Also: RrdBackendFactory

RrdDb

public RrdDb(String rrdPath, String externalPath)

Constructor used to create RRD files from external file sources. Supported external file sources are:

Newly created RRD will be backed with a default storage (backend) type (file on the disk).

JRobin and RRDTool use the same format for XML dump and this constructor should be used to (re)create JRobin RRD files from XML dumps. First, dump the content of a RRDTool RRD file (use command line):

 rrdtool dump original.rrd > original.xml
 

Than, use the file original.xml to create JRobin RRD file named copy.rrd:

 RrdDb rrd = new RrdDb("copy.rrd", "original.xml");
 

or:

 RrdDb rrd = new RrdDb("copy.rrd", "xml:/original.xml");
 

See documentation for dumpXml() method to see how to convert JRobin files to RRDTool's format.

To read RRDTool files directly, specify rrdtool:/ prefix in the externalPath argument. For example, to create JRobin compatible file named copy.rrd from the file original.rrd created with RRDTool, use the following code:

 RrdDb rrd = new RrdDb("copy.rrd", "rrdtool:/original.rrd");
 

Note that the prefix xml:/ or rrdtool:/ is necessary to distinguish between XML and RRDTool's binary sources. If no prefix is supplied, XML format is assumed

Parameters: rrdPath Path to a RRD file which will be created externalPath Path to an external file which should be imported, with an optional xml:/ or rrdtool:/ prefix.

Throws: IOException Thrown in case of I/O error RrdException Thrown in case of JRobin specific error

RrdDb

public RrdDb(String rrdPath, String externalPath, RrdBackendFactory factory)

Constructor used to create RRD files from external file sources with a backend type different from default. Supported external file sources are:

JRobin and RRDTool use the same format for XML dump and this constructor should be used to (re)create JRobin RRD files from XML dumps. First, dump the content of a RRDTool RRD file (use command line):

 rrdtool dump original.rrd > original.xml
 

Than, use the file original.xml to create JRobin RRD file named copy.rrd:

 RrdDb rrd = new RrdDb("copy.rrd", "original.xml");
 

or:

 RrdDb rrd = new RrdDb("copy.rrd", "xml:/original.xml");
 

See documentation for dumpXml() method to see how to convert JRobin files to RRDTool's format.

To read RRDTool files directly, specify rrdtool:/ prefix in the externalPath argument. For example, to create JRobin compatible file named copy.rrd from the file original.rrd created with RRDTool, use the following code:

 RrdDb rrd = new RrdDb("copy.rrd", "rrdtool:/original.rrd");
 

Note that the prefix xml:/ or rrdtool:/ is necessary to distinguish between XML and RRDTool's binary sources. If no prefix is supplied, XML format is assumed

Parameters: rrdPath Path to RRD which will be created externalPath Path to an external file which should be imported, with an optional xml:/ or rrdtool:/ prefix. factory Backend factory which will be used to create storage (backend) for this RRD.

Throws: IOException Thrown in case of I/O error RrdException Thrown in case of JRobin specific error

See Also: RrdBackendFactory

Method Detail

close

public void close()
Closes RRD. No further operations are allowed on this RrdDb object.

Throws: IOException Thrown in case of I/O related error.

containsDs

public boolean containsDs(String dsName)
Checks presence of a specific datasource.

Parameters: dsName Datasource name to check

Returns: true if datasource is present in this RRD, false otherwise

Throws: IOException Thrown in case of I/O error.

copyStateTo

public void copyStateTo(RrdUpdater other)
Copies object's internal state to another RrdDb object.

Parameters: other New RrdDb object to copy state to

Throws: IOException Thrown in case of I/O error RrdException Thrown if supplied argument is not a compatible RrdDb object

createFetchRequest

public FetchRequest createFetchRequest(String consolFun, long fetchStart, long fetchEnd, long resolution)

Prepares fetch request to be executed on this RRD. Use returned FetchRequest object and its fetchData() method to actually fetch data from the RRD file.

Parameters: consolFun Consolidation function to be used in fetch request. Allowed values are "AVERAGE", "MIN", "MAX" and "LAST" (these constants are conveniently defined in the ConsolFuns class). fetchStart Starting timestamp for fetch request. fetchEnd Ending timestamp for fetch request. resolution Fetch resolution (see RRDTool's rrdfetch man page for an explanation of this parameter.

Returns: Request object that should be used to actually fetch data from RRD.

Throws: RrdException In case of JRobin related error (invalid consolidation function or invalid time span).

createFetchRequest

public FetchRequest createFetchRequest(String consolFun, long fetchStart, long fetchEnd)

Prepares fetch request to be executed on this RRD. Use returned FetchRequest object and its fetchData() method to actually fetch data from this RRD. Data will be fetched with the smallest possible resolution (see RRDTool's rrdfetch man page for the explanation of the resolution parameter).

Parameters: consolFun Consolidation function to be used in fetch request. Allowed values are "AVERAGE", "MIN", "MAX" and "LAST" (these constants are conveniently defined in the ConsolFuns class). fetchStart Starting timestamp for fetch request. fetchEnd Ending timestamp for fetch request.

Returns: Request object that should be used to actually fetch data from RRD.

Throws: RrdException In case of JRobin related error (invalid consolidation function or invalid time span).

createSample

public Sample createSample(long time)

Creates new sample with the given timestamp and all datasource values set to 'unknown'. Use returned Sample object to specify datasource values for the given timestamp. See documentation for Sample for an explanation how to do this.

Once populated with data source values, call Sample's update() method to actually store sample in the RRD associated with it.

Parameters: time Sample timestamp rounded to the nearest second (without milliseconds).

Returns: Fresh sample with the given timestamp and all data source values set to 'unknown'.

Throws: IOException Thrown in case of I/O error.

createSample

public Sample createSample()

Creates new sample with the current timestamp and all data source values set to 'unknown'. Use returned Sample object to specify datasource values for the current timestamp. See documentation for Sample for an explanation how to do this.

Once populated with data source values, call Sample's update() method to actually store sample in the RRD associated with it.

Returns: Fresh sample with the current timestamp and all data source values set to 'unknown'.

Throws: IOException Thrown in case of I/O error.

dump

public String dump()

Returns string representing complete internal RRD state. The returned string can be printed to stdout and/or used for debugging purposes.

Returns: String representing internal RRD state.

Throws: IOException Thrown in case of I/O related error.

dumpXml

public void dumpXml(OutputStream destination)

Writes the RRD content to OutputStream using XML format. This format is fully compatible with RRDTool's XML dump format and can be used for conversion purposes or debugging.

Parameters: destination Output stream to receive XML data

Throws: IOException Thrown in case of I/O related error

dumpXml

public void dumpXml(String filename)

Dumps internal RRD state to XML file. Use this XML file to convert your JRobin RRD to RRDTool format.

Suppose that you have a JRobin RRD file original.rrd and you want to convert it to RRDTool format. First, execute the following java code:

RrdDb rrd = new RrdDb("original.rrd"); rrd.dumpXml("original.xml");

Use original.xml file to create the corresponding RRDTool file (from your command line):

rrdtool restore copy.rrd original.xml

Parameters: filename Path to XML file which will be created.

Throws: IOException Thrown in case of I/O related error. RrdException Thrown in case of JRobin related error.

exportXml

public void exportXml(OutputStream destination)
This method is just an alias for dumpXml method.

Throws: IOException Thrown in case of I/O related error

exportXml

public String exportXml()
This method is just an alias for getXml method.

Returns: Internal RRD state in XML format.

Throws: IOException Thrown in case of I/O related error RrdException Thrown in case of JRobin specific error

exportXml

public void exportXml(String filename)
This method is just an alias for dumpXml(String) method.

Throws: IOException Thrown in case of I/O related error RrdException Thrown in case of JRobin specific error

finalize

protected void finalize()

findMatchingArchive

public Archive findMatchingArchive(FetchRequest request)

findStartMatchArchive

public Archive findStartMatchArchive(String consolFun, long startTime, long resolution)
Finds the archive that best matches to the start time (time period being start-time until now) and requested resolution.

Parameters: consolFun Consolidation function of the datasource. startTime Start time of the time period in seconds. resolution Requested fetch resolution.

Returns: Reference to the best matching archive.

Throws: IOException Thrown in case of I/O related error.

getArcCount

public int getArcCount()
Returns the number of RRA arcihves defined in the file

Returns: The number of RRA arcihves defined in the file

getArchive

public Archive getArchive(int arcIndex)
Returns Archive object for the given archive index.

Parameters: arcIndex Archive index (zero based)

Returns: Archive object

getArchive

public Archive getArchive(String consolFun, int steps)
Returns Archive object with the given consolidation function and the number of steps.

Parameters: consolFun Consolidation function steps Number of archive steps

Returns: Requested Archive object or null if no such archive could be found

Throws: IOException Thrown in case of I/O error

getArcIndex

public int getArcIndex(String consolFun, int steps)
Returns index of Archive object with the given consolidation function and the number of steps. Exception is thrown if such archive could not be found.

Parameters: consolFun Consolidation function steps Number of archive steps

Returns: Requested Archive object

Throws: IOException Thrown in case of I/O error RrdException Thrown if no such archive could be found

getBytes

public byte[] getBytes()
Returns an array of bytes representing the whole RRD.

Returns: All RRD bytes

Throws: IOException Thrown in case of I/O related error.

getCanonicalPath

public String getCanonicalPath()
Returns canonical path to the underlying RRD file. Note that this method makes sense just for ordinary RRD files created on the disk - an exception will be thrown for RRD objects created in memory or with custom backends.

Returns: Canonical path to RRD file;

Throws: IOException Thrown in case of I/O error or if the underlying backend is not derived from RrdFileBackend.

getDatasource

public Datasource getDatasource(int dsIndex)
Returns Datasource object for the given datasource index.

Parameters: dsIndex Datasource index (zero based)

Returns: Datasource object

getDatasource

public Datasource getDatasource(String dsName)
Returns Datasource object corresponding to the given datasource name.

Parameters: dsName Datasource name

Returns: Datasource object corresponding to the give datasource name or null if not found.

Throws: IOException Thrown in case of I/O error

getDsCount

public int getDsCount()
Returns the number of datasources defined in the file

Returns: The number of datasources defined in the file

getDsIndex

public int getDsIndex(String dsName)

Returns internal index number for the given datasource name. This index is heavily used by jrobin.graph package and has no value outside of it.

Parameters: dsName Data source name.

Returns: Internal index of the given data source name in this RRD.

Throws: RrdException Thrown in case of JRobin related error (invalid data source name, for example) IOException Thrown in case of I/O error.

getDsNames

public String[] getDsNames()

Returns an array of datasource names defined in RRD.

Returns: Array of datasource names.

Throws: IOException Thrown in case of I/O error.

getHeader

public Header getHeader()
Returns RRD header.

Returns: Header object

getInfo

public String getInfo()

getLastArchiveUpdateTime

public long getLastArchiveUpdateTime()
Returns the last time when some of the archives in this RRD was updated. This time is not the same as the getLastUpdateTime since RRD file can be updated without updating any of the archives.

Returns: last time when some of the archives in this RRD was updated

Throws: IOException Thrown in case of I/O error

getLastDatasourceValue

public double getLastDatasourceValue(String dsName)
Returns the last stored value for the given datasource.

Parameters: dsName Datasource name

Returns: Last stored value for the given datasource

Throws: IOException Thrown in case of I/O error RrdException Thrown if no datasource in this RrdDb matches the given datasource name

getLastDatasourceValues

public double[] getLastDatasourceValues()
Returns an array of last datasource values. The first value in the array corresponds to the first datasource defined in the RrdDb and so on.

Returns: Array of last datasource values

Throws: IOException Thrown in case of I/O error

getLastUpdateTime

public long getLastUpdateTime()
Returns time of last update operation as timestamp (in seconds).

Returns: Last update time (in seconds).

getPath

public String getPath()
Returns path to this RRD.

Returns: Path to this RRD.

getRrdAllocator

public RrdAllocator getRrdAllocator()
Required to implement RrdUpdater interface. You should never call this method directly.

Returns: Allocator object

getRrdBackend

public RrdBackend getRrdBackend()
Returns backend object for this RRD which performs actual I/O operations.

Returns: RRD backend for this RRD.

getRrdDef

public RrdDef getRrdDef()

Returns RRD definition object which can be used to create new RRD with the same creation parameters but with no data in it.

Example:

 RrdDb rrd1 = new RrdDb("original.rrd");
 RrdDef def = rrd1.getRrdDef();
 // fix path
 def.setPath("empty_copy.rrd");
 // create new RRD file
 RrdDb rrd2 = new RrdDb(def);
 

Returns: RRD definition.

Throws: RrdException Thrown in case of JRobin specific error.

getXml

public String getXml()

Returns string representing internal RRD state in XML format. This format is fully compatible with RRDTool's XML dump format and can be used for conversion purposes or debugging.

Returns: Internal RRD state in XML format.

Throws: IOException Thrown in case of I/O related error RrdException Thrown in case of JRobin specific error

isClosed

public boolean isClosed()
Returns true if the RRD is closed.

Returns: true if closed, false otherwise

main

public static void main(String[] args)

setDefaultFactory

public static void setDefaultFactory(String factoryName)
Sets default backend factory to be used. This method is just an alias for RrdBackendFactory.

Parameters: factoryName Name of the backend factory to be set as default.

Throws: RrdException Thrown if invalid factory name is supplied, or not called before the first backend object (before the first RrdDb object) is created.

setInfo

public void setInfo(String info)