public class

RrdDef

extends Object
java.lang.Object
   ↳ org.rrd4j.core.RrdDef

Class Overview

Class to represent definition of new Round Robin Database (RRD). Object of this class is used to create new RRD from scratch - pass its reference as a RrdDb constructor argument (see documentation for RrdDb class). RrdDef object does not actually create new RRD. It just holds all necessary information which will be used during the actual creation process

RRD definition (RrdDef object) consists of the following elements:

  • path to RRD that will be created
  • starting timestamp
  • step
  • version, 1 for linear disposition of archives, 2 for matrix disposition
  • one or more datasource definitions
  • one or more archive definitions

RrdDef provides API to set all these elements. For the complete explanation of all RRD definition parameters, see RRDTool's rrdcreate man page.

Summary

Constants
int DEFAULTVERSION
long DEFAULT_INITIAL_SHIFT If not specified in constructor, starting timestamp will be set to the current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10).
long DEFAULT_STEP Default RRD step to be used if not specified in constructor (300 seconds).
Public Constructors
RrdDef(String path)

Creates new RRD definition object with the given path.

RrdDef(String path, long step)
Creates new RRD definition object with the given path and step.
RrdDef(String path, long startTime, long step)
Creates new RRD definition object with the given path, starting timestamp and step.
RrdDef(String path, long startTime, long step, int version)
Creates new RRD definition object with the given path, starting timestamp, step and version.
Public Methods
void addArchive(ConsolFun consolFun, double xff, int steps, int rows)
Adds single archive definition by specifying its consolidation function, X-files factor, number of steps and rows.
void addArchive(ArcDef... arcDefs)
Adds archive definitions to RRD definition in bulk.
void addArchive(String rrdToolArcDef)
Adds single archive to RRD definition from a RRDTool-like archive definition string.
void addArchive(ArcDef arcDef)
Adds single archive definition represented with object of class ArcDef.
void addDatasource(DsDef dsDef)
Adds single datasource definition represented with object of class DsDef.
void addDatasource(DsDef... dsDefs)
Adds data source definitions to RRD definition in bulk.
void addDatasource(String rrdToolDsDef)
Adds single datasource to RRD definition from a RRDTool-like datasource definition string.
void addDatasource(String dsName, DsType dsType, long heartbeat, double minValue, double maxValue)

Adds single datasource to RRD definition by specifying its data source name, source type, heartbeat, minimal and maximal value.

String dump()
Returns string that represents all specified RRD creation parameters.
boolean equals(Object obj)
Compares the current RrdDef with another.
String exportXmlTemplate()
Exports RrdDef object to string in XML format.
void exportXmlTemplate(String filePath)
Exports RrdDef object to a file in XML format.
void exportXmlTemplate(OutputStream out)
Exports RrdDef object to output stream in XML format.
int getArcCount()
Returns number of defined archives.
ArcDef[] getArcDefs()
Returns all archive definition objects specified so far.
int getDsCount()
Returns number of defined datasources.
DsDef[] getDsDefs()
Returns all data source definition objects specified so far.
long getEstimatedSize()
Returns the number of storage bytes required to create RRD from this RrdDef object.
String getPath()
Returns path for the new RR
long getStartTime()
Returns starting timestamp for the RRD that should be created.
long getStep()
Returns time step for the RRD that will be created.
int getVersion()
Returns the RRD file version
boolean hasArchives()
boolean hasDatasources()
void removeArchives()
Removes all RRA archive definitions.
void removeDatasources()
Removes all datasource definitions.
void setPath(String path)
Sets path to RRD.
void setStartTime(Date date)
Sets RRD's starting timestamp.
void setStartTime(long startTime)
Sets RRD's starting timestamp.
void setStartTime(Calendar gc)
Sets RRD's starting timestamp.
void setStep(long step)
Sets RRD's time step.
void setVersion(int version)
Sets RRD's file version.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int DEFAULTVERSION

Constant Value: 1 (0x00000001)

public static final long DEFAULT_INITIAL_SHIFT

If not specified in constructor, starting timestamp will be set to the current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10).

Constant Value: -10 (0xfffffffffffffff6)

public static final long DEFAULT_STEP

Default RRD step to be used if not specified in constructor (300 seconds).

Constant Value: 300 (0x000000000000012c)

Public Constructors

public RrdDef (String path)

Creates new RRD definition object with the given path. When this object is passed to RrdDb constructor, new RRD will be created using the specified path.

Parameters
path Path to new RRD.

public RrdDef (String path, long step)

Creates new RRD definition object with the given path and step.

Parameters
path Path to new RRD.
step RRD step.

public RrdDef (String path, long startTime, long step)

Creates new RRD definition object with the given path, starting timestamp and step.

Parameters
path Path to new RRD.
startTime RRD starting timestamp.
step RRD step.

public RrdDef (String path, long startTime, long step, int version)

Creates new RRD definition object with the given path, starting timestamp, step and version.

Parameters
path Path to new RRD.
startTime RRD starting timestamp.
step RRD step.
version RRD's file version.

Public Methods

public void addArchive (ConsolFun consolFun, double xff, int steps, int rows)

Adds single archive definition by specifying its consolidation function, X-files factor, number of steps and rows. For the complete explanation of all archive definition parameters see RRDTool's rrdcreate man page.

Parameters
consolFun Consolidation function.
xff X-files factor. Valid values are between 0 and 1.
steps Number of archive steps
rows Number of archive rows
Throws
IllegalArgumentException Thrown if archive with the same consolidation function and the same number of steps is already added.

public void addArchive (ArcDef... arcDefs)

Adds archive definitions to RRD definition in bulk.

Parameters
arcDefs Array of archive definition objects
Throws
IllegalArgumentException Thrown if RRD definition already contains archive with the same consolidation function and the same number of steps.

public void addArchive (String rrdToolArcDef)

Adds single archive to RRD definition from a RRDTool-like archive definition string. The string must have five elements separated with colons (:) in the following order:

 RRA:consolidationFunction:XFilesFactor:steps:rows
 
For example:

 RRA:AVERAGE:0.5:10:1000
 
For more information on archive definition parameters see rrdcreate man page.

Parameters
rrdToolArcDef Archive definition string with the syntax borrowed from RRDTool.
Throws
IllegalArgumentException Thrown if invalid string is supplied.

public void addArchive (ArcDef arcDef)

Adds single archive definition represented with object of class ArcDef.

Parameters
arcDef Archive definition.
Throws
IllegalArgumentException Thrown if archive with the same consolidation function and the same number of steps is already added.

public void addDatasource (DsDef dsDef)

Adds single datasource definition represented with object of class DsDef.

Parameters
dsDef Datasource definition.

public void addDatasource (DsDef... dsDefs)

Adds data source definitions to RRD definition in bulk.

Parameters
dsDefs Array of data source definition objects.

public void addDatasource (String rrdToolDsDef)

Adds single datasource to RRD definition from a RRDTool-like datasource definition string. The string must have six elements separated with colons (:) in the following order:

 DS:name:type:heartbeat:minValue:maxValue
 
For example:

 DS:input:COUNTER:600:0:U
 
For more information on datasource definition parameters see rrdcreate man page.

Parameters
rrdToolDsDef Datasource definition string with the syntax borrowed from RRDTool.
Throws
IllegalArgumentException Thrown if invalid string is supplied.

public void addDatasource (String dsName, DsType dsType, long heartbeat, double minValue, double maxValue)

Adds single datasource to RRD definition by specifying its data source name, source type, heartbeat, minimal and maximal value. For the complete explanation of all data source definition parameters see RRDTool's rrdcreate man page.

IMPORTANT NOTE: If datasource name ends with '!', corresponding archives will never store NaNs as datasource values. In that case, NaN datasource values will be silently replaced with zeros by the framework.

Parameters
dsName Data source name.
dsType Data source type. Valid types are "COUNTER", "GAUGE", "DERIVE" and "ABSOLUTE" (these string constants are conveniently defined in the DsType class).
heartbeat Data source heartbeat.
minValue Minimal acceptable value. Use Double.NaN if unknown.
maxValue Maximal acceptable value. Use Double.NaN if unknown.
Throws
IllegalArgumentException Thrown if new datasource definition uses already used data source name.

public String dump ()

Returns string that represents all specified RRD creation parameters. Returned string has the syntax of RRDTool's create command.

Returns
  • Dumped content of RrdDb object.

public boolean equals (Object obj)

Compares the current RrdDef with another. RrdDefs are considered equal if:

  • RRD steps match
  • all datasources have exactly the same definition in both RrdDef objects (datasource names, types, heartbeat, min and max values must match)
  • all archives have exactly the same definition in both RrdDef objects (archive consolidation functions, X-file factors, step and row counts must match)

Parameters
obj The second RrdDef object
Returns
  • true if RrdDefs match exactly, false otherwise

public String exportXmlTemplate ()

Exports RrdDef object to string in XML format. Generated XML string can be parsed with RrdDefTemplate class.

Returns
  • XML formatted string representing this RrdDef object

public void exportXmlTemplate (String filePath)

Exports RrdDef object to a file in XML format. Generated XML code can be parsed with RrdDefTemplate class.

Parameters
filePath Path to the file
Throws
IOException

public void exportXmlTemplate (OutputStream out)

Exports RrdDef object to output stream in XML format. Generated XML code can be parsed with RrdDefTemplate class.

Parameters
out Output stream

public int getArcCount ()

Returns number of defined archives.

Returns
  • Number of defined archives.

public ArcDef[] getArcDefs ()

Returns all archive definition objects specified so far.

Returns
  • Array of archive definition objects.

public int getDsCount ()

Returns number of defined datasources.

Returns
  • Number of defined datasources.

public DsDef[] getDsDefs ()

Returns all data source definition objects specified so far.

Returns
  • Array of data source definition objects

public long getEstimatedSize ()

Returns the number of storage bytes required to create RRD from this RrdDef object.

Returns
  • Estimated byte count of the underlying RRD storage.

public String getPath ()

Returns path for the new RR

Returns
  • path to the new RRD which should be created

public long getStartTime ()

Returns starting timestamp for the RRD that should be created.

Returns
  • RRD starting timestamp

public long getStep ()

Returns time step for the RRD that will be created.

Returns
  • RRD step

public int getVersion ()

Returns the RRD file version

Returns
  • the version

public boolean hasArchives ()

public boolean hasDatasources ()

public void removeArchives ()

Removes all RRA archive definitions.

public void removeDatasources ()

Removes all datasource definitions.

public void setPath (String path)

Sets path to RRD.

Parameters
path to new RRD.

public void setStartTime (Date date)

Sets RRD's starting timestamp.

Parameters
date starting date

public void setStartTime (long startTime)

Sets RRD's starting timestamp.

Parameters
startTime starting timestamp.

public void setStartTime (Calendar gc)

Sets RRD's starting timestamp.

Parameters
gc starting date

public void setStep (long step)

Sets RRD's time step.

Parameters
step RRD time step.

public void setVersion (int version)

Sets RRD's file version.

Parameters
version the version to set