java.lang.Object
org.rrd4j.core.Datasource
All Implemented Interfaces:
RrdUpdater<Datasource>
public class Datasourceextends Object implements RrdUpdater<Datasource>
Class to represent single datasource within RRD. Each datasource object holds the following information: datasource definition (once set, never changed) and datasource state variables (changed whenever RRD gets updated).

Normally, you don't need to manipulate Datasource objects directly, it's up to Rrd4j framework to do it for you.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private double
    accumLastValue
    Interpolated value at the last update.
    private final RrdDouble<Datasource>
    accumValue
    Value accumulated since the last step.
    private final RrdString<Datasource>
    dsName
    The name of the data source.
    private final RrdEnum<Datasource, DsType>
    dsType
    The type of the data source.
    private final RrdLong<Datasource>
    heartbeat
    The heartbeat, in seconds.
    private static final String
    INVALID_MIN_MAX_VALUES
    Error text for an out of range min or max.
    private final RrdDouble<Datasource>
    lastValue
    The value at the last update.
    private static final double
    MAX_32_BIT
    Largest value representable in 32 bits.
    private static final double
    MAX_64_BIT
    Largest value representable in 64 bits.
    private final RrdDouble<Datasource>
    maxValue
    The minimum and maximum accepted values.
    private final RrdDouble<Datasource>
    minValue
    The minimum and maximum accepted values.
    private final RrdLong<Datasource>
    nanSeconds
    Seconds of unknown data accumulated.
    private final RrdDb
    parentDb
    The database holding this data source.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Datasource(RrdDb parentDb, DataImporter reader, int dsIndex)
    Loads an existing datasource from another RRD, copying the definition and the state variables (last value, accumulated value and NaN seconds) from the indexed datasource of the importer.
    Datasource(RrdDb parentDb, DsDef dsDef)
    Binds this datasource's storage slots in the RRD and, when a definition is supplied, fills them with it.

  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    accumulate(long oldTime, long newTime, double updateValue)
    Adds an update to the accumulated value.
    (package private) void
    appendXml(XmlWriter writer)
    Writes the datasource as a <ds> element of the XML dump, including the definition fields and the PDP status fields holding the last, accumulated and unknown-second counts.
    private double
    calculateLastTotal(long startTime, long boundaryTime)
    Integrates up to the last known value.
    private double
    calculateTotal(long startTime, long boundaryTime)
    Integrates the consolidated values over a range.
    private double
    calculateUpdateValue(long oldTime, double oldValue, long newTime, double newValue)
    Interpolates the value to store for an update.
    void
    copyStateTo(Datasource datasource)
    Copies object's internal state to another Datasource object.
    (package private) String
    dump()
    Returns a string representation of datasource information.
    double
    getAccumValue()
    Returns value this datasource accumulated so far.
    int
    getDsIndex()
    Returns index of this Datasource object in the RRD.
    long
    getHeartbeat()
    Returns datasource heartbeat
    double
    getLastValue()
    Returns last known value of the datasource.
    double
    getMaxValue()
    Returns maximal allowed value for this datasource.
    double
    getMinValue()
    Returns minimal allowed value for this datasource.
    String
    getName()
    Returns datasource name.
    long
    getNanSeconds()
    Returns the number of accumulated NaN seconds.
    RrdAllocator
    getRrdAllocator()
    Required to implement RrdUpdater interface.
    RrdBackend
    getRrdBackend()
    Returns the underlying storage (backend) object which actually performs all I/O operations.
    DsType
    getType()
    Returns datasource type (GAUGE, COUNTER, DERIVE, ABSOLUTE).
    (package private) final void
    process(long newTime, double newValue)
    Feeds one sample into the current primary data point, accumulating the rate over the interval since the last sample.
    void
    setDsName(String newDsName)
    Sets datasource name to a new value
    void
    setDsType(DsType newDsType)
    Setter for the field dsType.
    void
    setHeartbeat(long heartbeat)
    Sets datasource heartbeat to a new value.
    void
    setMaxValue(double maxValue, boolean filterArchivedValues)
    Sets maximum allowed value for this datasource.
    void
    setMinMaxValue(double minValue, double maxValue, boolean filterArchivedValues)
    Sets min/max values allowed for this datasource.
    void
    setMinValue(double minValue, boolean filterArchivedValues)
    Sets minimum allowed value for this datasource.

    Methods inherited from class Object

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

  • Field Details

    • MAX_32_BIT

      private static final double MAX_32_BIT
      Largest value representable in 32 bits.

    • MAX_64_BIT

      private static final double MAX_64_BIT
      Largest value representable in 64 bits.

    • INVALID_MIN_MAX_VALUES

      private static final String INVALID_MIN_MAX_VALUES
      Error text for an out of range min or max.
      See Also:

    • accumLastValue

      private double accumLastValue
      Interpolated value at the last update.

    • parentDb

      private final RrdDb parentDb
      The database holding this data source.

    • dsName

      private final RrdString<Datasource> dsName
      The name of the data source.

    • dsType

      private final RrdEnum<Datasource, DsType> dsType
      The type of the data source.

    • heartbeat

      private final RrdLong<Datasource> heartbeat
      The heartbeat, in seconds.

    • minValue

      private final RrdDouble<Datasource> minValue
      The minimum and maximum accepted values.

    • maxValue

      private final RrdDouble<Datasource> maxValue
      The minimum and maximum accepted values.

    • lastValue

      private final RrdDouble<Datasource> lastValue
      The value at the last update.

    • nanSeconds

      private final RrdLong<Datasource> nanSeconds
      Seconds of unknown data accumulated.

    • accumValue

      private final RrdDouble<Datasource> accumValue
      Value accumulated since the last step.

  • Constructor Details

    • Datasource

      Datasource(RrdDb parentDb, DsDef dsDef) throws IOException
      Binds this datasource's storage slots in the RRD and, when a definition is supplied, fills them with it. Passing a null definition leaves every slot holding the zero value, which is how a datasource is opened for reading from an existing file; the other constructor then copies the stored values in.
      Parameters:
      parentDb - the RRD this datasource belongs to, whose backend allocates the storage
      dsDef - definition to initialize the slots from, or null to leave them unset
      Throws:
      IOException - if the storage cannot be allocated or written

    • Datasource

      Datasource(RrdDb parentDb, DataImporter reader, int dsIndex) throws IOException
      Loads an existing datasource from another RRD, copying the definition and the state variables (last value, accumulated value and NaN seconds) from the indexed datasource of the importer.
      Parameters:
      parentDb - the RRD this datasource belongs to, whose backend allocates the storage
      reader - the RRD to copy the datasource from
      dsIndex - position of the datasource to copy within the reader's datasource list
      Throws:
      IOException - if the source datasource cannot be read or the storage written

  • Method Details

    • dump

      String dump() throws IOException
      Returns a string representation of datasource information.
      Returns:
      a string containing datasource information
      Throws:
      IOException - if an I/O error occurs

    • getName

      public String getName() throws IOException
      Returns datasource name.
      Returns:
      Datasource name
      Throws:
      IOException - Thrown in case of I/O error

    • getType

      public DsType getType() throws IOException
      Returns datasource type (GAUGE, COUNTER, DERIVE, ABSOLUTE).
      Returns:
      Datasource type, one of GAUGE, COUNTER, DERIVE or ABSOLUTE.
      Throws:
      IOException - Thrown in case of I/O error

    • getHeartbeat

      public long getHeartbeat() throws IOException
      Returns datasource heartbeat
      Returns:
      Datasource heartbeat, in seconds
      Throws:
      IOException - Thrown in case of I/O error

    • getMinValue

      public double getMinValue() throws IOException
      Returns minimal allowed value for this datasource.
      Returns:
      Minimal value allowed.
      Throws:
      IOException - Thrown in case of I/O error

    • getMaxValue

      public double getMaxValue() throws IOException
      Returns maximal allowed value for this datasource.
      Returns:
      Maximal value allowed.
      Throws:
      IOException - Thrown in case of I/O error

    • getLastValue

      public double getLastValue() throws IOException
      Returns last known value of the datasource.
      Returns:
      Last datasource value.
      Throws:
      IOException - Thrown in case of I/O error

    • getAccumValue

      public double getAccumValue() throws IOException
      Returns value this datasource accumulated so far.
      Returns:
      Accumulated datasource value.
      Throws:
      IOException - Thrown in case of I/O error

    • getNanSeconds

      public long getNanSeconds() throws IOException
      Returns the number of accumulated NaN seconds.
      Returns:
      Accumulated NaN seconds.
      Throws:
      IOException - Thrown in case of I/O error

    • process

      final void process(long newTime, double newValue) throws IOException
      Feeds one sample into the current primary data point, accumulating the rate over the interval since the last sample. Once the sample crosses a step boundary the interval is closed out and written to this datasource's archive, after which accumulation restarts at the boundary.
      Parameters:
      newTime - sample time in seconds since the epoch
      newValue - sample value; samples further apart than the heartbeat are ignored, as are rates that fall outside the configured min/max
      Throws:
      IOException - if the datasource state cannot be read, updated or archived

    • calculateUpdateValue

      private double calculateUpdateValue(long oldTime, double oldValue, long newTime, double newValue) throws IOException
      Interpolates the value to store for an update.
      Parameters:
      oldTime - the time of the previous update
      oldValue - the value at the previous update
      newTime - the time of the new update
      newValue - the value given for the new update
      Returns:
      the interpolated value
      Throws:
      IOException - if the archive data cannot be read

    • accumulate

      private void accumulate(long oldTime, long newTime, double updateValue) throws IOException
      Adds an update to the accumulated value.
      Parameters:
      oldTime - the start of the accumulation
      newTime - the time of the update
      updateValue - the value to accumulate
      Throws:
      IOException - if the archive data cannot be read

    • calculateTotal

      private double calculateTotal(long startTime, long boundaryTime) throws IOException
      Integrates the consolidated values over a range.
      Parameters:
      startTime - the start of the range
      boundaryTime - the end of the range
      Returns:
      the total over the range
      Throws:
      IOException - if the archive data cannot be read

    • calculateLastTotal

      private double calculateLastTotal(long startTime, long boundaryTime) throws IOException
      Integrates up to the last known value.
      Parameters:
      startTime - the start of the range
      boundaryTime - the end of the range
      Returns:
      the total over the range
      Throws:
      IOException - if the archive data cannot be read

    • appendXml

      void appendXml(XmlWriter writer) throws IOException
      Writes the datasource as a <ds> element of the XML dump, including the definition fields and the PDP status fields holding the last, accumulated and unknown-second counts. An unknown last value is written as UNKN.
      Parameters:
      writer - the XML writer positioned at the point the ds element starts
      Throws:
      IOException - if a datasource value cannot be read from storage

    • copyStateTo

      public void copyStateTo(Datasource datasource) throws IOException

      Copies object's internal state to another Datasource object.

      Specified by:
      copyStateTo in interface RrdUpdater<Datasource>
      Parameters:
      datasource - a RrdUpdater object.
      Throws:
      IOException - if the state cannot be read from the backend

    • getDsIndex

      public int getDsIndex() throws IOException
      Returns index of this Datasource object in the RRD.
      Returns:
      Datasource index in the RRD.
      Throws:
      IOException - Thrown in case of I/O error

    • setHeartbeat

      public void setHeartbeat(long heartbeat) throws IOException
      Sets datasource heartbeat to a new value.
      Parameters:
      heartbeat - New heartbeat value
      Throws:
      IOException - Thrown in case of I/O error
      IllegalArgumentException - Thrown if invalid (non-positive) heartbeat value is specified.

    • setDsName

      public void setDsName(String newDsName) throws IOException
      Sets datasource name to a new value
      Parameters:
      newDsName - New datasource name
      Throws:
      IOException - Thrown in case of I/O error

    • setDsType

      public void setDsType(DsType newDsType) throws IOException
      Setter for the field dsType.
      Parameters:
      newDsType - a DsType object.
      Throws:
      IOException - if the RRD file cannot be written.

    • setMinValue

      public void setMinValue(double minValue, boolean filterArchivedValues) throws IOException
      Sets minimum allowed value for this datasource. If filterArchivedValues argument is set to true, all archived values less then minValue will be fixed to NaN.
      Parameters:
      minValue - New minimal value. Specify Double.NaN if no minimal value should be set
      filterArchivedValues - true, if archived datasource values should be fixed; false, otherwise.
      Throws:
      IOException - Thrown in case of I/O error
      IllegalArgumentException - Thrown if invalid minValue was supplied (not less then maxValue)

    • setMaxValue

      public void setMaxValue(double maxValue, boolean filterArchivedValues) throws IOException
      Sets maximum allowed value for this datasource. If filterArchivedValues argument is set to true, all archived values greater then maxValue will be fixed to NaN.
      Parameters:
      maxValue - New maximal value. Specify Double.NaN if no max value should be set.
      filterArchivedValues - true, if archived datasource values should be fixed; false, otherwise.
      Throws:
      IOException - Thrown in case of I/O error
      IllegalArgumentException - Thrown if invalid maxValue was supplied (not greater then minValue)

    • setMinMaxValue

      public void setMinMaxValue(double minValue, double maxValue, boolean filterArchivedValues) throws IOException
      Sets min/max values allowed for this datasource. If filterArchivedValues argument is set to true, all archived values less then minValue or greater then maxValue will be fixed to NaN.
      Parameters:
      minValue - New minimal value. Specify Double.NaN if no min value should be set.
      maxValue - New maximal value. Specify Double.NaN if no max value should be set.
      filterArchivedValues - true, if archived datasource values should be fixed; false, otherwise.
      Throws:
      IOException - Thrown in case of I/O error
      IllegalArgumentException - Thrown if invalid min/max values were supplied

    • getRrdBackend

      public RrdBackend getRrdBackend()
      Returns the underlying storage (backend) object which actually performs all I/O operations.
      Specified by:
      getRrdBackend in interface RrdUpdater<Datasource>
      Returns:
      I/O backend object

    • getRrdAllocator

      public RrdAllocator getRrdAllocator()
      Required to implement RrdUpdater interface. You should never call this method directly.
      Specified by:
      getRrdAllocator in interface RrdUpdater<Datasource>
      Returns:
      Allocator object