java.lang.Object
org.rrd4j.core.Sample
public class Sampleextends Object
Class to represent data source values for the given timestamp. Objects of this class are never created directly (no public constructor is provided). For RRD update semantics see the rrdupdate man page.

To update a RRD with Rrd4j use the following procedure:

  1. Obtain empty Sample object by calling method createSample() on respective RrdDb object.
  2. Adjust Sample timestamp if necessary (see setTime() method).
  3. Supply data source values (see setValue()).
  4. Call Sample's update() method.

Newly created Sample object contains all data source values set to 'unknown'. You should specify only 'known' data source values. However, if you want to specify 'unknown' values too, use Double.NaN.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final String[]
    dsNames
    Data sources named in the sample.
    private final RrdDb
    parentDb
    The database the sample belongs to.
    private long
    time
    Time the sample was taken.
    private final double[]
    values
    Values read for those sources.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Sample(RrdDb parentDb, long time)
    Creates a new sample for the specified RRD database and time.

  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    clearValues()
    Clears all values in the sample by setting them to NaN.
    String
    dump()
    Dumps sample content using the syntax of RRDTool's update command.
    String[]
    getDsNames()
    Returns an array of all data source names.
    (package private) String
    getRrdToolCommand()
    Render this sample using the syntax of RRDTool's update command, quoting the backing database path and listing every data source value in order.
    long
    getTime()
    Returns sample timestamp (in seconds, without milliseconds).
    double[]
    getValues()
    Returns all current data source values in the sample.
    Sample
    set(String timeAndValues)
    Sets sample timestamp and data source values in a fashion similar to RRDTool.
    void
    setAndUpdate(String timeAndValues)
    Creates sample with the timestamp and data source values supplied in the argument string and stores sample in the corresponding RRD.
    Sample
    setTime(long time)
    Sets sample timestamp.
    Sample
    setValue(int i, double value)
    Sets single datasource value using data source index.
    Sample
    setValue(String dsName, double value)
    Sets single data source value in the sample.
    Sample
    setValues(double... values)
    Sets some (possibly all) data source values in bulk.
    void
    update()
    Stores sample in the corresponding RRD.

    Methods inherited from class Object

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

  • Field Details

    • parentDb

      private final RrdDb parentDb
      The database the sample belongs to.

    • time

      private long time
      Time the sample was taken.

    • dsNames

      private final String[] dsNames
      Data sources named in the sample.

    • values

      private final double[] values
      Values read for those sources.

  • Constructor Details

    • Sample

      Sample(RrdDb parentDb, long time) throws IOException
      Creates a new sample for the specified RRD database and time.
      Parameters:
      parentDb - the parent RRD database
      time - the timestamp for this sample
      Throws:
      IOException - if an I/O error occurs

  • Method Details

    • clearValues

      private void clearValues()
      Clears all values in the sample by setting them to NaN.

    • setValue

      public Sample setValue(String dsName, double value)
      Sets single data source value in the sample.
      Parameters:
      dsName - Data source name.
      value - Data source value.
      Returns:
      This Sample object
      Throws:
      IllegalArgumentException - Thrown if invalid data source name is supplied.

    • setValue

      public Sample setValue(int i, double value)
      Sets single datasource value using data source index. Data sources are indexed by the order specified during RRD creation (zero-based).
      Parameters:
      i - Data source index
      value - Data source values
      Returns:
      This Sample object
      Throws:
      IllegalArgumentException - Thrown if data source index is invalid.

    • setValues

      public Sample setValues(double... values)
      Sets some (possibly all) data source values in bulk. Data source values are assigned in the order of their definition inside the RRD.
      Parameters:
      values - Data source values.
      Returns:
      This Sample object
      Throws:
      IllegalArgumentException - Thrown if the number of supplied values is zero or greater than the number of data sources defined in the RRD.

    • getValues

      public double[] getValues()
      Returns all current data source values in the sample.
      Returns:
      Data source values.

    • getTime

      public long getTime()
      Returns sample timestamp (in seconds, without milliseconds).
      Returns:
      the sample time in seconds since the epoch, milliseconds truncated

    • setTime

      public Sample setTime(long time)
      Sets sample timestamp. Timestamp should be defined in seconds (without milliseconds).
      Parameters:
      time - New sample timestamp.
      Returns:
      This Sample object

    • getDsNames

      public String[] getDsNames()
      Returns an array of all data source names. If you try to set value for the data source name not in this array, an exception is thrown.
      Returns:
      Acceptable data source names.

    • set

      public Sample set(String timeAndValues)
      Sets sample timestamp and data source values in a fashion similar to RRDTool. Argument string should be composed in the following way: timestamp:value1:value2:...:valueN.

      You don't have to supply all datasource values. Unspecified values will be treated as unknowns. To specify unknown value in the argument string, use letter 'U'.

      Parameters:
      timeAndValues -

      String made by concatenating sample timestamp with corresponding data source values delimited with colons. For example:

                           1005234132:12.2:35.6:U:24.5
                     NOW:12.2:35.6:U:24.5

      'N' stands for the current timestamp (can be replaced with 'NOW')

      Method will throw an exception if timestamp is invalid (cannot be parsed as Long, and is not 'N' or 'NOW'). Datasource value which cannot be parsed as 'double' will be silently set to NaN.

      Returns:
      This Sample object
      Throws:
      IllegalArgumentException - Thrown if too many datasource values are supplied

    • update

      public void update() throws IOException
      Stores sample in the corresponding RRD. If the update operation succeeds, all datasource values in the sample will be set to Double.NaN (unknown) values.
      Throws:
      IOException - Thrown in case of I/O error.

    • setAndUpdate

      public void setAndUpdate(String timeAndValues) throws IOException
      Creates sample with the timestamp and data source values supplied in the argument string and stores sample in the corresponding RRD. This method is just a shortcut for:
          set(timeAndValues);
    update();
      Parameters:
      timeAndValues - String made by concatenating sample timestamp with corresponding data source values delimited with colons. For example:
      1005234132:12.2:35.6:U:24.5
      NOW:12.2:35.6:U:24.5
      Throws:
      IOException - Thrown in case of I/O error.

    • dump

      public String dump()
      Dumps sample content using the syntax of RRDTool's update command.
      Returns:
      the sample as an RRDTool update command line

    • getRrdToolCommand

      String getRrdToolCommand()
      Render this sample using the syntax of RRDTool's update command, quoting the backing database path and listing every data source value in order.
      Returns:
      the rrdtool update command text