org.rrd4j.core

Class Sample

java.lang.Object

org.rrd4j.core.Sample

public class Sample
extends 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 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.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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()
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 java.lang.Object

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

Constructor Detail

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 Detail

dump

public String dump()

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

Returns:

Sample dump.

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.

getRrdToolCommand

String getRrdToolCommand()

getTime

public long getTime()

Returns sample timestamp (in seconds, without milliseconds).

Returns:

Sample timestamp.

getValues

public double[] getValues()

Returns all current data source values in the sample.

Returns:

Data source values.

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

Returns:

This Sample object

Throws:

IllegalArgumentException - Thrown if too many datasource values are supplied

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

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

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.

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.

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.

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.