java.lang.Object
org.rrd4j.core.RrdToolkit
public class RrdToolkitextends Object
Class used to perform various complex operations on RRD files. Use an instance of the RrdToolkit class to:
  • add datasource to a RRD file.
  • add archive to a RRD file.
  • remove datasource from a RRD file.
  • remove archive from a RRD file.
All these operations can be performed on the copy of the original RRD file, or on the original file itself (with possible backup file creation).

IMPORTANT: NEVER use methods found in this class on 'live' RRD files (files which are currently in use).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final String
    SOURCE_AND_DESTINATION_PATHS_ARE_THE_SAME
    Error text when a copy would overwrite its own source.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    RrdToolkit()
    Utility class, not intended for instantiation.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    addArchive(String sourcePath, String destPath, ArcDef newArchive)
    Creates a new RRD file with one more archive in it.
    static void
    addArchive(String sourcePath, ArcDef newArchive, boolean saveBackup)
    Adds one more archive to a RRD file.
    static void
    addDatasource(String sourcePath, String destPath, DsDef newDatasource)
    Creates a new RRD file with one more datasource in it.
    static void
    addDatasource(String sourcePath, DsDef newDatasource, boolean saveBackup)
    Adds one more datasource to a RRD file.
    static void
    addDatasources(String sourcePath, Iterable<DsDef> newDatasources, boolean saveBackup)
    Adds datasources to a RRD file.
    static void
    addDatasources(String sourcePath, String destPath, Iterable<DsDef> newDatasources)
    Creates a new RRD file with one more datasource in it.
    private static void
    copyFile(String sourcePath, String destPath, boolean saveBackup)
    Copies a file, keeping a backup when asked.
    private static String
    createSplitPath(String dsName, String sourcePath)
    Names the file a split-out data source is written to.
    static int
    forceZerosForNans(String sourcePath, String dsName)
    Updates single or all datasource names in the specified RRD file by appending '!' (if not already present).
    private static String
    getBackupPath(String destPath)
    Names the backup for a file about to be overwritten.
    static String[]
    getCanonicalPaths(String directory, String extension, boolean resursive)
    Returns list of canonical file names with the specified extension in the given directory.
    static void
    removeArchive(String sourcePath, String destPath, ConsolFun consolFun, int steps)
    Creates a new RRD file with one archive removed.
    static void
    removeArchive(String sourcePath, ConsolFun consolFun, int steps, boolean saveBackup)
    Removes one archive from a RRD file.
    static void
    removeDatasource(String sourcePath, String dsName, boolean saveBackup)
    Removes single datasource from a RRD file.
    static void
    removeDatasource(String sourcePath, String destPath, String dsName)
    Creates a new RRD file with one datasource removed.
    static void
    renameDatasource(String sourcePath, String oldDsName, String newDsName)
    Renames single datasource in the given RRD file.
    static void
    resizeArchive(String sourcePath, String destPath, ConsolFun consolFun, int numSteps, int newRows)
    Creates new RRD file based on the existing one, but with a different size (number of rows) for a single archive.
    static void
    resizeArchive(String sourcePath, ConsolFun consolFun, int numSteps, int newRows, boolean saveBackup)
    Modifies existing RRD file, by resizing its chosen archive.
    static void
    setArcXff(String sourcePath, ConsolFun consolFun, int steps, double newXff)
    Sets single archive's X-files factor to a new value.
    static void
    setDsHeartbeat(String sourcePath, int dsIndex, long newHeartbeat)
    Sets datasource heartbeat to a new value.
    static void
    setDsHeartbeat(String sourcePath, String datasourceName, long newHeartbeat)
    Sets datasource heartbeat to a new value.
    static void
    setDsMaxValue(String sourcePath, String datasourceName, double newMaxValue, boolean filterArchivedValues)
    Sets datasource max value to a new value.
    static void
    setDsMinMaxValue(String sourcePath, String datasourceName, double newMinValue, double newMaxValue, boolean filterArchivedValues)
    Updates valid value range for the given datasource.
    static void
    setDsMinValue(String sourcePath, String datasourceName, double newMinValue, boolean filterArchivedValues)
    Sets datasource min value to a new value
    static void
    split(String sourcePath)
    Splits single RRD file with several datasources into a number of smaller RRD files with a single datasource in it.
    private static void
    traverseDirectory(File directory, String extension, boolean recursive, List<String> list)
    Collects the canonical paths of the files with a given extension, descending into subdirectories when asked.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • SOURCE_AND_DESTINATION_PATHS_ARE_THE_SAME

      private static final String SOURCE_AND_DESTINATION_PATHS_ARE_THE_SAME
      Error text when a copy would overwrite its own source.
      See Also:

  • Constructor Details

    • RrdToolkit

      private RrdToolkit()
      Utility class, not intended for instantiation.

  • Method Details

    • addDatasource

      public static void addDatasource(String sourcePath, String destPath, DsDef newDatasource) throws IOException
      Creates a new RRD file with one more datasource in it. RRD file is created based on the existing one (the original RRD file is not modified at all). All data from the original RRD file is copied to the new one.
      Parameters:
      sourcePath - path to a RRD file to import data from (will not be modified)
      destPath - path to a new RRD file (will be created)
      newDatasource - Datasource definition to be added to the new RRD file
      Throws:
      IOException - Thrown in case of I/O error

    • addDatasources

      public static void addDatasources(String sourcePath, String destPath, Iterable<DsDef> newDatasources) throws IOException
      Creates a new RRD file with one more datasource in it. RRD file is created based on the existing one (the original RRD file is not modified at all). All data from the original RRD file is copied to the new one.
      Parameters:
      sourcePath - path to a RRD file to import data from (will not be modified)
      destPath - path to a new RRD file (will be created)
      newDatasources - Datasource definitions to be added to the new RRD file
      Throws:
      IOException - Thrown in case of I/O error

    • addDatasource

      public static void addDatasource(String sourcePath, DsDef newDatasource, boolean saveBackup) throws IOException
      Adds one more datasource to a RRD file.

      WARNING: This method is potentially dangerous! It will modify your RRD file. It is highly recommended to preserve the original RRD file (saveBackup should be set to true ). The backup file will be created in the same directory as the original one with .bak extension added to the original name.

      Before applying this method, be sure that the specified RRD file is not in use (not open)

      Parameters:
      sourcePath - path to a RRD file to add datasource to.
      newDatasource - Datasource definition to be added to the RRD file
      saveBackup - true, if backup of the original file should be created; false, otherwise
      Throws:
      IOException - Thrown in case of I/O error

    • addDatasources

      public static void addDatasources(String sourcePath, Iterable<DsDef> newDatasources, boolean saveBackup) throws IOException
      Adds datasources to a RRD file.

      WARNING: This method is potentially dangerous! It will modify your RRD file. It is highly recommended to preserve the original RRD file (saveBackup should be set to true ). The backup file will be created in the same directory as the original one with .bak extension added to the original name.

      Before applying this method, be sure that the specified RRD file is not in use (not open)

      Parameters:
      sourcePath - path to a RRD file to add datasource to.
      newDatasources - Datasource definitions to be added to the RRD file
      saveBackup - true, if backup of the original file should be created; false, otherwise
      Throws:
      IOException - Thrown in case of I/O error

    • removeDatasource

      public static void removeDatasource(String sourcePath, String destPath, String dsName) throws IOException
      Creates a new RRD file with one datasource removed. RRD file is created based on the existing one (the original RRD file is not modified at all). All remaining data from the original RRD file is copied to the new one.
      Parameters:
      sourcePath - path to a RRD file to import data from (will not be modified)
      destPath - path to a new RRD file (will be created)
      dsName - Name of the Datasource to be removed from the new RRD file
      Throws:
      IOException - Thrown in case of I/O error

    • removeDatasource

      public static void removeDatasource(String sourcePath, String dsName, boolean saveBackup) throws IOException
      Removes single datasource from a RRD file.

      WARNING: This method is potentially dangerous! It will modify your RRD file. It is highly recommended to preserve the original RRD file (saveBackup should be set to true ). The backup file will be created in the same directory as the original one with .bak extension added to the original name.

      Before applying this method, be sure that the specified RRD file is not in use (not open)

      Parameters:
      sourcePath - path to a RRD file to remove datasource from.
      dsName - Name of the Datasource to be removed from the RRD file
      saveBackup - true, if backup of the original file should be created; false, otherwise
      Throws:
      IOException - Thrown in case of I/O error

    • renameDatasource

      public static void renameDatasource(String sourcePath, String oldDsName, String newDsName) throws IOException
      Renames single datasource in the given RRD file.
      Parameters:
      sourcePath - Path to a RRD file
      oldDsName - Old datasource name
      newDsName - New datasource name
      Throws:
      IOException - Thrown in case of I/O error

    • forceZerosForNans

      public static int forceZerosForNans(String sourcePath, String dsName) throws IOException
      Updates single or all datasource names in the specified RRD file by appending '!' (if not already present). Datasources with names ending with '!' will never store NaNs in RRA archives (zero value will be used instead). Might be useful from time to time
      Parameters:
      sourcePath - Path to a RRD file
      dsName - Datasource name or null if you want to rename all datasources
      Returns:
      Number of datasources successfully renamed
      Throws:
      IOException - Thrown in case of I/O error

    • addArchive

      public static void addArchive(String sourcePath, String destPath, ArcDef newArchive) throws IOException
      Creates a new RRD file with one more archive in it. RRD file is created based on the existing one (the original RRD file is not modified at all). All data from the original RRD file is copied to the new one.
      Parameters:
      sourcePath - path to a RRD file to import data from (will not be modified)
      destPath - path to a new RRD file (will be created)
      newArchive - Archive definition to be added to the new RRD file
      Throws:
      IOException - Thrown in case of I/O error

    • addArchive

      public static void addArchive(String sourcePath, ArcDef newArchive, boolean saveBackup) throws IOException
      Adds one more archive to a RRD file.

      WARNING: This method is potentially dangerous! It will modify your RRD file. It is highly recommended to preserve the original RRD file (saveBackup should be set to true ). The backup file will be created in the same directory as the original one with .bak extension added to the original name.

      Before applying this method, be sure that the specified RRD file is not in use (not open)

      Parameters:
      sourcePath - path to a RRD file to add datasource to.
      newArchive - Archive definition to be added to the RRD file
      saveBackup - true, if backup of the original file should be created; false, otherwise
      Throws:
      IOException - Thrown in case of I/O error

    • removeArchive

      public static void removeArchive(String sourcePath, String destPath, ConsolFun consolFun, int steps) throws IOException
      Creates a new RRD file with one archive removed. RRD file is created based on the existing one (the original RRD file is not modified at all). All relevant data from the original RRD file is copied to the new one.
      Parameters:
      sourcePath - path to a RRD file to import data from (will not be modified)
      destPath - path to a new RRD file (will be created)
      consolFun - Consolidation function of Archive which should be removed
      steps - Number of steps for Archive which should be removed
      Throws:
      IOException - Thrown in case of I/O error

    • removeArchive

      public static void removeArchive(String sourcePath, ConsolFun consolFun, int steps, boolean saveBackup) throws IOException
      Removes one archive from a RRD file.

      WARNING: This method is potentially dangerous! It will modify your RRD file. It is highly recommended to preserve the original RRD file (saveBackup should be set to true ). The backup file will be created in the same directory as the original one with .bak extension added to the original name.

      Before applying this method, be sure that the specified RRD file is not in use (not open)

      Parameters:
      sourcePath - path to a RRD file to add datasource to.
      consolFun - Consolidation function of Archive which should be removed
      steps - Number of steps for Archive which should be removed
      saveBackup - true, if backup of the original file should be created; false, otherwise
      Throws:
      IOException - Thrown in case of I/O error

    • copyFile

      private static void copyFile(String sourcePath, String destPath, boolean saveBackup) throws IOException
      Copies a file, keeping a backup when asked.
      Parameters:
      sourcePath - the file to read
      destPath - where to write it
      saveBackup - true to keep the file being overwritten
      Throws:
      RrdException - if the copy fails
      IOException

    • getBackupPath

      private static String getBackupPath(String destPath)
      Names the backup for a file about to be overwritten.
      Parameters:
      destPath - the file being overwritten
      Returns:
      the backup's path

    • setDsHeartbeat

      public static void setDsHeartbeat(String sourcePath, String datasourceName, long newHeartbeat) throws IOException
      Sets datasource heartbeat to a new value.
      Parameters:
      sourcePath - Path to existing RRD file (will be updated)
      datasourceName - Name of the datasource in the specified RRD file
      newHeartbeat - New datasource heartbeat
      Throws:
      IOException - Thrown in case of I/O error

    • setDsHeartbeat

      public static void setDsHeartbeat(String sourcePath, int dsIndex, long newHeartbeat) throws IOException
      Sets datasource heartbeat to a new value.
      Parameters:
      sourcePath - Path to existing RRD file (will be updated)
      dsIndex - Index of the datasource in the specified RRD file
      newHeartbeat - New datasource heartbeat
      Throws:
      IOException - Thrown in case of I/O error

    • setDsMinValue

      public static void setDsMinValue(String sourcePath, String datasourceName, double newMinValue, boolean filterArchivedValues) throws IOException
      Sets datasource min value to a new value
      Parameters:
      sourcePath - Path to existing RRD file (will be updated)
      datasourceName - Name of the datasource in the specified RRD file
      newMinValue - New min value for the datasource
      filterArchivedValues - set to true if archived values less than newMinValue should be set to NaN; set to false, otherwise.
      Throws:
      IOException - Thrown in case of I/O error

    • setDsMaxValue

      public static void setDsMaxValue(String sourcePath, String datasourceName, double newMaxValue, boolean filterArchivedValues) throws IOException
      Sets datasource max value to a new value.
      Parameters:
      sourcePath - Path to existing RRD file (will be updated)
      datasourceName - Name of the datasource in the specified RRD file
      newMaxValue - New max value for the datasource
      filterArchivedValues - set to true if archived values greater than newMaxValue should be set to NaN; set to false, otherwise.
      Throws:
      IOException - Thrown in case of I/O error

    • setDsMinMaxValue

      public static void setDsMinMaxValue(String sourcePath, String datasourceName, double newMinValue, double newMaxValue, boolean filterArchivedValues) throws IOException
      Updates valid value range for the given datasource.
      Parameters:
      sourcePath - Path to existing RRD file (will be updated)
      datasourceName - Name of the datasource in the specified RRD file
      newMinValue - New min value for the datasource
      newMaxValue - New max value for the datasource
      filterArchivedValues - set to true if archived values outside of the specified min/max range should be replaced with NaNs.
      Throws:
      IOException - Thrown in case of I/O error

    • setArcXff

      public static void setArcXff(String sourcePath, ConsolFun consolFun, int steps, double newXff) throws IOException
      Sets single archive's X-files factor to a new value.
      Parameters:
      sourcePath - Path to existing RRD file (will be updated)
      consolFun - Consolidation function of the target archive
      steps - Number of steps of the target archive
      newXff - New X-files factor for the target archive
      Throws:
      IOException - Thrown in case of I/O error

    • resizeArchive

      public static void resizeArchive(String sourcePath, String destPath, ConsolFun consolFun, int numSteps, int newRows) throws IOException
      Creates new RRD file based on the existing one, but with a different size (number of rows) for a single archive. The archive to be resized is identified by its consolidation function and the number of steps.
      Parameters:
      sourcePath - Path to the source RRD file (will not be modified)
      destPath - Path to the new RRD file (will be created)
      consolFun - Consolidation function of the archive to be resized
      numSteps - Number of steps of the archive to be resized
      newRows - New archive size (number of archive rows)
      Throws:
      IOException - Thrown in case of I/O error

    • resizeArchive

      public static void resizeArchive(String sourcePath, ConsolFun consolFun, int numSteps, int newRows, boolean saveBackup) throws IOException
      Modifies existing RRD file, by resizing its chosen archive. The archive to be resized is identified by its consolidation function and the number of steps.
      Parameters:
      sourcePath - Path to the RRD file (will be modified)
      consolFun - Consolidation function of the archive to be resized
      numSteps - Number of steps of the archive to be resized
      newRows - New archive size (number of archive rows)
      saveBackup - true, if backup of the original file should be created; false, otherwise
      Throws:
      IOException - Thrown in case of I/O error

    • split

      public static void split(String sourcePath) throws IOException
      Splits single RRD file with several datasources into a number of smaller RRD files with a single datasource in it. All archived values are preserved. If you have a RRD file named 'traffic.rrd' with two datasources, 'in' and 'out', this method will create two files (with a single datasource, in the same directory) named 'in-traffic.rrd' and 'out-traffic.rrd'.
      Parameters:
      sourcePath - Path to a RRD file with multiple datasources defined
      Throws:
      IOException - Thrown in case of I/O error

    • getCanonicalPaths

      public static String[] getCanonicalPaths(String directory, String extension, boolean resursive) throws IOException
      Returns list of canonical file names with the specified extension in the given directory. This method is not RRD related, but might come handy to create a quick list of all RRD files in the given directory.
      Parameters:
      directory - the directory to search; it must exist, else an RrdException
      extension - File extension (like ".rrd", ".jrb", ".rrd.jrb")
      resursive - true if all subdirectories should be traversed for the same extension, false otherwise
      Returns:
      Array of sorted canonical file names with the given extension
      Throws:
      IOException - Thrown in case of I/O error

    • traverseDirectory

      private static void traverseDirectory(File directory, String extension, boolean recursive, List<String> list) throws IOException
      Collects the canonical paths of the files with a given extension, descending into subdirectories when asked.
      Parameters:
      directory - the directory to walk
      extension - the file extension to look for, e.g. ".rrd"
      recursive - true to descend into subdirectories
      list - where the paths found are collected, in encounter order
      Throws:
      IOException - if a directory cannot be read

    • createSplitPath

      private static String createSplitPath(String dsName, String sourcePath)
      Names the file a split-out data source is written to.
      Parameters:
      dsName - the data source's name
      sourcePath - the file being split
      Returns:
      the new file's path