org.rrd4j.data

## Class DataProcessor

- java.lang.Object
- - org.rrd4j.data.DataProcessor

- All Implemented Interfaces:
    DataHolder

      public class DataProcessor
      extends Object
      implements DataHolder

  Class which should be used for all calculations based on the data fetched from RRD files. This class supports ordinary DEF datasources (defined in RRD files), CDEF datasources (RPN expressions evaluation), SDEF (static datasources - extension of Rrd4j) and PDEF (plottables, see `Plottable` for more information.

  Typical class usage:

       final long t1 = ...
       final long t2 = ...
       DataProcessor dp = new DataProcessor(t1, t2);
       // DEF datasource
       dp.addDatasource("x", "demo.rrd", "some_source", "AVERAGE");
       // DEF datasource
       dp.addDatasource("y", "demo.rrd", "some_other_source", "AVERAGE");
       // CDEF datasource, z = (x + y) / 2
       dp.addDatasource("z", "x,y,+,2,/");
       // ACTION!
       dp.processData();
       // Dump calculated values
       System.out.println(dp.dump());

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static double` | `DEFAULT_PERCENTILE` Constant `DEFAULT_PERCENTILE=95.0`
    `static int` | `DEFAULT_PIXEL_COUNT` Deprecated.

    - ### Fields inherited from interface org.rrd4j.core.DataHolder

      `DEFAULT_POOL_USAGE_POLICY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataProcessor(Calendar gc1, Calendar gc2)` Creates new DataProcessor object for the given time span.
    `DataProcessor(Date d1, Date d2)` Creates new DataProcessor object for the given time span.
    `DataProcessor(long t1, long t2)` Creates new DataProcessor object for the given time span.
    `DataProcessor(java.time.temporal.TemporalAmount d)` Creates new DataProcessor object for the given time duration.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `datasource(String name, FetchData fetchData)` Adds DEF datasource with datasource values already available in the FetchData object.
    `void` | `datasource(String name, IPlottable plottable)` Adds a custom, `plottable` datasource (PDEF).
    `void` | `datasource(String name, String rpnExpression)` Adds complex source (CDEF).
    `void` | `datasource(String name, String dsName, FetchData fetchData)` Adds DEF datasource with datasource values already available in the FetchData object.
    `void` | `datasource(String name, String file, String dsName, ConsolFun consolFunc)` Adds simple datasource (DEF).
    `void` | `datasource(String name, String file, String dsName, ConsolFun consolFunc, RrdBackendFactory backend)` Adds simple source (DEF).
    `void` | `datasource(String name, String defName, Variable var)` Creates a datasource that performs a variable calculation on an another named datasource to yield a single combined timestamp/value.
    `void` | `datasource(String name, URI rrdUri, String dsName, ConsolFun consolFunc)` Adds simple datasource (DEF).
    `void` | `datasource(String name, URI uri, String dsName, ConsolFun consolFunc, RrdBackendFactory backend)` Adds simple source (DEF).
    `String` | `dump()` Dumps timestamps and values of all datasources in a tabular form.
    `long` | `getEndTime()` Returns ending timestamp.
    `long` | `getFetchRequestResolution()` Returns desired RRD archive step (resolution) in seconds to be used while fetching data from RRD files.
    `long` | `getLastRrdArchiveUpdateTime()` Returns time when last RRD archive was updated (all RRD files are considered).
    `int` | `getPixelCount()` Returns the number of pixels (target graph width).
    `RrdDbPool` | `getPool()`
    `(package private) Source` | `getSource(String sourceName)`
    `String[]` | `getSourceNames()` Returns array of datasource names defined in this DataProcessor.
    `long` | `getStartTime()` Returns starting timestamp.
    `long` | `getStep()` Returns the time step used for data processing.
    `long[]` | `getTimestamps()` Returns consolidated timestamps created with the `processData()` method.
    `long[]` | `getTimestampsPerPixel()` Calculates timestamps which correspond to individual pixels on the graph based on the graph width set with a `setPixelCount(int)` method call.
    `long[]` | `getTimestampsPerPixel(int pixelCount)` Calculates timestamps which correspond to individual pixels on the graph.
    `TimeZone` | `getTimeZone()`
    `double[][]` | `getValues()` Returns an array of all datasource values for all datasources.
    `double[]` | `getValues(String sourceName)` Returns calculated values for a single datasource.
    `double[]` | `getValuesPerPixel(String sourceName)` Method used to calculate datasource values which should be presented on the graph based on the graph width set with a `setPixelCount(int)` method call.
    `double[]` | `getValuesPerPixel(String sourceName, int pixelCount)` Method used to calculate datasource values which should be presented on the graph based on the desired graph width.
    `Variable.Value` | `getVariable(String sourceName)` Extract the variable value from an already define Variable datasource (a VDEF)
    `Variable.Value` | `getVariable(String sourceName, Variable var)` Returns single aggregated value for a single datasource.
    `boolean` | `isPoolUsed()` Returns boolean value representing `RrdDbPool` usage policy.
    `void` | `processData()` Method that should be called once all datasources are defined.
    `void` | `setEndTime(long time)` Sets the time when the graph should end.
    `void` | `setFetchRequestResolution(long fetchRequestResolution)` Sets desired RRD archive step in seconds to be used internally while fetching data from RRD files.
    `void` | `setPixelCount(int pixelCount)` Sets the number of pixels (target graph width).
    `void` | `setPool(RrdDbPool pool)` Defines the `RrdDbPool` to use.
    `void` | `setPoolUsed(boolean poolUsed)` Sets the `RrdDbPool` usage policy.
    `void` | `setStartTime(long time)` Sets the time when the graph should start.
    `void` | `setStep(long step)` Once data are fetched, the step value will be used to generate values.
    `void` | `setTimeSpan(long startTime, long endTime)` Sets starting and ending time for the for the graph.
    `void` | `setTimeZone(TimeZone tz)` Set the time zone used for the legend.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### DEFAULT_PERCENTILE

          public static final double DEFAULT_PERCENTILE

      Constant `DEFAULT_PERCENTILE=95.0`
      See Also:
        Constant Field Values

    - #### DEFAULT_PIXEL_COUNT

          @Deprecated
          public static final int DEFAULT_PIXEL_COUNT

      Deprecated.
      Not used any more.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DataProcessor

          public DataProcessor(Calendar gc1,
                               Calendar gc2)

      Creates new DataProcessor object for the given time span. Ending date may be set to null. In that case, the class will try to find optimal ending date based on the last update time of RRD files processed with the `processData()` method.

      It use the time zone for starting calendar date.

      Parameters:
        `gc1` - Starting Calendar date
        `gc2` - Ending Calendar date

    - #### DataProcessor

          public DataProcessor(Date d1,
                               Date d2)

      Creates new DataProcessor object for the given time span. Ending date may be set to null. In that case, the class will try to find optimal ending date based on the last update time of RRD files processed with the `processData()` method.
      Parameters:
        `d1` - Starting date
        `d2` - Ending date

    - #### DataProcessor

          public DataProcessor(long t1,
                               long t2)

      Creates new DataProcessor object for the given time span. Ending timestamp may be set to zero. In that case, the class will try to find the optimal ending timestamp based on the last update time of RRD files processed with the `processData()` method.
      Parameters:
        `t1` - Starting timestamp in seconds without milliseconds
        `t2` - Ending timestamp in seconds without milliseconds

    - #### DataProcessor

          public DataProcessor(java.time.temporal.TemporalAmount d)

      Creates new DataProcessor object for the given time duration. The given duration will be substracted from current time.
      Parameters:
        `d` - duration to substract.

  - ### Method Detail

    - #### datasource

          public void datasource(String name,
                                 FetchData fetchData)

      Adds DEF datasource with datasource values already available in the FetchData object. This method is used internally by Rrd4j and probably has no purpose outside of it.
      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - Source name.
        `fetchData` - Fetched data containing values for the given source name.

    - #### datasource

          public void datasource(String name,
                                 IPlottable plottable)

      Adds a custom, `plottable` datasource (PDEF). The datapoints should be made available by a class extending `Plottable` class.
      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - source name.
        `plottable` - class that extends Plottable class and is suited for graphing.

    - #### datasource

          public void datasource(String name,
                                 String rpnExpression)

      Adds complex source (CDEF). Complex sources are evaluated using the supplied `RPN` expression. Complex source `name` can be used:
      - To specify sources for line, area and stack plots.
      - To define other complex sources.
      The supported RPN functions, operators and constants are detailed at RRD4J's wiki.

      Rrd4j does not force you to specify at least one simple source name as RRDTool.

      For more details on RPN see RRDTool's rrdgraph man page.

      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - source name.
        `rpnExpression` - RPN expression containing comma delimited simple and complex source names, RPN constants, functions and operators.

    - #### datasource

          public void datasource(String name,
                                 String dsName,
                                 FetchData fetchData)

      Adds DEF datasource with datasource values already available in the FetchData object. This method is used internally by Rrd4j and probably has no purpose outside of it. The values will be extracted from dsName in fetchData.
      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - Source name.
        `dsName` - Source name in the fetch data.
        `fetchData` - Fetched data containing values for the given source name.

    - #### datasource

          public void datasource(String name,
                                 String file,
                                 String dsName,
                                 ConsolFun consolFunc)

      Adds simple datasource (DEF). Simple source `name` can be used:
      - To specify sources for line, area and stack plots.
      - To define complex sources
      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - source name.
        `file` - Path to RRD file.
        `dsName` - Datasource name defined in the RRD file.
        `consolFunc` - Consolidation function that will be used to extract data from the RRD

    - #### datasource

          public void datasource(String name,
                                 String file,
                                 String dsName,
                                 ConsolFun consolFunc,
                                 RrdBackendFactory backend)

      Adds simple source (DEF). Source `name` can be used:
      - To specify sources for line, area and stack plots.
      - To define complex sources
      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - Source name.
        `file` - Path to RRD file.
        `dsName` - Data source name defined in the RRD file.
        `consolFunc` - Consolidation function that will be used to extract data from the RRD file ("AVERAGE", "MIN", "MAX" or "LAST" - these string constants are conveniently defined in the `ConsolFun` class).
        `backend` - Name of the RrdBackendFactory that should be used for this RrdDb.

    - #### datasource

          public void datasource(String name,
                                 String defName,
                                 Variable var)

      Creates a datasource that performs a variable calculation on an another named datasource to yield a single combined timestamp/value.

      Requires that the other datasource has already been defined; otherwise, it'll end up with no data

      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - - the new virtual datasource name
        `defName` - - the datasource from which to extract the percentile. Must be a previously defined virtual datasource
        `var` - - a new instance of a Variable used to do the calculation

    - #### datasource

          public void datasource(String name,
                                 URI rrdUri,
                                 String dsName,
                                 ConsolFun consolFunc)

      Adds simple datasource (DEF). Simple source `name` can be used:
      - To specify sources for line, area and stack plots.
      - To define complex sources
      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - source name.
        `rrdUri` - URI to RRD file.
        `dsName` - Datasource name defined in the RRD file.
        `consolFunc` - Consolidation function that will be used to extract data from the RRD

    - #### datasource

          public void datasource(String name,
                                 URI uri,
                                 String dsName,
                                 ConsolFun consolFunc,
                                 RrdBackendFactory backend)

      Adds simple source (DEF). Source `name` can be used:
      - To specify sources for line, area and stack plots.
      - To define complex sources
      Specified by:
        `datasource` in interface `DataHolder`
      Parameters:
        `name` - Source name.
        `uri` - URI to RRD file.
        `dsName` - Data source name defined in the RRD file.
        `consolFunc` - Consolidation function that will be used to extract data from the RRD file ("AVERAGE", "MIN", "MAX" or "LAST" - these string constants are conveniently defined in the `ConsolFun` class).
        `backend` - Name of the RrdBackendFactory that should be used for this RrdDb.

    - #### dump

          public String dump()

      Dumps timestamps and values of all datasources in a tabular form. Very useful for debugging.
      Returns:
        Dumped object content.

    - #### getEndTime

          public long getEndTime()

      Description copied from interface: `DataHolder`
      Returns ending timestamp.
      Specified by:
        `getEndTime` in interface `DataHolder`
      Returns:
        Ending timestamp in seconds

    - #### getFetchRequestResolution

          public long getFetchRequestResolution()

      Returns desired RRD archive step (resolution) in seconds to be used while fetching data from RRD files. In other words, this value will used as the last parameter of `RrdDb.createFetchRequest()` method when this method is called internally by this DataProcessor.
      Returns:
        Desired archive step (fetch resolution) in seconds.

    - #### getLastRrdArchiveUpdateTime

          public long getLastRrdArchiveUpdateTime()

      Returns time when last RRD archive was updated (all RRD files are considered).
      Returns:
        Last archive update time for all RRD files in this DataProcessor

    - #### getPixelCount

          public int getPixelCount()

      Returns the number of pixels (target graph width). See `setPixelCount(int)` for more information.
      Returns:
        Target graph width

    - #### getPool

          public RrdDbPool getPool()

      Specified by:
        `getPool` in interface `DataHolder`

    - #### getSource

          Source getSource(String sourceName)

    - #### getSourceNames

          public String[] getSourceNames()

      Returns array of datasource names defined in this DataProcessor.
      Returns:
        array of datasource names

    - #### getStartTime

          public long getStartTime()

      Description copied from interface: `DataHolder`
      Returns starting timestamp.
      Specified by:
        `getStartTime` in interface `DataHolder`
      Returns:
        Starting timestamp in seconds

    - #### getStep

          public long getStep()

      Returns the time step used for data processing. Initially, this method returns zero. Once `processData()` is finished, the method will return the time stamp interval.
      Specified by:
        `getStep` in interface `DataHolder`
      Returns:
        Step used for data processing.

    - #### getTimestamps

          public long[] getTimestamps()

      Returns consolidated timestamps created with the `processData()` method.
      Returns:
        array of timestamps in seconds

    - #### getTimestampsPerPixel

          public long[] getTimestampsPerPixel()

      Calculates timestamps which correspond to individual pixels on the graph based on the graph width set with a `setPixelCount(int)` method call.
      Returns:
        Array of timestamps

    - #### getTimestampsPerPixel

          public long[] getTimestampsPerPixel(int pixelCount)

      Calculates timestamps which correspond to individual pixels on the graph. It also set the timestampsPerPixel value.
      Parameters:
        `pixelCount` - Graph width
      Returns:
        Array of timestamps

    - #### getTimeZone

          public TimeZone getTimeZone()

      Specified by:
        `getTimeZone` in interface `DataHolder`

    - #### getValues

          public double[][] getValues()

      Returns an array of all datasource values for all datasources. Each row in this two-dimensional array represents an array of calculated values for a single datasource. The order of rows is the same as the order in which datasources were added to this DataProcessor object.
      Returns:
        All datasource values for all datasources. The first index is the index of the datasource, the second index is the index of the datasource value. The number of datasource values is equal to the number of timestamps returned with `getTimestamps()` method.
      Throws:
        `IllegalArgumentException` - Thrown if invalid datasource name is specified, or if datasource values are not yet calculated (method `processData()` was not called)

    - #### getValues

          public double[] getValues(String sourceName)

      Returns calculated values for a single datasource. Corresponding timestamps can be obtained from the `getTimestamps()` method.
      Parameters:
        `sourceName` - Datasource name
      Returns:
        an array of datasource values
      Throws:
        `IllegalArgumentException` - Thrown if invalid datasource name is specified, or if datasource values are not yet calculated (method `processData()` was not called)

    - #### getValuesPerPixel

          public double[] getValuesPerPixel(String sourceName)

      Method used to calculate datasource values which should be presented on the graph based on the graph width set with a `setPixelCount(int)` method call. Each value returned represents a single pixel on the graph. Corresponding timestamp can be found in the array returned from `getTimestampsPerPixel()` method.
      Parameters:
        `sourceName` - Datasource name
      Returns:
        Per-pixel datasource values
      Throws:
        `IllegalArgumentException` - Thrown if datasource values are not yet calculated (method `processData()` was not called)

    - #### getValuesPerPixel

          public double[] getValuesPerPixel(String sourceName,
                                            int pixelCount)

      Method used to calculate datasource values which should be presented on the graph based on the desired graph width. Each value returned represents a single pixel on the graph. Corresponding timestamp can be found in the array returned from `getTimestampsPerPixel()` method.
      Parameters:
        `sourceName` - Datasource name
        `pixelCount` - Graph width
      Returns:
        Per-pixel datasource values
      Throws:
        `IllegalArgumentException` - Thrown if datasource values are not yet calculated (method `processData()` was not called)

    - #### getVariable

          public Variable.Value getVariable(String sourceName)

      Extract the variable value from an already define Variable datasource (a VDEF)
      Parameters:
        `sourceName` - Datasource name
      Returns:
        A combined time and value extracted calculated from the datasource

    - #### getVariable

          public Variable.Value getVariable(String sourceName,
                                            Variable var)

      Returns single aggregated value for a single datasource.
      Parameters:
        `sourceName` - Datasource name
        `var` - variable that will generate value
      Returns:
        A combined time and value extracted calculated from the datasource

    - #### isPoolUsed

          public boolean isPoolUsed()

      Returns boolean value representing `RrdDbPool` usage policy.
      Specified by:
        `isPoolUsed` in interface `DataHolder`
      Returns:
        true, if the pool will be used internally to fetch data from RRD files, false otherwise.

    - #### processData

          public void processData()
                           throws IOException

      Method that should be called once all datasources are defined. Data will be fetched from RRD files, RPN expressions will be calculated, etc.
      Throws:
        `IOException` - Thrown in case of I/O error (while fetching data from RRD files)

    - #### setEndTime

          public void setEndTime(long time)

      Description copied from interface: `DataHolder`
      Sets the time when the graph should end. Time in seconds since epoch (1970-01-01) is required. Negative numbers are relative to the current time.
      Specified by:
        `setEndTime` in interface `DataHolder`
      Parameters:
        `time` - Ending time for the graph in seconds since epoch

    - #### setFetchRequestResolution

          public void setFetchRequestResolution(long fetchRequestResolution)

      Sets desired RRD archive step in seconds to be used internally while fetching data from RRD files. In other words, this value will used as the last parameter of `RrdDb.createFetchRequest()` method when this method is called internally by this DataProcessor. If this method is never called, fetch request resolution defaults to 1 (smallest possible archive step will be chosen automatically).
      Parameters:
        `fetchRequestResolution` - Desired archive step (fetch resolution) in seconds.

    - #### setPixelCount

          public void setPixelCount(int pixelCount)

      Sets the number of pixels (target graph width). This number is used only to calculate pixel coordinates for Rrd4j graphs (methods `getValuesPerPixel(String)` and `getTimestampsPerPixel()`), but has influence neither on datasource values calculated with the `processData()` method nor on aggregated values returned from `getAggregates(String)` and similar methods. In other words, aggregated values will not change once you decide to change the dimension of your graph.
      Parameters:
        `pixelCount` - The number of pixels. If you process RRD data in order to display it on the graph, this should be the width of your graph.

    - #### setPool

          public void setPool(RrdDbPool pool)

      Defines the `RrdDbPool` to use. If not defined, but {`setPoolUsed(boolean)` set to true, the default `RrdDbPool.getInstance()` will be used.
      Specified by:
        `setPool` in interface `DataHolder`
      Parameters:
        `pool` - an optional pool to use.

    - #### setPoolUsed

          public void setPoolUsed(boolean poolUsed)

      Sets the `RrdDbPool` usage policy.
      Specified by:
        `setPoolUsed` in interface `DataHolder`
      Parameters:
        `poolUsed` - true, if the pool should be used to fetch data from RRD files, false otherwise.

    - #### setStartTime

          public void setStartTime(long time)

      Description copied from interface: `DataHolder`
      Sets the time when the graph should start. Time in seconds since epoch (1970-01-01) is required. Negative numbers are relative to the current time.
      Specified by:
        `setStartTime` in interface `DataHolder`
      Parameters:
        `time` - Starting time for the graph in seconds since epoch

    - #### setStep

          public void setStep(long step)

      Once data are fetched, the step value will be used to generate values. If not defined, or set to 0, a optimal step will be calculated.
      Specified by:
        `setStep` in interface `DataHolder`
      Parameters:
        `step` - Default to 0.

    - #### setTimeSpan

          public void setTimeSpan(long startTime,
                                  long endTime)

      Description copied from interface: `DataHolder`
      Sets starting and ending time for the for the graph. Timestamps in seconds since epoch are required. Negative numbers are relative to the current time.
      Specified by:
        `setTimeSpan` in interface `DataHolder`
      Parameters:
        `startTime` - Starting time in seconds since epoch
        `endTime` - Ending time in seconds since epoch

    - #### setTimeZone

          public void setTimeZone(TimeZone tz)

      Description copied from interface: `DataHolder`
      Set the time zone used for the legend.
      Specified by:
        `setTimeZone` in interface `DataHolder`
      Parameters:
        `tz` - the time zone to set