## org.jrobin.core
Class Sample

    java.lang.Object
      org.jrobin.core.Sample

public class Sample
extends java.lang.Object

Class to represent data source values for the given timestamp. Objects of this class are never created directly (no public constructor is provided). To learn more how to update RRDs, see RRDTool's rrdupdate man page.

To update a RRD with JRobin 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 specifify only 'known' data source values. However, if you want to specify 'unknown' values too, use `Double.NaN`.

Method Summary
`java.lang.String` `dump()` Dumps sample content using the syntax of RRDTool's update command.
`java.lang.String[]` `getDsNames()` Returns an array of all data source names.
`long` `getTime()` Returns sample timestamp (in seconds, without milliseconds).
`double[]` `getValues()` Returns all current data source values in the sample.
`void` `set(java.lang.String timeAndValues)` Sets sample timestamp and data source values in a fashion similar to RRDTool.
`void` `setAndUpdate(java.lang.String timeAndValues)` Creates sample with the timestamp and data source values supplied in the argument string and stores sample in the corresponding RRD.
`void` `setTime(long time)` Sets sample timestamp.
`void` `setValue(int i, double value)` Sets single datasource value using data source index.
`void` `setValue(java.lang.String dsName, double value)` Sets single data source value in the sample.
`void` `setValues(double[] values)` Sets some (possibly all) data source values in bulk.
`void` `update()` Stores sample in the corresponding RRD.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### setValue

    public void setValue(java.lang.String dsName,
                         double value)
                  throws RrdException

  Sets single data source value in the sample.

  Parameters:
    `dsName` - Data source name.
    `value` - Data source value.
  Throws:
    `RrdException` - Thrown if invalid data source name is supplied.

### setValue

    public void setValue(int i,
                         double value)
                  throws RrdException

  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
  Throws:
    `RrdException` - Thrown if data source index is invalid.

### setValues

    public void setValues(double[] values)
                   throws RrdException

  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.
  Throws:
    `RrdException` - 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:
    Sample timestamp.

### setTime

    public void setTime(long time)

  Sets sample timestamp. Timestamp should be defined in seconds (without milliseconds).

  Parameters:
    `time` - New sample timestamp.

### getDsNames

    public java.lang.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 void set(java.lang.String timeAndValues)
             throws RrdException

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

  Throws:
    `RrdException` - Thrown if too many datasource values are supplied

### update

    public void update()
                throws java.io.IOException,
                       RrdException

  Stores sample in the corresponding RRD. If the update operation succeedes, all datasource values in the sample will be set to Double.NaN (unknown) values.

  Throws:
    `java.io.IOException` - Thrown in case of I/O error.
    `RrdException` - Thrown in case of JRobin related error.

### setAndUpdate

    public void setAndUpdate(java.lang.String timeAndValues)
                      throws java.io.IOException,
                             RrdException

  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 delmited with colons. For example:
    `1005234132:12.2:35.6:U:24.5`
    `NOW:12.2:35.6:U:24.5`
  Throws:
    `java.io.IOException` - Thrown in case of I/O error.
    `RrdException` - Thrown in case of JRobin related error.

### dump

    public java.lang.String dump()

  Dumps sample content using the syntax of RRDTool's update command.

  Returns:
    Sample dump.