org.rrd4j.core

## Class RrdDb

- java.lang.Object
- - org.rrd4j.core.RrdDb

- All Implemented Interfaces:
    Closeable, AutoCloseable, RrdUpdater<RrdDb>

      public class RrdDb
      extends Object
      implements RrdUpdater<RrdDb>, Closeable

  Main class used to create and manipulate round robin databases (RRDs). Use this class to perform update and fetch operations on existing RRDs, to create new RRD from the definition (object of class `RrdDef`) or from XML file (dumped content of RRDTool's or Rrd4j's RRD file).

  Each RRD is backed with some kind of storage. For example, RRDTool supports only one kind of storage (disk file). On the contrary, Rrd4j gives you freedom to use other storage (backend) types even to create your own backend types for some special purposes. Rrd4j by default stores RRD data in files (as RRDTool), but you might choose to store RRD data in memory (this is supported in Rrd4j), to use java.nio.* instead of java.io.* package for file manipulation (also supported) or to store whole RRDs in the SQL database (you'll have to extend some classes to do this).

  Note that Rrd4j uses binary format different from RRDTool's format. You cannot use this class to manipulate RRD files created with RRDTool. However, if you perform the same sequence of create, update and fetch operations, you will get exactly the same results from Rrd4j and RRDTool.

  You will not be able to use Rrd4j API if you are not familiar with basic RRDTool concepts. Good place to start is the official RRD tutorial and relevant RRDTool man pages: rrdcreate, rrdupdate, rrdfetch and rrdgraph. For RRDTool's advanced graphing capabilities (RPN extensions), also supported in Rrd4j, there is an excellent CDEF tutorial.

  See Also:
    `RrdBackend`, `RrdBackendFactory`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `RrdDb.Builder` Builder for `RrdDb` instances.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `PREFIX_RRDTool` Prefix to identify external RRDTool file source used in various RrdDb constructors.
    `static String` | `PREFIX_XML` Prefix to identify external XML file source used in various RrdDb constructors.
    `(package private) static int` | `XML_BUFFER_CAPACITY`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) void` | `archive(Datasource datasource, double value, double lastValue, long numUpdates)`
    `void` | `close()` Closes RRD.
    `boolean` | `containsDs(String dsName)` Checks presence of a specific datasource.
    `void` | `copyStateTo(RrdDb otherRrd)` copyStateTo.
    `FetchRequest` | `createFetchRequest(ConsolFun consolFun, long fetchStart, long fetchEnd)` Prepares fetch request to be executed on this RRD.
    `FetchRequest` | `createFetchRequest(ConsolFun consolFun, long fetchStart, long fetchEnd, long resolution)` Prepares fetch request to be executed on this RRD.
    `Sample` | `createSample()` Creates new sample with the current timestamp and all data source values set to 'unknown'.
    `Sample` | `createSample(long time)` Creates new sample with the given timestamp and all datasource values set to 'unknown'.
    `String` | `dump()` Returns string representing complete internal RRD state.
    `void` | `dumpXml(OutputStream destination)` Writes the RRD content to `OutputStream` using XML format.
    `void` | `dumpXml(String filename)` Dumps internal RRD state to XML file.
    `void` | `dumpXml(XmlWriter writer)` Writes the RRD content to `XmlWriter` using XML format.
    `String` | `exportXml()` This method is just an alias for `getXml` method.
    `void` | `exportXml(OutputStream destination)` This method is just an alias for `dumpXml` method.
    `void` | `exportXml(String filename)` This method is just an alias for `dumpXml(String)` method.
    `(package private) FetchData` | `fetchData(FetchRequest request)`
    `Archive` | `findMatchingArchive(FetchRequest request)` findMatchingArchive.
    `Archive` | `findStartMatchArchive(String consolFun, long startTime, long resolution)` Finds the archive that best matches to the start time (time period being start-time until now) and requested resolution.
    `int` | `getArcCount()` Returns the number of RRA archives defined in the file
    `Archive` | `getArchive(ConsolFun consolFun, int steps)` Returns Archive object with the given consolidation function and the number of steps.
    `Archive` | `getArchive(int arcIndex)` Returns Archive object for the given archive index.
    `(package private) Archive[]` | `getArchives()`
    `int` | `getArcIndex(ConsolFun consolFun, int steps)` Returns index of Archive object with the given consolidation function and the number of steps.
    `static RrdDb.Builder` | `getBuilder()`
    `byte[]` | `getBytes()` Returns an array of bytes representing the whole RRD.
    `String` | `getCanonicalPath()` Returns canonical path to the underlying RRD file.
    `URI` | `getCanonicalUri()`
    `Datasource` | `getDatasource(int dsIndex)` Returns Datasource object for the given datasource index.
    `Datasource` | `getDatasource(String dsName)` Returns Datasource object corresponding to the given datasource name.
    `(package private) Datasource[]` | `getDatasources()`
    `int` | `getDsCount()` Returns the number of datasources defined in the file
    `int` | `getDsIndex(String dsName)` Returns internal index number for the given datasource name.
    `String[]` | `getDsNames()` Returns an array of datasource names defined in RRD.
    `Header` | `getHeader()` Returns RRD header.
    `String` | `getInfo()` getInfo.
    `long` | `getLastArchiveUpdateTime()` Returns the last time when some of the archives in this RRD was updated.
    `double` | `getLastDatasourceValue(String dsName)` Returns the last stored value for the given datasource.
    `double[]` | `getLastDatasourceValues()` Returns an array of last datasource values.
    `long` | `getLastUpdateTime()` Returns time of last update operation as timestamp (in seconds).
    `String` | `getPath()` Returns the path to this RRD.
    `RrdAllocator` | `getRrdAllocator()` Required to implement RrdUpdater interface.
    `RrdBackend` | `getRrdBackend()` Returns backend object for this RRD which performs actual I/O operations.
    `RrdDef` | `getRrdDef()` Returns RRD definition object which can be used to create new RRD with the same creation parameters but with no data in it.
    `URI` | `getUri()` Returns the URI to this RRD, as seen by the backend.
    `String` | `getXml()` Returns string representing internal RRD state in XML format.
    `(package private) void` | `internalClose()`
    `boolean` | `isClosed()` Returns true if the RRD is closed.
    `static void` | `main(String[] args)` main.
    `static RrdDb` | `of(RrdDef rrdDef)` Returns a new RRD object from the definition.
    `static RrdDb` | `of(String path)` Opens an existing RRD with read/write access.
    `static RrdDb` | `of(URI uri)` Opens an existing RRD with read/write access.
    `void` | `setInfo(String info)` setInfo.
    `(package private) void` | `store(Sample sample)`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### PREFIX_RRDTool

          public static final String PREFIX_RRDTool

      Prefix to identify external RRDTool file source used in various RrdDb constructors.
      See Also:
        Constant Field Values

    - #### PREFIX_XML

          public static final String PREFIX_XML

      Prefix to identify external XML file source used in various RrdDb constructors.
      See Also:
        Constant Field Values

    - #### XML_BUFFER_CAPACITY

          static final int XML_BUFFER_CAPACITY

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### archive

          final void archive(Datasource datasource,
                             double value,
                             double lastValue,
                             long numUpdates)
                      throws IOException

      Throws:
        `IOException`

    - #### close

          public void close()
                     throws IOException

      Closes RRD. No further operations are allowed on this RrdDb object.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `IOException` - Thrown in case of I/O related error.
        `IllegalStateException` - if the thread was interrupted in pool usage.

    - #### containsDs

          public boolean containsDs(String dsName)
                             throws IOException

      Checks presence of a specific datasource.
      Parameters:
        `dsName` - Datasource name to check
      Returns:
        `true` if datasource is present in this RRD, `false` otherwise
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### copyStateTo

          public void copyStateTo(RrdDb otherRrd)
                           throws IOException

      copyStateTo.

      Copies object's internal state to another RrdDb object.

      Specified by:
        `copyStateTo` in interface `RrdUpdater<RrdDb>`
      Parameters:
        `otherRrd` - a `RrdUpdater` object.
      Throws:
        `IOException` - if any.

    - #### createFetchRequest

          public FetchRequest createFetchRequest(ConsolFun consolFun,
                                                 long fetchStart,
                                                 long fetchEnd)

      Prepares fetch request to be executed on this RRD. Use returned `FetchRequest` object and its `fetchData()` method to actually fetch data from this RRD. Data will be fetched with the smallest possible resolution (see RRDTool's rrdfetch man page for the explanation of the resolution parameter).
      Parameters:
        `consolFun` - Consolidation function to be used in fetch request.
        `fetchStart` - Starting timestamp for fetch request.
        `fetchEnd` - Ending timestamp for fetch request.
      Returns:
        Request object that should be used to actually fetch data from RRD.

    - #### createFetchRequest

          public FetchRequest createFetchRequest(ConsolFun consolFun,
                                                 long fetchStart,
                                                 long fetchEnd,
                                                 long resolution)

      Prepares fetch request to be executed on this RRD. Use returned `FetchRequest` object and its `fetchData()` method to actually fetch data from the RRD file.
      Parameters:
        `consolFun` - Consolidation function to be used in fetch request.
        `fetchStart` - Starting timestamp for fetch request.
        `fetchEnd` - Ending timestamp for fetch request.
        `resolution` - Fetch resolution (see RRDTool's rrdfetch man page for an explanation of this parameter.
      Returns:
        Request object that should be used to actually fetch data from RRD

    - #### createSample

          public Sample createSample()
                              throws IOException

      Creates new sample with the current timestamp and all data source values set to 'unknown'. Use returned `Sample` object to specify datasource values for the current timestamp. See documentation for `Sample` for an explanation how to do this.

      Once populated with data source values, call Sample's `update()` method to actually store sample in the RRD associated with it.

      Returns:
        Fresh sample with the current timestamp and all data source values set to 'unknown'.
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### createSample

          public Sample createSample(long time)
                              throws IOException

      Creates new sample with the given timestamp and all datasource values set to 'unknown'. Use returned `Sample` object to specify datasource values for the given timestamp. See documentation for `Sample` for an explanation how to do this.

      Once populated with data source values, call Sample's `update()` method to actually store sample in the RRD associated with it.

      Parameters:
        `time` - Sample timestamp rounded to the nearest second (without milliseconds).
      Returns:
        Fresh sample with the given timestamp and all data source values set to 'unknown'.
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### dump

          public String dump()
                      throws IOException

      Returns string representing complete internal RRD state. The returned string can be printed to `stdout` and/or used for debugging purposes.
      Returns:
        String representing internal RRD state.
      Throws:
        `IOException` - Thrown in case of I/O related error.

    - #### dumpXml

          public void dumpXml(OutputStream destination)
                       throws IOException

      Writes the RRD content to `OutputStream` using XML format. This format is fully compatible with RRDTool's XML dump format and can be used for conversion purposes or debugging.
      Parameters:
        `destination` - Output stream to receive XML data
      Throws:
        `IOException` - Thrown in case of I/O related error

    - #### dumpXml

          public void dumpXml(String filename)
                       throws IOException

      Dumps internal RRD state to XML file. Use this XML file to convert your Rrd4j RRD to RRDTool format.

      Suppose that you have a Rrd4j RRD file `original.rrd` and you want to convert it to RRDTool format. First, execute the following java code: `RrdDb rrd = new RrdDb("original.rrd"); rrd.dumpXml("original.xml");`

      Use `original.xml` file to create the corresponding RRDTool file (from your command line):

      `rrdtool restore copy.rrd original.xml`

      Parameters:
        `filename` - Path to XML file which will be created.
      Throws:
        `IOException` - Thrown in case of I/O related error.

    - #### dumpXml

          public void dumpXml(XmlWriter writer)
                       throws IOException

      Writes the RRD content to `XmlWriter` using XML format. This format is fully compatible with RRDTool's XML dump format and can be used for conversion purposes or debugging.
      Parameters:
        `writer` - `XmlWriter` to receive XML data
      Throws:
        `IOException` - Thrown in case of I/O related error

    - #### exportXml

          public String exportXml()
                           throws IOException

      This method is just an alias for `getXml` method.
      Returns:
        Internal RRD state in XML format.
      Throws:
        `IOException` - Thrown in case of I/O related error

    - #### exportXml

          public void exportXml(OutputStream destination)
                         throws IOException

      This method is just an alias for `dumpXml` method.
      Parameters:
        `destination` - a `OutputStream` object.
      Throws:
        `IOException` - Thrown in case of I/O related error

    - #### exportXml

          public void exportXml(String filename)
                         throws IOException

      This method is just an alias for `dumpXml(String)` method.
      Parameters:
        `filename` - a `String` object.
      Throws:
        `IOException` - Thrown in case of I/O related error

    - #### fetchData

          FetchData fetchData(FetchRequest request)
                       throws IOException

      Throws:
        `IOException`

    - #### findMatchingArchive

          public Archive findMatchingArchive(FetchRequest request)
                                      throws IOException

      findMatchingArchive.
      Parameters:
        `request` - a `FetchRequest` object.
      Returns:
        a `Archive` object.
      Throws:
        `IOException` - if any.

    - #### findStartMatchArchive

          public Archive findStartMatchArchive(String consolFun,
                                               long startTime,
                                               long resolution)
                                        throws IOException

      Finds the archive that best matches to the start time (time period being start-time until now) and requested resolution.
      Parameters:
        `consolFun` - Consolidation function of the datasource.
        `startTime` - Start time of the time period in seconds.
        `resolution` - Requested fetch resolution.
      Returns:
        Reference to the best matching archive.
      Throws:
        `IOException` - Thrown in case of I/O related error.

    - #### getArcCount

          public int getArcCount()

      Returns the number of RRA archives defined in the file
      Returns:
        The number of RRA archives defined in the file

    - #### getArchive

          public Archive getArchive(ConsolFun consolFun,
                                    int steps)
                             throws IOException

      Returns Archive object with the given consolidation function and the number of steps.
      Parameters:
        `consolFun` - Consolidation function
        `steps` - Number of archive steps
      Returns:
        Requested Archive object or null if no such archive could be found
      Throws:
        `IOException` - Thrown in case of I/O error

    - #### getArchive

          public Archive getArchive(int arcIndex)

      Returns Archive object for the given archive index.
      Parameters:
        `arcIndex` - Archive index (zero based)
      Returns:
        Archive object

    - #### getArchives

          Archive[] getArchives()

    - #### getArcIndex

          public int getArcIndex(ConsolFun consolFun,
                                 int steps)
                          throws IOException

      Returns index of Archive object with the given consolidation function and the number of steps. Exception is thrown if such archive could not be found.
      Parameters:
        `consolFun` - Consolidation function
        `steps` - Number of archive steps
      Returns:
        Requested Archive object
      Throws:
        `IOException` - Thrown in case of I/O error

    - #### getBuilder

          public static RrdDb.Builder getBuilder()

    - #### getBytes

          public byte[] getBytes()
                          throws IOException

      Returns an array of bytes representing the whole RRD.
      Returns:
        All RRD bytes
      Throws:
        `IOException` - Thrown in case of I/O related error.

    - #### getCanonicalPath

          public String getCanonicalPath()
                                  throws IOException

      Returns canonical path to the underlying RRD file. Note that this method makes sense just for ordinary RRD files created on the disk - an exception will be thrown for RRD objects created in memory or with custom backends.
      Returns:
        Canonical path to RRD file;
      Throws:
        `IOException` - Thrown in case of I/O error or if the underlying backend is not derived from RrdFileBackend.

    - #### getCanonicalUri

          public URI getCanonicalUri()

    - #### getDatasource

          public Datasource getDatasource(int dsIndex)

      Returns Datasource object for the given datasource index.
      Parameters:
        `dsIndex` - Datasource index (zero based)
      Returns:
        Datasource object

    - #### getDatasource

          public Datasource getDatasource(String dsName)
                                   throws IOException

      Returns Datasource object corresponding to the given datasource name.
      Parameters:
        `dsName` - Datasource name
      Returns:
        Datasource object corresponding to the give datasource name or null if not found.
      Throws:
        `IOException` - Thrown in case of I/O error

    - #### getDatasources

          Datasource[] getDatasources()

    - #### getDsCount

          public int getDsCount()

      Returns the number of datasources defined in the file
      Returns:
        The number of datasources defined in the file

    - #### getDsIndex

          public int getDsIndex(String dsName)
                         throws IOException

      Returns internal index number for the given datasource name.
      Parameters:
        `dsName` - Data source name.
      Returns:
        Internal index of the given data source name in this RRD.
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### getDsNames

          public String[] getDsNames()
                              throws IOException

      Returns an array of datasource names defined in RRD.
      Returns:
        Array of datasource names.
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### getHeader

          public Header getHeader()

      Returns RRD header.
      Returns:
        Header object

    - #### getInfo

          public String getInfo()
                         throws IOException

      getInfo.
      Returns:
        a `String` object.
      Throws:
        `IOException` - if any.

    - #### getLastArchiveUpdateTime

          public long getLastArchiveUpdateTime()
                                        throws IOException

      Returns the last time when some of the archives in this RRD was updated. This time is not the same as the `getLastUpdateTime()` since RRD file can be updated without updating any of the archives.
      Returns:
        last time when some of the archives in this RRD was updated
      Throws:
        `IOException` - Thrown in case of I/O error

    - #### getLastDatasourceValue

          public double getLastDatasourceValue(String dsName)
                                        throws IOException

      Returns the last stored value for the given datasource.
      Parameters:
        `dsName` - Datasource name
      Returns:
        Last stored value for the given datasource
      Throws:
        `IOException` - Thrown in case of I/O error
        `IllegalArgumentException` - Thrown if no datasource in this RrdDb matches the given datasource name

    - #### getLastDatasourceValues

          public double[] getLastDatasourceValues()
                                           throws IOException

      Returns an array of last datasource values. The first value in the array corresponds to the first datasource defined in the RrdDb and so on.
      Returns:
        Array of last datasource values
      Throws:
        `IOException` - Thrown in case of I/O error

    - #### getLastUpdateTime

          public long getLastUpdateTime()
                                 throws IOException

      Returns time of last update operation as timestamp (in seconds).
      Returns:
        Last update time (in seconds).
      Throws:
        `IOException` - if any.

    - #### getPath

          public String getPath()

      Returns the path to this RRD.
      Returns:
        Path to this RRD.

    - #### getRrdAllocator

          public RrdAllocator getRrdAllocator()

      Required to implement RrdUpdater interface. You should never call this method directly.
      Specified by:
        `getRrdAllocator` in interface `RrdUpdater<RrdDb>`
      Returns:
        Allocator object

    - #### getRrdBackend

          public RrdBackend getRrdBackend()

      Returns backend object for this RRD which performs actual I/O operations.
      Specified by:
        `getRrdBackend` in interface `RrdUpdater<RrdDb>`
      Returns:
        RRD backend for this RRD.

    - #### getRrdDef

          public RrdDef getRrdDef()
                           throws IOException

      Returns RRD definition object which can be used to create new RRD with the same creation parameters but with no data in it.

      Example:

           RrdDb rrd1 = new RrdDb("original.rrd");
           RrdDef def = rrd1.getRrdDef();
           // fix path
           def.setPath("empty_copy.rrd");
           // create new RRD file
           RrdDb rrd2 = new RrdDb(def);

      Returns:
        RRD definition.
      Throws:
        `IOException` - if any.

    - #### getUri

          public URI getUri()

      Returns the URI to this RRD, as seen by the backend.
      Returns:
        URI to this RRD.

    - #### getXml

          public String getXml()
                        throws IOException

      Returns string representing internal RRD state in XML format. This format is fully compatible with RRDTool's XML dump format and can be used for conversion purposes or debugging.
      Returns:
        Internal RRD state in XML format.
      Throws:
        `IOException` - Thrown in case of I/O related error

    - #### internalClose

          void internalClose()
                      throws IOException

      Throws:
        `IOException`

    - #### isClosed

          public boolean isClosed()

      Returns true if the RRD is closed.
      Returns:
        true if closed, false otherwise

    - #### main

          public static void main(String[] args)

      main.
      Parameters:
        `args` - an array of `String` objects.

    - #### of

          public static RrdDb of(RrdDef rrdDef)
                          throws IOException

      Returns a new RRD object from the definition. If the rrdDef was constructed giving an `URI`, `RrdBackendFactory.findFactory(URI)` will be used to resolve the needed factory. If not, or a relative URI was given, this RRD object will be backed with a storage (backend) of the default type. Initially, storage type defaults to "NIO" (RRD bytes will be put in a file on the disk). Default storage type can be changed with a static `RrdBackendFactory.setDefaultFactory(String)` method call.

      New RRD file structure is specified with an object of class `RrdDef`. The underlying RRD storage is created as soon as the method returns.

      Typical scenario:

           // create new RRD definition
           RrdDef def = new RrdDef("test.rrd", 300);
           def.addDatasource("input", DsType.DT_COUNTER, 600, 0, Double.NaN);
           def.addDatasource("output", DsType.DT_COUNTER, 600, 0, Double.NaN);
           def.addArchive(ConsolFun.CF_AVERAGE, 0.5, 1, 600);
           def.addArchive(ConsolFun.CF_AVERAGE, 0.5, 6, 700);
           def.addArchive(ConsolFun.CF_AVERAGE, 0.5, 24, 797);
           def.addArchive(ConsolFun.CF_AVERAGE, 0.5, 288, 775);
           def.addArchive(ConsolFun.CF_MAX, 0.5, 1, 600);
           def.addArchive(ConsolFun.CF_MAX, 0.5, 6, 700);
           def.addArchive(ConsolFun.CF_MAX, 0.5, 24, 797);
           def.addArchive(ConsolFun.CF_MAX, 0.5, 288, 775);

           // RRD definition is now completed, create the database!
           RrdDb rrd = RrdDb.of(def);
           // new RRD file has been created on your disk

      Parameters:
        `rrdDef` - Object describing the structure of the new RRD file.
      Returns:
        a new Rrdb created from the definition.
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### of

          public static RrdDb of(String path)
                          throws IOException

      Opens an existing RRD with read/write access. The path will be parsed as an URI and checked against the active factories. If it's a relative URI (no scheme given, or just a plain path), the default factory will be used.
      Parameters:
        `path` - Path to existing RRD.
      Returns:
        a {link RrdDb} opened with default settings
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### of

          public static RrdDb of(URI uri)
                          throws IOException

      Opens an existing RRD with read/write access. The URI will checked against the active factories. If it's a relative URI (no scheme given, or just a plain path), the default factory will be used.
      Parameters:
        `uri` - URI to existing RRD.
      Returns:
        a {link RrdDb} opened with default settings
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### setInfo

          public void setInfo(String info)
                       throws IOException

      setInfo.
      Parameters:
        `info` - a `String` object.
      Throws:
        `IOException` - if any.

    - #### store

          final void store(Sample sample)
                    throws IOException

      Throws:
        `IOException`