java.lang.Object
org.rrd4j.core.RrdDef
public class RrdDefextends 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
  • 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 the rrdcreate man page.

  • Field Summary

    Modifier and Type
    Field
    Description
    private final List<ArcDef>
    arcDefs
    The archives to create.
    static final long
    DEFAULT_INITIAL_SHIFT
    If not specified in constructor, starting timestamp will be set to current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10).
    static final long
    DEFAULT_STEP
    Default RRD step to be used if not specified in constructor (300 seconds).
    static final int
    DEFAULTVERSION
    Default RRD file format version.
    private final List<DsDef>
    dsDefs
    The data sources to create.
    private long
    startTime
    Time of the first step the file can hold.
    private long
    step
    Seconds between steps.
    private URI
    uri
    Where the RRD file will be created.
    private int
    version
    File format version to write.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RrdDef(String rrdpath)
    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.
    RrdDef(URI uri)
    Creates new RRD definition object with the given path.
    RrdDef(URI uri, long step)
    Creates new RRD definition object with the given path and step.
    RrdDef(URI uri, long startTime, long step)
    Creates new RRD definition object with the given path, starting timestamp and step.
    RrdDef(URI uri, long startTime, long step, int version)
    Creates new RRD definition object with the given path, starting timestamp, step and version.

  • 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(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 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, 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 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[] dsNames)
    Calculate estimated storage size
    String
    dump()
    Returns string that represents all specified RRD creation parameters.
    boolean
    equals(Object obj)
    String
    exportXmlTemplate()
    Exports RrdDef object to string in XML format.
    String
    exportXmlTemplate(boolean compatible)
    Exports RrdDef object to string in XML format.
    void
    exportXmlTemplate(OutputStream out)
    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.
    void
    exportXmlTemplate(XmlWriter xml, boolean compatible)
    Exports RrdDef object to output stream in XML format.
    (package private) ArcDef
    findArchive(ConsolFun consolFun, int steps)
    Searches the archive definitions for a matching consolidation and step count.
    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()
    Builds the rrdtool command line for this definition.
    long
    getStartTime()
    Returns starting time stamp for the RRD that should be created.
    long
    getStep()
    Returns time step for the RRD that will be created.
    URI
    getUri()
    Returns URI for the new RRD
    int
    getVersion()
    Returns the RRD file version
    boolean
    hasArchives()
    Tests whether any archive is defined.
    boolean
    hasDatasources()
    Tests whether any data source is defined.
    int
    hashCode()
    Hashes the archive definitions, data source definitions and step.
    (package private) void
    removeArchive(ConsolFun consolFun, int steps)
    Remove archive
    void
    removeArchives()
    Removes all RRA archive definitions.
    (package private) void
    removeDatasource(String dsName)
    Remove datasource
    void
    removeDatasources()
    Removes all datasource definitions.
    (package private) void
    saveSingleDatasource(String dsName)
    Save single datasource
    void
    setPath(String path)
    Sets path to RRD.
    void
    setPath(URI uri)
    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.

    Methods inherited from class Object

    clone, getClass, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_STEP

      public static final long DEFAULT_STEP
      Default RRD step to be used if not specified in constructor (300 seconds).
      See Also:

    • DEFAULT_INITIAL_SHIFT

      public static final long DEFAULT_INITIAL_SHIFT
      If not specified in constructor, starting timestamp will be set to current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10).
      See Also:

    • DEFAULTVERSION

      public static final int DEFAULTVERSION
      Default RRD file format version.
      See Also:

    • uri

      private URI uri
      Where the RRD file will be created.

    • startTime

      private long startTime
      Time of the first step the file can hold.

    • step

      private long step
      Seconds between steps.

    • version

      private int version
      File format version to write.

    • dsDefs

      private final List<DsDef> dsDefs
      The data sources to create.

    • arcDefs

      private final List<ArcDef> arcDefs
      The archives to create.

  • Constructor Details

    • RrdDef

      public RrdDef(String rrdpath)
      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

      public RrdDef(URI uri)
      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:
      uri - URI to the new RRD.

    • RrdDef

      public RrdDef(String path, long step)
      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 in seconds, must be positive.

    • RrdDef

      public RrdDef(URI uri, long step)
      Creates new RRD definition object with the given path and step.
      Parameters:
      uri - URI to new RRD.
      step - RRD step in seconds, must be positive.

    • RrdDef

      public RrdDef(String path, long startTime, long step)
      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 in seconds, must be positive.

    • RrdDef

      public RrdDef(URI uri, long startTime, long step)
      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 in seconds, must be positive.

    • RrdDef

      public RrdDef(String path, long startTime, long step, int version)
      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 in seconds, must be positive.
      version - RRD's file version.

    • RrdDef

      public RrdDef(URI uri, long startTime, long step, int version)
      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 in seconds, must be positive.
      version - RRD's file version.

  • Method Details

    • getPath

      public String 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.
      It's not a reliable way to resolve an file path. Instead, one should use Paths.get(def.getUri()) when the URI scheme is file.
      Returns:
      path to the new RRD which should be created

    • getUri

      public URI 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 in seconds

    • getVersion

      public int getVersion()
      Returns the RRD file version
      Returns:
      the RRD file format version

    • setPath

      public void setPath(String path)
      Sets path to RRD.

      The will be transformed internally to an URI using the default backend factory.

      Parameters:
      path - path to new RRD.

    • setPath

      public void setPath(URI uri)
      Sets URI to RRD.
      Parameters:
      uri - URI to new RRD.

    • setStartTime

      public void setStartTime(long startTime)
      Sets RRD's starting timestamp.
      Parameters:
      startTime - RRD starting timestamp in seconds since the epoch, not negative.

    • setStartTime

      public void setStartTime(Date date)
      Sets RRD's starting timestamp.
      Parameters:
      date - starting date, converted to a timestamp

    • setStartTime

      public void setStartTime(Calendar gc)
      Sets RRD's starting timestamp.
      Parameters:
      gc - starting date, converted to a timestamp

    • 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

      public void addDatasource(DsDef dsDef)
      Adds single datasource definition represented with object of class DsDef.
      Parameters:
      dsDef - Datasource definition to add, which must not already be present.

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

    • addDatasource

      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 the rrdcreate man page.

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

    • addDatasource

      public void addDatasource(DsDef... dsDefs)
      Adds data source definitions to RRD definition in bulk.
      Parameters:
      dsDefs - Array of data source definition objects.

    • addArchive

      public void addArchive(ArcDef arcDef)
      Adds single archive definition represented with object of class ArcDef.
      Parameters:
      arcDef - Archive definition to add.
      Throws:
      IllegalArgumentException - Thrown if archive with the same consolidation function and the same number of steps is already added.

    • addArchive

      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.

    • addArchive

      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 the rrdcreate man page.
      Parameters:
      consolFun - Consolidation function, must not duplicate an existing archive.
      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.

    • addArchive

      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.

    • 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()
      Builds the rrdtool command line for this definition.
      Returns:
      the command, identical to dump()

    • removeDatasource

      void removeDatasource(String dsName)
      Remove datasource
      Parameters:
      dsName - the name of the datasource to drop from this definition

    • saveSingleDatasource

      void saveSingleDatasource(String dsName)
      Save single datasource
      Parameters:
      dsName - the name of the one datasource to keep; every other is removed from this definition

    • removeArchive

      void removeArchive(ConsolFun consolFun, int steps)
      Remove archive
      Parameters:
      consolFun - the consolidation function of the archive to remove
      steps - the step count of the archive to remove

    • findArchive

      ArcDef findArchive(ConsolFun consolFun, int steps)
      Searches the archive definitions for a matching consolidation and step count.
      Parameters:
      consolFun - the consolidation function of the wanted archive
      steps - the step count of the wanted archive
      Returns:
      the matching archive definition

    • exportXmlTemplate

      public void exportXmlTemplate(OutputStream out)
      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 to write the XML template to

    • exportXmlTemplate

      public void exportXmlTemplate(OutputStream out, boolean compatible)
      Exports RrdDef object to output stream 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's versions, using a path, instead of an URI.

      Parameters:
      out - Output stream to write the XML template to
      compatible - Compatible with previous versions.

    • exportXmlTemplate

      public void exportXmlTemplate(XmlWriter xml, boolean compatible)
      Exports RrdDef object to output stream 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's versions, using a path, instead of an URI.

      Parameters:
      xml - XML writer to emit the template through, not closed here
      compatible - Compatible with previous versions.

    • exportXmlTemplate

      public String exportXmlTemplate(boolean compatible)
      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

      public String 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

      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.

      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 the file cannot be written.

    • exportXmlTemplate

      public void exportXmlTemplate(String filePath, boolean compatible) throws IOException
      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 file
      compatible - Compatible with previous versions.
      Throws:
      IOException - if the file cannot be written.

    • 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, String[] dsNames)
      Calculate estimated storage size
      Parameters:
      dsCount - the number of datasources the archive stores
      arcCount - the number of archives defined over the time range
      rowsCount - the total number of rows across those archives
      dsNames - the datasource names, whose length beyond the fixed string size adds to the stored payload
      Returns:
      the estimated size in bytes of the resulting RRD file

    • 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

    • hashCode

      public int hashCode()
      Hashes the archive definitions, data source definitions and step.
      Overrides:
      hashCode in class Object

    • hasDatasources

      public boolean hasDatasources()
      Tests whether any data source is defined.
      Returns:
      true if at least one datasource is defined

    • hasArchives

      public boolean hasArchives()
      Tests whether any archive is defined.
      Returns:
      true if at least one archive (consolidation source) is defined

    • removeDatasources

      public void removeDatasources()
      Removes all datasource definitions.

    • removeArchives

      public void removeArchives()
      Removes all RRA archive definitions.