Class RrdDef
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.
- Author:
- Sasa Markovic
-
Field Summary
Modifier and TypeFieldDescriptionstatic final long
If not specified in constructor, starting timestamp will be set to the current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10).static final long
Default RRD step to be used if not specified in constructor (300 seconds).static final int
ConstantDEFAULTVERSION=2
-
Constructor Summary
ConstructorDescriptionCreates new RRD definition object with the given path.Creates new RRD definition object with the given path and step.Creates new RRD definition object with the given path, starting timestamp and step.Creates new RRD definition object with the given path, starting timestamp, step and version.Creates new RRD definition object with the given path.Creates new RRD definition object with the given path and step.Creates new RRD definition object with the given path, starting timestamp and step.Creates new RRD definition object with the given path, starting timestamp, step and version. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addArchive
(String rrdToolArcDef) Adds single archive to RRD definition from a RRDTool-like archive definition string.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 arcDef) Adds single archive definition represented with object of classArcDef
.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, 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.void
addDatasource
(DsDef dsDef) Adds single datasource definition represented with object of classDsDef
.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[] dsNames) dump()
Returns string that represents all specified RRD creation parameters.boolean
Exports RrdDef object to string in XML format.exportXmlTemplate
(boolean compatible) Exports RrdDef object to string in XML format.void
Exports RrdDef object to output stream in XML format.void
exportXmlTemplate
(OutputStream out, boolean compatible) Exports RrdDef object to output stream in XML format.void
exportXmlTemplate
(String filePath) Exports RrdDef object to a file in XML format.void
exportXmlTemplate
(String filePath, boolean compatible) Exports RrdDef object to a file in XML format.(package private) ArcDef
findArchive
(ConsolFun consolFun, int steps) int
Returns number of defined archives.ArcDef[]
Returns all archive definition objects specified so far.int
Returns number of defined datasources.DsDef[]
Returns all data source definition objects specified so far.long
Returns the number of storage bytes required to create RRD from this RrdDef object.getPath()
Returns path for the new RRD.(package private) String
long
Returns starting time stamp for the RRD that should be created.long
getStep()
Returns time step for the RRD that will be created.getUri()
Returns URI for the new RRDint
Returns the RRD file versionboolean
hasArchives.boolean
hasDatasources.int
hashCode()
(package private) void
removeArchive
(ConsolFun consolFun, int steps) void
Removes all RRA archive definitions.(package private) void
removeDatasource
(String dsName) void
Removes all datasource definitions.(package private) void
saveSingleDatasource
(String dsName) void
Sets path to RRD.void
Sets URI 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.void
setVersion
(int version) Sets RRD's file version.
-
Field Details
-
DEFAULT_STEP
public static final long DEFAULT_STEPDefault RRD step to be used if not specified in constructor (300 seconds).- See Also:
-
DEFAULT_INITIAL_SHIFT
public static final long DEFAULT_INITIAL_SHIFTIf not specified in constructor, starting timestamp will be set to the current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10).- See Also:
-
DEFAULTVERSION
public static final int DEFAULTVERSIONConstantDEFAULTVERSION=2
- See Also:
-
-
Constructor Details
-
RrdDef
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.The will be transformed internally to an URI using the default backend factory.
- Parameters:
rrdpath
- Path to new RRD.
-
RrdDef
Creates new RRD definition object with the given path. When this object is passed toRrdDb
constructor, new RRD will be created using the specified path.- Parameters:
uri
- URI to the new RRD.
-
RrdDef
Creates new RRD definition object with the given path and step.
The will be transformed internally to an URI using the default backend factory.
- Parameters:
path
- URI to new RRD.step
- RRD step.
-
RrdDef
Creates new RRD definition object with the given path and step.- Parameters:
uri
- URI to new RRD.step
- RRD step.
-
RrdDef
Creates new RRD definition object with the given path, starting timestamp and step.
The will be transformed internally to an URI using the default backend factory.
- Parameters:
path
- Path to new RRD.startTime
- RRD starting timestamp.step
- RRD step.
-
RrdDef
Creates new RRD definition object with the given path, starting timestamp and step.- Parameters:
uri
- URI to new RRD.startTime
- RRD starting timestamp.step
- RRD step.
-
RrdDef
Creates new RRD definition object with the given path, starting timestamp, step and version.
The will be transformed internally to an URI using the default backend factory.
- Parameters:
path
- Path to new RRD.startTime
- RRD starting timestamp.step
- RRD step.version
- RRD's file version.
-
RrdDef
Creates new RRD definition object with the given path, starting timestamp, step and version.- Parameters:
uri
- URI to new RRD.startTime
- RRD starting timestamp.step
- RRD step.version
- RRD's file version.
-
-
Method Details
-
getPath
Returns path for the new RRD. It's extracted from the URI. If it's an opaque URI, it return the scheme specific part.- Returns:
- path to the new RRD which should be created
-
getUri
Returns URI for the new RRD- Returns:
- URI to the new RRD which should be created
-
getStartTime
public long getStartTime()Returns starting time stamp for the RRD that should be created.- Returns:
- RRD starting time stamp
-
getStep
public long getStep()Returns time step for the RRD that will be created.- Returns:
- RRD step
-
getVersion
public int getVersion()Returns the RRD file version- Returns:
- the version
-
setPath
Sets path to RRD.
The will be transformed internally to an URI using the default backend factory.
- Parameters:
path
- path to new RRD.
-
setPath
Sets URI to RRD.- Parameters:
uri
- URI to new RRD.
-
setStartTime
public void setStartTime(long startTime) Sets RRD's starting timestamp.- Parameters:
startTime
- Starting timestamp.
-
setStartTime
Sets RRD's starting timestamp.- Parameters:
date
- starting date
-
setStartTime
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.
-
setVersion
public void setVersion(int version) Sets RRD's file version.- Parameters:
version
- the version to set
-
addDatasource
Adds single datasource definition represented with object of classDsDef
.- Parameters:
dsDef
- Datasource definition.
-
addDatasource
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 theDsType
class).heartbeat
- Data source heartbeat.minValue
- Minimal acceptable value. UseDouble.NaN
if unknown.maxValue
- Maximal acceptable value. UseDouble.NaN
if unknown.- Throws:
IllegalArgumentException
- Thrown if new datasource definition uses already used data source name.
-
addDatasource
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.
-
addDatasource
Adds data source definitions to RRD definition in bulk.- Parameters:
dsDefs
- Array of data source definition objects.
-
addArchive
Adds single archive definition represented with object of classArcDef
.- Parameters:
arcDef
- Archive definition.- Throws:
IllegalArgumentException
- Thrown if archive with the same consolidation function and the same number of steps is already added.
-
addArchive
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.
-
addArchive
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 stepsrows
- Number of archive rows- Throws:
IllegalArgumentException
- Thrown if archive with the same consolidation function and the same number of steps is already added.
-
addArchive
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.
-
getDsDefs
Returns all data source definition objects specified so far.- Returns:
- Array of data source definition objects
-
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
Returns string that represents all specified RRD creation parameters. Returned string has the syntax of RRDTool'screate
command.- Returns:
- Dumped content of
RrdDb
object.
-
getRrdToolCommand
String getRrdToolCommand() -
removeDatasource
-
saveSingleDatasource
-
removeArchive
-
findArchive
-
exportXmlTemplate
Exports RrdDef object to output stream in XML format. Generated XML code can be parsed with
RrdDefTemplate
class.It use a format compatible with previous RRD4J's version, using a path, instead of an URI.
- Parameters:
out
- Output stream
-
exportXmlTemplate
Exports RrdDef object to output stream in XML format. Generated XML code can be parsed withRrdDefTemplate
class.If
compatible
is set to true, it returns an XML compatible with previous RRD4J's versions, using a path, instead of an URI.- Parameters:
out
- Output streamcompatible
- Compatible with previous versions.
-
exportXmlTemplate
Exports RrdDef object to string in XML format. Generated XML string can be parsed with
RrdDefTemplate
class.If
compatible
is set to true, it returns an XML compatible with previous RRD4J's versions, using a path, instead of an URI.- Parameters:
compatible
- Compatible with previous versions.- Returns:
- XML formatted string representing this RrdDef object
-
exportXmlTemplate
Exports RrdDef object to string in XML format. Generated XML string can be parsed with
RrdDefTemplate
class.It use a format compatible with previous RRD4J's version, using a path, instead of an URI.
- Returns:
- XML formatted string representing this RrdDef object
-
exportXmlTemplate
Exports RrdDef object to a file in XML format. Generated XML code can be parsed with
RrdDefTemplate
class.It use a format compatible with previous RRD4J's version, using a path, instead of an URI.
- Parameters:
filePath
- Path to the file- Throws:
IOException
- if any.
-
exportXmlTemplate
Exports RrdDef object to a file in XML format. Generated XML code can be parsed with
RrdDefTemplate
class.If
compatible
is set to true, it returns an XML compatible with previous RRD4J versions, using a path, instead of an URI.- Parameters:
filePath
- Path to the filecompatible
- Compatible with previous versions.- Throws:
IOException
- if any.
-
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
-
equals
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)
-
hashCode
public int hashCode() -
hasDatasources
public boolean hasDatasources()hasDatasources.
- Returns:
- a boolean.
-
hasArchives
public boolean hasArchives()hasArchives.
- Returns:
- a boolean.
-
removeDatasources
public void removeDatasources()Removes all datasource definitions. -
removeArchives
public void removeArchives()Removes all RRA archive definitions.
-