Package org.jrobin.core

Class RrdDef

java.lang.Object

org.jrobin.core.RrdDef

public class RrdDef
extends Object

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
• 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.

Author:

Sasa Markovic

Field Summary

Fields

Modifier and Type	Field	Description
static long	DEFAULT_INITIAL_SHIFT	if not specified in constructor, starting timestamp will be set to the current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10)
static long	DEFAULT_STEP	default RRD step to be used if not specified in constructor (300 seconds)

Constructor Summary

Constructors

Constructor	Description
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.

Method Summary

Modifier and Type	Method	Description
void	addArchive(String rrdToolArcDef)	Adds single archive to RRD definition from a RRDTool-like archive definition string.
void	addArchive(String 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 arcDef)	Adds single archive definition represented with object of class ArcDef.
void	addArchive(ArcDef[] arcDefs)	Adds archive 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, String 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.
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.
(package private) static long	calculateSize(int dsCount, int arcCount, int rowsCount)
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(OutputStream out)	Exports RrdDef object to output stream in XML format.
void	exportXmlTemplate(String filePath)	Exports RrdDef object to a file in XML format.
(package private) ArcDef	findArchive(String consolFun, int steps)
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 RRD
(package private) String	getRrdToolCommand()
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	hashCode()
(package private) void	removeArchive(String consolFun, int steps)
void	removeArchives()	Removes all RRA archive definitions.
(package private) void	removeDatasource(String dsName)
void	removeDatasources()	Removes all datasource definitions.
(package private) void	saveSingleDatasource(String dsName)
void	setPath(String path)	Sets path to RRD.
void	setStartTime(long startTime)	Sets RRD's starting timestamp.
void	setStartTime(Calendar gc)	Sets RRD's starting timestamp.
void	setStartTime(Date date)	Sets RRD's starting timestamp.
void	setStep(long step)	Sets RRD's time step.
String	toString()
(package private) void	validate()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_STEP

public static final long DEFAULT_STEP

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

See Also:

Constant Field Values

DEFAULT_INITIAL_SHIFT

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)

See Also:

Constant Field Values

Constructor Detail

RrdDef

public RrdDef(String path)
       throws RrdException

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.

Throws:

RrdException - Thrown if name is invalid (null or empty).

RrdDef

public RrdDef(String path,
              long step)
       throws RrdException

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

Parameters:

path - Path to new RRD.

step - RRD step.

Throws:

RrdException - Thrown if supplied parameters are invalid.

RrdDef

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

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.

Throws:

RrdException - Thrown if supplied parameters are invalid.

Method Detail

getPath

public String getPath()

Returns path for the new RRD

Returns:

path to the new RRD which should be created

getStartTime

public long getStartTime()

Returns starting timestamp for the RRD that should be created.

Returns:

RRD starting timestamp

getStep

public long getStep()

Returns time step for the RRD that will be created.

Returns:

RRD step

setPath

public void setPath(String path)

Sets path to RRD.

Parameters:

path - to new RRD.

setStartTime

public void setStartTime(long startTime)

Sets RRD's starting timestamp.

Parameters:

startTime - starting timestamp.

setStartTime

public void setStartTime(Date date)

Sets RRD's starting timestamp.

Parameters:

date - starting date

setStartTime

public void setStartTime(Calendar gc)

Sets RRD's starting timestamp.

Parameters:

gc - starting date

setStep

public void setStep(long step)

Sets RRD's time step.

Parameters:

step - RRD time step.

addDatasource

public void addDatasource(DsDef dsDef)
                   throws RrdException

Adds single datasource definition represented with object of class DsDef.

Parameters:

dsDef - Datasource definition.

Throws:

RrdException - Thrown if new datasource definition uses already used data source name.

addDatasource

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

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 DsTypes class).

heartbeat - Data source heartbeat.

minValue - Minimal acceptable value. Use Double.NaN if unknown.

maxValue - Maximal acceptable value. Use Double.NaN if unknown.

Throws:

RrdException - Thrown if new datasource definition uses already used data source name.

addDatasource

public void addDatasource(String rrdToolDsDef)
                   throws RrdException

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:

RrdException - Thrown if invalid string is supplied.

addDatasource

public void addDatasource(DsDef[] dsDefs)
                   throws RrdException

Adds data source definitions to RRD definition in bulk.

Parameters:

dsDefs - Array of data source definition objects.

Throws:

RrdException - Thrown if duplicate data source name is used.

addArchive

public void addArchive(ArcDef arcDef)
                throws RrdException

Adds single archive definition represented with object of class ArcDef.

Parameters:

arcDef - Archive definition.

Throws:

RrdException - Thrown if archive with the same consolidation function and the same number of steps is already added.

addArchive

public void addArchive(ArcDef[] arcDefs)
                throws RrdException

Adds archive definitions to RRD definition in bulk.

Parameters:

arcDefs - Array of archive definition objects

Throws:

RrdException - Thrown if RRD definition already contains archive with the same consolidation function and the same number of steps.

addArchive

public void addArchive(String consolFun,
                       double xff,
                       int steps,
                       int rows)
                throws RrdException

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. Valid values are "AVERAGE", "MIN", "MAX" and "LAST" (these constants are conveniently defined in the ConsolFuns class)

xff - X-files factor. Valid values are between 0 and 1.

steps - Number of archive steps

rows - Number of archive rows

Throws:

RrdException - Thrown if archive with the same consolidation function and the same number of steps is already added.

addArchive

public void addArchive(String rrdToolArcDef)
                throws RrdException

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:

RrdException - Thrown if invalid string is supplied.

validate

void validate()
       throws RrdException

Throws:

RrdException

getDsDefs

public DsDef[] getDsDefs()

Returns all data source definition objects specified so far.

Returns:

Array of data source definition objects

getArcDefs

public ArcDef[] getArcDefs()

Returns all archive definition objects specified so far.

Returns:

Array of archive definition objects.

getDsCount

public int getDsCount()

Returns number of defined datasources.

Returns:

Number of defined datasources.

getArcCount

public int getArcCount()

Returns number of defined archives.

Returns:

Number of defined archives.

dump

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.

getRrdToolCommand

String getRrdToolCommand()

removeDatasource

void removeDatasource(String dsName)
               throws RrdException

Throws:

RrdException

saveSingleDatasource

void saveSingleDatasource(String dsName)

removeArchive

void removeArchive(String consolFun,
                   int steps)
            throws RrdException

Throws:

RrdException

findArchive

ArcDef findArchive(String consolFun,
                   int steps)
            throws RrdException

Throws:

RrdException

exportXmlTemplate

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

exportXmlTemplate

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

exportXmlTemplate

public void exportXmlTemplate(String filePath)
                       throws IOException

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 - if an I/O error occurs.

getEstimatedSize

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.

calculateSize

static long calculateSize(int dsCount,
                          int arcCount,
                          int rowsCount)

equals

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)

Overrides:

equals in class Object

Parameters:

obj - The second RrdDef object

Returns:

true if RrdDefs match exactly, false otherwise

hashCode

public int hashCode()

Overrides:

hashCode in class Object

removeDatasources

public void removeDatasources()

Removes all datasource definitions.

removeArchives

public void removeArchives()

Removes all RRA archive definitions.

toString

public String toString()

Overrides:

toString in class Object