java.lang.Object
org.rrd4j.core.RrdDb
All Implemented Interfaces:
Closeable, AutoCloseable, RrdUpdater<RrdDb>
public class RrdDbextends 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.

See also the RRDtool tutorial and the man pages for rrdcreate, rrdupdate, rrdfetch and rrdgraph; see the CDEF tutorial for RPN extensions, also supported here.

See Also:

  • Field Details

    • PREFIX_XML

      public static final String PREFIX_XML
      Prefix to identify external XML file source used in various RrdDb constructors.
      See Also:

    • PREFIX_RRDTool

      public static final String PREFIX_RRDTool
      Prefix to identify external RRDTool file source used in various RrdDb constructors.
      See Also:

    • XML_BUFFER_CAPACITY

      static final int XML_BUFFER_CAPACITY
      XML buffer capacity in bytes
      See Also:

    • backend

      private final RrdBackend backend
      The backend holding the data.

    • allocator

      private final RrdAllocator allocator
      Allocator handing out file positions.

    • datasources

      private final Datasource[] datasources
      The datasources of the database.

    • archives

      private final Archive[] archives
      The archives of the database.

    • pool

      private final RrdDbPool pool
      The pool holding this database.

    • closed

      private boolean closed
      True once the database is closed.

  • Constructor Details

    • RrdDb

      private RrdDb(RrdDef rrdDef, RrdBackendFactory factory, RrdDbPool pool) throws IOException
      Creates a new database from a definition.
      Parameters:
      rrdDef - the database definition
      factory - the backend factory
      pool - the pool to hold the database
      Throws:
      IOException - if the database cannot be created

    • RrdDb

      private RrdDb(String rrdPath, URI rrdUri, boolean readOnly, RrdBackendFactory factory, RrdDbPool pool) throws IOException
      Opens an existing database.
      Parameters:
      rrdPath - the database path
      rrdUri - the database URI, may be null
      readOnly - true to open read-only
      factory - the backend factory
      pool - the pool to hold the database
      Throws:
      IOException - if the database cannot be opened

    • RrdDb

      private RrdDb(String rrdPath, URI rrdUri, String externalPath, DataImporter importer, RrdBackendFactory factory, RrdDbPool pool) throws IOException
      Opens a database importing an external file.
      Parameters:
      rrdPath - the database path
      rrdUri - the database URI, may be null
      externalPath - the external file to import
      importer - the importer for the external data
      factory - the backend factory
      pool - the pool to hold the database
      Throws:
      IOException - if the database cannot be opened

  • Method Details

    • getBuilder

      public static RrdDb.Builder getBuilder()
      Create a new builder for constructing RrdDb instances.
      Returns:
      a new builder whose pool defaults to the shared RrdDbPool

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

    • close

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

    • internalClose

      void internalClose() throws IOException
      Internal close
      Throws:
      IOException - if the backend fails to release the RRD file

    • isClosed

      public boolean isClosed()
      Returns true if the RRD is closed.
      Returns:
      true if closed, false otherwise

    • getHeader

      public Header getHeader()
      Returns RRD header.
      Returns:
      Header object

    • getDatasource

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

    • getArchive

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

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

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

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

    • 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

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

    • store

      final void store(Sample sample) throws IOException
      Store sample
      Parameters:
      sample - the populated sample, whose timestamp must be at least one step after the last update
      Throws:
      IOException - if a datasource fails to write the processed value

    • fetchData

      FetchData fetchData(FetchRequest request) throws IOException
      Fetch data
      Parameters:
      request - the fetch request naming the consolidation function, time range and resolution
      Returns:
      the data consolidated from the archive that best matches the request
      Throws:
      IOException - if the matching archive fails to read the RRD file

    • findMatchingArchive

      public Archive findMatchingArchive(FetchRequest request) throws IOException
      Picks the archive best able to serve the request, preferring a full over a partial time-range match and then the closest step to the requested resolution.
      Parameters:
      request - a FetchRequest object.
      Returns:
      a Archive object.
      Throws:
      IOException - declared but never thrown; matching reads in-memory metadata only

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

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

    • archive

      final void archive(Datasource datasource, double value, double lastValue, long numUpdates) throws IOException
      Archive value
      Parameters:
      datasource - the datasource being updated, whose name resolves to the archive slot index
      value - the current reading, archived into the AVERAGE consolidation archives
      lastValue - the previous reading, archived into every other consolidation archive
      numUpdates - how many accumulated updates are still pending in the current RRD step
      Throws:
      IOException - if an archive fails to write the value

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

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

    • getDatasources

      Datasource[] getDatasources()
      Returns the data sources declared by this RRD.
      Returns:
      the data source objects, in the order declared by the RrdDef

    • getArchives

      Archive[] getArchives()
      Returns the round robin archives holding the consolidated data.
      Returns:
      the round robin archives, in the order declared by the RrdDef

    • 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

    • 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

    • 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

    • 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

    • 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

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

    • 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

    • 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 the value cannot be read from the backend

    • 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:
      a newly built RRD definition holding this RRD's path, header, data sources and archives
      Throws:
      IOException - if the header, data source or archive values cannot be read from the backend

    • copyStateTo

      public void copyStateTo(RrdDb otherRrd) throws IOException
      Copies object's internal state to another RrdDb object.
      Specified by:
      copyStateTo in interface RrdUpdater<RrdDb>
      Parameters:
      otherRrd - the target RrdDb
      Throws:
      IOException - if an I/O error occurs

    • 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

    • 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 - the consolidation function to match
      steps - Number of archive steps
      Returns:
      Requested Archive object
      Throws:
      IOException - Thrown in case of I/O error

    • 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 - the consolidation function to match
      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

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

    • getPath

      public String getPath()
      Returns the path to this RRD.
      Returns:
      Path to this RRD.

    • getUri

      public URI getUri()
      Returns the URI to this RRD, as seen by the backend.
      Returns:
      URI to this RRD.

    • getCanonicalUri

      public URI getCanonicalUri()
      Returns the canonical URI for this RRD.
      Returns:
      the canonical URI

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

    • 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

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

    • 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

    • 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

    • getDsCount

      public int getDsCount()
      Returns the number of datasources defined in the file
      Returns:
      The number of datasources defined in the file

    • getArcCount

      public int getArcCount()
      Returns the number of RRA archives defined in the file
      Returns:
      The number of RRA archives defined in the file

    • 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

    • getInfo

      public String getInfo() throws IOException
      Returns the free-form informational string stored in the RRD header.
      Returns:
      a String object.
      Throws:
      IOException - if the signature cannot be read from the backend

    • setInfo

      public void setInfo(String info) throws IOException
      Replaces the free-form informational string stored in the RRD header.
      Parameters:
      info - a String object.
      Throws:
      IOException - if the signature cannot be written to the backend