org.jrobin.core
Class RrdToolkit

java.lang.Object
  org.jrobin.core.RrdToolkit

public class RrdToolkit
extends 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).

Constructor Summary

RrdToolkit()

Method Summary

static void	addArchive(String sourcePath, ArcDef newArchive, boolean saveBackup) Adds one more archive to a RRD file.
static void	addArchive(String sourcePath, String destPath, ArcDef newArchive) Creates a new RRD file with one more archive in it.
static void	addDatasource(String sourcePath, DsDef newDatasource, boolean saveBackup) Adds one more datasource 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 int	forceZerosForNans(String sourcePath, String dsName) Updates single or all datasource names in the specified RRD file by appending '!' (if not already present).
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 consolFun, int steps, boolean saveBackup) Removes one archive from a RRD file.
static void	removeArchive(String sourcePath, String destPath, String consolFun, int steps) Creates a new RRD file with one archive removed.
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 consolFun, int numSteps, int newRows, boolean saveBackup) Modifies existing RRD file, by resizing its chosen archive.
static void	resizeArchive(String sourcePath, String destPath, String 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	setArcXff(String sourcePath, String 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.

Methods inherited from class java.lang.Object

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

Constructor Detail

RrdToolkit

public RrdToolkit()

Method Detail

addDatasource

public static void addDatasource(String sourcePath,
                                 String destPath,
                                 DsDef newDatasource)
                          throws IOException,
                                 RrdException

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

RrdException - Thrown in case of JRobin specific error

addDatasource

public static void addDatasource(String sourcePath,
                                 DsDef newDatasource,
                                 boolean saveBackup)
                          throws IOException,
                                 RrdException

Adds one more datasource to a RRD file.

WARNING: This method is potentialy 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

RrdException - Thrown in case of JRobin specific error

removeDatasource

public static void removeDatasource(String sourcePath,
                                    String destPath,
                                    String dsName)
                             throws IOException,
                                    RrdException

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

RrdException - Thrown in case of JRobin specific error

removeDatasource

public static void removeDatasource(String sourcePath,
                                    String dsName,
                                    boolean saveBackup)
                             throws IOException,
                                    RrdException

Removes single datasource from a RRD file.

WARNING: This method is potentialy 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

RrdException - Thrown in case of JRobin specific error

renameDatasource

public static void renameDatasource(String sourcePath,
                                    String oldDsName,
                                    String newDsName)
                             throws IOException,
                                    RrdException

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

RrdException - Thrown in case of JRobin specific error (invalid path or datasource names, for example)

forceZerosForNans

public static int forceZerosForNans(String sourcePath,
                                    String dsName)
                             throws IOException,
                                    RrdException

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

RrdException - Thrown in case of JRobin specific error (invalid path or datasource name, for example)

addArchive

public static void addArchive(String sourcePath,
                              String destPath,
                              ArcDef newArchive)
                       throws IOException,
                              RrdException

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

RrdException - Thrown in case of JRobin specific error

addArchive

public static void addArchive(String sourcePath,
                              ArcDef newArchive,
                              boolean saveBackup)
                       throws IOException,
                              RrdException

Adds one more archive to a RRD file.

WARNING: This method is potentialy 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

RrdException - Thrown in case of JRobin specific error

removeArchive

public static void removeArchive(String sourcePath,
                                 String destPath,
                                 String consolFun,
                                 int steps)
                          throws IOException,
                                 RrdException

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

RrdException - Thrown in case of JRobin specific error

removeArchive

public static void removeArchive(String sourcePath,
                                 String consolFun,
                                 int steps,
                                 boolean saveBackup)
                          throws IOException,
                                 RrdException

Removes one archive from a RRD file.

WARNING: This method is potentialy 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

RrdException - Thrown in case of JRobin specific error

setDsHeartbeat

public static void setDsHeartbeat(String sourcePath,
                                  String datasourceName,
                                  long newHeartbeat)
                           throws RrdException,
                                  IOException

Sets datasource heartbeat to a new value.

Parameters:

sourcePath - Path to exisiting RRD file (will be updated)

datasourceName - Name of the datasource in the specified RRD file

newHeartbeat - New datasource heartbeat

Throws:

RrdException - Thrown in case of JRobin specific error

IOException - Thrown in case of I/O error

setDsHeartbeat

public static void setDsHeartbeat(String sourcePath,
                                  int dsIndex,
                                  long newHeartbeat)
                           throws RrdException,
                                  IOException

Sets datasource heartbeat to a new value.

Parameters:

sourcePath - Path to exisiting RRD file (will be updated)

dsIndex - Index of the datasource in the specified RRD file

newHeartbeat - New datasource heartbeat

Throws:

RrdException - Thrown in case of JRobin specific error

IOException - Thrown in case of I/O error

setDsMinValue

public static void setDsMinValue(String sourcePath,
                                 String datasourceName,
                                 double newMinValue,
                                 boolean filterArchivedValues)
                          throws RrdException,
                                 IOException

Sets datasource min value to a new value

Parameters:

sourcePath - Path to exisiting 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:

RrdException - Thrown in case of JRobin specific error

IOException - Thrown in case of I/O error

setDsMaxValue

public static void setDsMaxValue(String sourcePath,
                                 String datasourceName,
                                 double newMaxValue,
                                 boolean filterArchivedValues)
                          throws RrdException,
                                 IOException

Sets datasource max value to a new value.

Parameters:

sourcePath - Path to exisiting 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:

RrdException - Thrown in case of JRobin specific error

IOException - Thrown in case of I/O error

setDsMinMaxValue

public static void setDsMinMaxValue(String sourcePath,
                                    String datasourceName,
                                    double newMinValue,
                                    double newMaxValue,
                                    boolean filterArchivedValues)
                             throws RrdException,
                                    IOException

Updates valid value range for the given datasource.

Parameters:

sourcePath - Path to exisiting 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:

RrdException - Thrown in case of JRobin specific error

IOException - Thrown in case of I/O error

setArcXff

public static void setArcXff(String sourcePath,
                             String consolFun,
                             int steps,
                             double newXff)
                      throws RrdException,
                             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 sptes of the target archive

newXff - New X-files factor for the target archive

Throws:

RrdException - Thrown in case of JRobin specific error

IOException - Thrown in case of I/O error

resizeArchive

public static void resizeArchive(String sourcePath,
                                 String destPath,
                                 String consolFun,
                                 int numSteps,
                                 int newRows)
                          throws IOException,
                                 RrdException

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

RrdException - Thrown in case of JRobin specific error

resizeArchive

public static void resizeArchive(String sourcePath,
                                 String consolFun,
                                 int numSteps,
                                 int newRows,
                                 boolean saveBackup)
                          throws IOException,
                                 RrdException

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

RrdException - Thrown in case of JRobin specific error

split

public static void split(String sourcePath)
                  throws IOException,
                         RrdException

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

RrdException - Thrown in case of JRobin specific 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 - Source directory

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