org.jrobin.core
Class FetchData

java.lang.Object
  extended by org.jrobin.core.FetchData
All Implemented Interfaces:
ConsolFuns

public class FetchData
extends Object
implements ConsolFuns

Class used to represent data fetched from the RRD. Object of this class is created when the method fetchData() is called on a FetchRequest object.

Data returned from the RRD is, simply, just one big table filled with timestamps and corresponding datasource values. Use getRowCount() method to count the number of returned timestamps (table rows).

The first table column is filled with timestamps. Time intervals between consecutive timestamps are guaranteed to be equal. Use getTimestamps() method to get an array of timestamps returned.

Remaining columns are filled with datasource values for the whole timestamp range, on a column-per-datasource basis. Use getColumnCount() to find the number of datasources and getValues(i) method to obtain all values for the i-th datasource. Returned datasource values correspond to the values returned with getTimestamps() method.


Field Summary
 
Fields inherited from interface org.jrobin.core.ConsolFuns
CF_AVERAGE, CF_FIRST, CF_LAST, CF_MAX, CF_MIN, CF_TOTAL
 
Method Summary
 String dump()
          Dumps the content of the whole FetchData object.
 String exportXml()
          Dumps fetch data in XML format.
 void exportXml(OutputStream outputStream)
          Dumps fetch data to output stream in XML format.
 void exportXml(String filepath)
          Dumps fetch data to file in XML format.
 double get95Percentile(String dsName)
          Used by ISPs which charge for bandwidth utilization on a "95th percentile" basis.
 double getAggregate(String dsName, String consolFun)
          Returns single aggregated value from the fetched data for a single datasource.
 double getAggregate(String dsName, String consolFun, String rpnExpression)
          Deprecated. This method is preserved just for backward compatibility.
 Aggregates getAggregates(String dsName)
          Returns all aggregated values (MIN, MAX, LAST, FIRST, AVERAGE or TOTAL) calculated from the fetched data for a single datasource.
 long getArcEndTime()
          Returns the timestamp of the last populated slot in the corresponding RRA archive
 long getArcStep()
          Returns the step of the corresponding RRA archive
 int getColumnCount()
          Returns the number of columns fetched from the corresponding RRD.
 int getDsIndex(String dsName)
          Retrieve the table index number of a datasource by name.
 String[] getDsNames()
          Returns array of datasource names found in the corresponding RRD.
 long getFirstTimestamp()
          Returns the first timestamp in this FetchData object.
 long getLastTimestamp()
          Returns the last timestamp in this FecthData object.
 Archive getMatchingArchive()
          Returns Archive object which is determined to be the best match for the timestamps specified in the fetch request.
 FetchRequest getRequest()
          Returns FetchRequest object used to create this FetchData object.
 int getRowCount()
          Returns the number of rows fetched from the corresponding RRD.
 double getRpn95Percentile(String rpnExpression)
          Same as get95Percentile(String), but for a set of values calculated with the given RPN expression.
 double getRpnAggregate(String rpnExpression, String consolFun)
          Returns aggregated value for a set of values calculated by applying an RPN expression to the fetched data.
 Aggregates getRpnAggregates(String rpnExpression)
          Returns all aggregated values for a set of values calculated by applying an RPN expression to the fetched data.
 double[] getRpnValues(String rpnExpression)
          Returns a set of values created by applying RPN expression to the fetched data.
 long getStep()
          Returns the step with which this data was fetched.
 long[] getTimestamps()
          Returns an array of timestamps covering the whole range specified in the FetchReguest object.
 double[][] getValues()
          Returns all archived values for all datasources.
 double[] getValues(int dsIndex)
          Returns all archived values for a single datasource.
 double[] getValues(String dsName)
          Returns all archived values for a single datasource.
 String toString()
          Returns string representing fetched data in a RRDTool-like form.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getRowCount

public int getRowCount()
Returns the number of rows fetched from the corresponding RRD. Each row represents datasource values for the specific timestamp.

Returns:
Number of rows.

getColumnCount

public int getColumnCount()
Returns the number of columns fetched from the corresponding RRD. This number is always equal to the number of datasources defined in the RRD. Each column represents values of a single datasource.

Returns:
Number of columns (datasources).

getTimestamps

public long[] getTimestamps()
Returns an array of timestamps covering the whole range specified in the FetchReguest object.

Returns:
Array of equidistant timestamps.

getStep

public long getStep()
Returns the step with which this data was fetched.

Returns:
Step as long.

getValues

public double[] getValues(int dsIndex)
Returns all archived values for a single datasource. Returned values correspond to timestamps returned with getTimestamps() method.

Parameters:
dsIndex - Datasource index.
Returns:
Array of single datasource values.

getValues

public double[][] getValues()
Returns all archived values for all datasources. Returned values correspond to timestamps returned with getTimestamps() method.

Returns:
Two-dimensional aray of all datasource values.

getValues

public double[] getValues(String dsName)
                   throws RrdException
Returns all archived values for a single datasource. Returned values correspond to timestamps returned with getTimestamps() method.

Parameters:
dsName - Datasource name.
Returns:
Array of single datasource values.
Throws:
RrdException - Thrown if no matching datasource name is found.

getRpnValues

public double[] getRpnValues(String rpnExpression)
                      throws RrdException
Returns a set of values created by applying RPN expression to the fetched data. For example, if you have two datasources named x and y in this FetchData and you want to calculate values for (x+y)/2 use something like:

getRpnValues("x,y,+,2,/");

Parameters:
rpnExpression - RRDTool-like RPN expression
Returns:
Calculated values
Throws:
RrdException - Thrown if invalid RPN expression is supplied

getRequest

public FetchRequest getRequest()
Returns FetchRequest object used to create this FetchData object.

Returns:
Fetch request object.

getFirstTimestamp

public long getFirstTimestamp()
Returns the first timestamp in this FetchData object.

Returns:
The smallest timestamp.

getLastTimestamp

public long getLastTimestamp()
Returns the last timestamp in this FecthData object.

Returns:
The biggest timestamp.

getMatchingArchive

public Archive getMatchingArchive()
Returns Archive object which is determined to be the best match for the timestamps specified in the fetch request. All datasource values are obtained from round robin archives belonging to this archive.

Returns:
Matching archive.

getDsNames

public String[] getDsNames()
Returns array of datasource names found in the corresponding RRD. If the request was filtered (data was fetched only for selected datasources), only datasources selected for fetching are returned.

Returns:
Array of datasource names.

getDsIndex

public int getDsIndex(String dsName)
Retrieve the table index number of a datasource by name. Names are case sensitive.

Parameters:
dsName - Name of the datasource for which to find the index.
Returns:
Index number of the datasources in the value table.

dump

public String dump()
Dumps the content of the whole FetchData object. Useful for debugging.


toString

public String toString()
Returns string representing fetched data in a RRDTool-like form.

Overrides:
toString in class Object
Returns:
Fetched data as a string in a rrdfetch-like output form.

getAggregate

public double getAggregate(String dsName,
                           String consolFun)
                    throws RrdException
Returns single aggregated value from the fetched data for a single datasource.

Parameters:
dsName - Datasource name
consolFun - Consolidation function to be applied to fetched datasource values. Valid consolidation functions are "MIN", "MAX", "LAST", "FIRST", "AVERAGE" and "TOTAL" (these string constants are conveniently defined in the ConsolFuns class)
Returns:
MIN, MAX, LAST, FIRST, AVERAGE or TOTAL value calculated from the fetched data for the given datasource name
Throws:
RrdException - Thrown if the given datasource name cannot be found in fetched data.

getAggregate

public double getAggregate(String dsName,
                           String consolFun,
                           String rpnExpression)
                    throws RrdException,
                           IOException
Deprecated. This method is preserved just for backward compatibility.

Returns aggregated value from the fetched data for a single datasource. Before applying aggregation functions, specified RPN expression is applied to fetched data. For example, if you have a gauge datasource named 'foots' but you want to find the maximum fetched value in meters use something like:

getAggregate("foots", "MAX", "foots,0.3048,*");

Parameters:
dsName - Datasource name
consolFun - Consolidation function (MIN, MAX, LAST, FIRST, AVERAGE or TOTAL)
rpnExpression - RRDTool-like RPN expression
Returns:
Aggregated value
Throws:
RrdException - Thrown if the given datasource name cannot be found in fetched data, or if invalid RPN expression is supplied
IOException - Thrown in case of I/O error (unlikely to happen)

getRpnAggregate

public double getRpnAggregate(String rpnExpression,
                              String consolFun)
                       throws RrdException
Returns aggregated value for a set of values calculated by applying an RPN expression to the fetched data. For example, if you have two datasources named x and y in this FetchData and you want to calculate MAX value of (x+y)/2 use something like:

getRpnAggregate("x,y,+,2,/", "MAX");

Parameters:
rpnExpression - RRDTool-like RPN expression
consolFun - Consolidation function (MIN, MAX, LAST, FIRST, AVERAGE or TOTAL)
Returns:
Aggregated value
Throws:
RrdException - Thrown if invalid RPN expression is supplied

getAggregates

public Aggregates getAggregates(String dsName)
                         throws RrdException
Returns all aggregated values (MIN, MAX, LAST, FIRST, AVERAGE or TOTAL) calculated from the fetched data for a single datasource.

Parameters:
dsName - Datasource name.
Returns:
Simple object containing all aggregated values.
Throws:
RrdException - Thrown if the given datasource name cannot be found in the fetched data.

getRpnAggregates

public Aggregates getRpnAggregates(String rpnExpression)
                            throws RrdException,
                                   IOException
Returns all aggregated values for a set of values calculated by applying an RPN expression to the fetched data. For example, if you have two datasources named x and y in this FetchData and you want to calculate MIN, MAX, LAST, FIRST, AVERAGE and TOTAL value of (x+y)/2 use something like:

getRpnAggregates("x,y,+,2,/");

Parameters:
rpnExpression - RRDTool-like RPN expression
Returns:
Object containing all aggregated values
Throws:
RrdException - Thrown if invalid RPN expression is supplied
IOException

get95Percentile

public double get95Percentile(String dsName)
                       throws RrdException
Used by ISPs which charge for bandwidth utilization on a "95th percentile" basis.

The 95th percentile is the highest source value left when the top 5% of a numerically sorted set of source data is discarded. It is used as a measure of the peak value used when one discounts a fair amount for transitory spikes. This makes it markedly different from the average.

Read more about this topic at:

Rednet or
Bytemark.

Parameters:
dsName - Datasource name
Returns:
95th percentile of fetched source values
Throws:
RrdException - Thrown if invalid source name is supplied

getRpn95Percentile

public double getRpn95Percentile(String rpnExpression)
                          throws RrdException
Same as get95Percentile(String), but for a set of values calculated with the given RPN expression.

Parameters:
rpnExpression - RRDTool-like RPN expression
Returns:
95-percentile
Throws:
RrdException - Thrown if invalid RPN expression is supplied

exportXml

public void exportXml(OutputStream outputStream)
               throws IOException
Dumps fetch data to output stream in XML format.

Parameters:
outputStream - Output stream to dump fetch data to
Throws:
IOException - Thrown in case of I/O error

exportXml

public void exportXml(String filepath)
               throws IOException
Dumps fetch data to file in XML format.

Parameters:
filepath - Path to destination file
Throws:
IOException - Thrown in case of I/O error

exportXml

public String exportXml()
                 throws IOException
Dumps fetch data in XML format.

Returns:
String containing XML formatted fetch data
Throws:
IOException - Thrown in case of I/O error

getArcStep

public long getArcStep()
Returns the step of the corresponding RRA archive

Returns:
Archive step in seconds

getArcEndTime

public long getArcEndTime()
Returns the timestamp of the last populated slot in the corresponding RRA archive

Returns:
Timestamp in seconds


Copyright 2003-2008. All Rights Reserved.