## org.jrobin.core
Class RrdDef

    java.lang.Object
      org.jrobin.core.RrdDef

public class RrdDef
extends java.lang.Object

Class to represent definition of new Round Robin Database (RRD). Object of this class is used to create new RRD from scratch - pass its reference as a `RrdDb` constructor argument (see documentation for `RrdDb` class). `RrdDef` object does not actually create new RRD. It just holds all necessary information which will be used during the actual creation process

RRD definition (RrdDef object) consists of the following elements:

- path to RRD that will be created
- starting timestamp
- step
- one or more datasource definitions
- one or more archive definitions

RrdDef provides API to set all these elements. For the complete explanation of all RRD definition parameters, see RRDTool's rrdcreate man page.

Field Summary
`static long` `DEFAULT_INITIAL_SHIFT` if not specified in constructor, starting timestamp will be set to the current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10)
`static long` `DEFAULT_STEP` default RRD step to be used if not specified in constructor (300 seconds)

Constructor Summary
`RrdDef(java.lang.String path)` Creates new RRD definition object with the given path.
`RrdDef(java.lang.String path, long step)` Creates new RRD definition object with the given path and step.
`RrdDef(java.lang.String path, long startTime, long step)` Creates new RRD definition object with the given path, starting timestamp and step.

Method Summary
`void` `addArchive(ArcDef arcDef)` Adds single archive definition represented with object of class `ArcDef`.
`void` `addArchive(ArcDef[] arcDefs)` Adds archive definitions to RRD definition in bulk.
`void` `addArchive(java.lang.String rrdToolArcDef)` Adds single archive to RRD definition from a RRDTool-like archive definition string.
`void` `addArchive(java.lang.String consolFun, double xff, int steps, int rows)` Adds single archive definition by specifying its consolidation function, X-files factor, number of steps and rows.
`void` `addDatasource(DsDef dsDef)` Adds single datasource definition represented with object of class `DsDef`.
`void` `addDatasource(DsDef[] dsDefs)` Adds data source definitions to RRD definition in bulk.
`void` `addDatasource(java.lang.String rrdToolDsDef)` Adds single datasource to RRD definition from a RRDTool-like datasource definition string.
`void` `addDatasource(java.lang.String dsName, java.lang.String dsType, long heartbeat, double minValue, double maxValue)` Adds single datasource to RRD definition by specifying its data source name, source type, heartbeat, minimal and maximal value.
`java.lang.String` `dump()` Returns string that represents all specified RRD creation parameters.
`boolean` `equals(java.lang.Object obj)` Compares the current RrdDef with another.
`java.lang.String` `exportXmlTemplate()` Exports RrdDef object to string in XML format.
`void` `exportXmlTemplate(java.io.OutputStream out)` Exports RrdDef object to output stream in XML format.
`void` `exportXmlTemplate(java.lang.String filePath)` Exports RrdDef object to a file in XML format.
`int` `getArcCount()` Returns number of defined archives.
`ArcDef[]` `getArcDefs()` Returns all archive definition objects specified so far.
`int` `getDsCount()` Returns number of defined datasources.
`DsDef[]` `getDsDefs()` Returns all data source definition objects specified so far.
`long` `getEstimatedSize()` Returns the number of storage bytes required to create RRD from this RrdDef object.
`java.lang.String` `getPath()` Returns path for the new RRD
`long` `getStartTime()` Returns starting timestamp for the RRD that should be created.
`long` `getStep()` Returns time step for the RRD that will be created.
`void` `setPath(java.lang.String path)` Sets path to RRD.
`void` `setStartTime(java.util.Date date)` Sets RRD's starting timestamp.
`void` `setStartTime(java.util.GregorianCalendar gc)` Sets RRD's starting timestamp.
`void` `setStartTime(long startTime)` Sets RRD's starting timestamp.
`void` `setStep(long step)` Sets RRD's time step.

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

Field Detail

### DEFAULT_STEP

    public static final long DEFAULT_STEP

  default RRD step to be used if not specified in constructor (300 seconds)

  See Also:
    Constant Field Values

### DEFAULT_INITIAL_SHIFT

    public static final long DEFAULT_INITIAL_SHIFT

  if not specified in constructor, starting timestamp will be set to the current timestamp plus DEFAULT_INITIAL_SHIFT seconds (-10)

  See Also:
    Constant Field Values

Constructor Detail

### RrdDef

    public RrdDef(java.lang.String path)
           throws RrdException

  Creates new RRD definition object with the given path. When this object is passed to `RrdDb` constructor, new RRD will be created using the specified path.

Parameters:
  `path` - Path to new RRD.
Throws:
  `RrdException` - Thrown if name is invalid (null or empty).

### RrdDef

    public RrdDef(java.lang.String path,
                  long step)
           throws RrdException

  Creates new RRD definition object with the given path and step.

Parameters:
  `path` - Path to new RRD.
  `step` - RRD step.
Throws:
  `RrdException` - Thrown if supplied parameters are invalid.

### RrdDef

    public RrdDef(java.lang.String path,
                  long startTime,
                  long step)
           throws RrdException

  Creates new RRD definition object with the given path, starting timestamp and step.

Parameters:
  `path` - Path to new RRD.
  `startTime` - RRD starting timestamp.
  `step` - RRD step.
Throws:
  `RrdException` - Thrown if supplied parameters are invalid.

Method Detail

### getPath

    public java.lang.String getPath()

  Returns path for the new RRD

  Returns:
    path to the new RRD which should be created

### getStartTime

    public long getStartTime()

  Returns starting timestamp for the RRD that should be created.

  Returns:
    RRD starting timestamp

### getStep

    public long getStep()

  Returns time step for the RRD that will be created.

  Returns:
    RRD step

### setPath

    public void setPath(java.lang.String path)

  Sets path to RRD.

  Parameters:
    `path` - to new RRD.

### setStartTime

    public void setStartTime(long startTime)

  Sets RRD's starting timestamp.

  Parameters:
    `startTime` - starting timestamp.

### setStartTime

    public void setStartTime(java.util.Date date)

  Sets RRD's starting timestamp.

  Parameters:
    `date` - starting date

### setStartTime

    public void setStartTime(java.util.GregorianCalendar gc)

  Sets RRD's starting timestamp.

  Parameters:
    `gc` - starting date

### setStep

    public void setStep(long step)

  Sets RRD's time step.

  Parameters:
    `step` - RRD time step.

### addDatasource

    public void addDatasource(DsDef dsDef)
                       throws RrdException

  Adds single datasource definition represented with object of class `DsDef`.

  Parameters:
    `dsDef` - Datasource definition.
  Throws:
    `RrdException` - Thrown if new datasource definition uses already used data source name.

### addDatasource

    public void addDatasource(java.lang.String dsName,
                              java.lang.String dsType,
                              long heartbeat,
                              double minValue,
                              double maxValue)
                       throws RrdException

  Adds single datasource to RRD definition by specifying its data source name, source type, heartbeat, minimal and maximal value. For the complete explanation of all data source definition parameters see RRDTool's rrdcreate man page.

  Parameters:
    `dsName` - Data source name.
    `dsType` - Data source type. Valid types are "COUNTER", "GAUGE", "DERIVE" and "ABSOLUTE".
    `heartbeat` - Data source heartbeat.
    `minValue` - Minimal acceptable value. Use `Double.NaN` if unknown.
    `maxValue` - Maximal acceptable value. Use `Double.NaN` if unknown.
  Throws:
    `RrdException` - Thrown if new datasource definition uses already used data source name.

### addDatasource

    public void addDatasource(java.lang.String rrdToolDsDef)
                       throws RrdException

  Adds single datasource to RRD definition from a RRDTool-like datasource definition string. The string must have six elements separated with colons (:) in the following order:

       DS:name:type:heartbeat:minValue:maxValue

  For example:

       DS:input:COUNTER:600:0:U

  For more information on datasource definition parameters see `rrdcreate` man page.

  Parameters:
    `rrdToolDsDef` - Datasource definition string with the syntax borrowed from RRDTool.
  Throws:
    `RrdException` - Thrown if invalid string is supplied.

### addDatasource

    public void addDatasource(DsDef[] dsDefs)
                       throws RrdException

  Adds data source definitions to RRD definition in bulk.

  Parameters:
    `dsDefs` - Array of data source definition objects.
  Throws:
    `RrdException` - Thrown if duplicate data source name is used.

### addArchive

    public void addArchive(ArcDef arcDef)
                    throws RrdException

  Adds single archive definition represented with object of class `ArcDef`.

  Parameters:
    `arcDef` - Archive definition.
  Throws:
    `RrdException` - Thrown if archive with the same consolidation function and the same number of steps is already added.

### addArchive

    public void addArchive(ArcDef[] arcDefs)
                    throws RrdException

  Adds archive definitions to RRD definition in bulk.

  Parameters:
    `arcDefs` - Array of archive definition objects
  Throws:
    `RrdException` - Thrown if RRD definition already contains archive with the same consolidation function and the same number of steps.

### addArchive

    public void addArchive(java.lang.String consolFun,
                           double xff,
                           int steps,
                           int rows)
                    throws RrdException

  Adds single archive definition by specifying its consolidation function, X-files factor, number of steps and rows. For the complete explanation of all archive definition parameters see RRDTool's rrdcreate man page.

  Parameters:
    `consolFun` - Consolidation function. Valid values are "AVERAGE", "MIN", "MAX" and "LAST"
    `xff` - X-files factor. Valid values are between 0 and 1.
    `steps` - Number of archive steps
    `rows` - Number of archive rows
  Throws:
    `RrdException` - Thrown if archive with the same consolidation function and the same number of steps is already added.

### addArchive

    public void addArchive(java.lang.String rrdToolArcDef)
                    throws RrdException

  Adds single archive to RRD definition from a RRDTool-like archive definition string. The string must have five elements separated with colons (:) in the following order:

       RRA:consolidationFunction:XFilesFactor:steps:rows

  For example:

       RRA:AVERAGE:0.5:10:1000

  For more information on archive definition parameters see `rrdcreate` man page.

  Parameters:
    `rrdToolArcDef` - Archive definition string with the syntax borrowed from RRDTool.
  Throws:
    `RrdException` - Thrown if invalid string is supplied.

### getDsDefs

    public DsDef[] getDsDefs()

  Returns all data source definition objects specified so far.

  Returns:
    Array of data source definition objects

### getArcDefs

    public ArcDef[] getArcDefs()

  Returns all archive definition objects specified so far.

  Returns:
    Array of archive definition objects.

### getDsCount

    public int getDsCount()

  Returns number of defined datasources.

  Returns:
    Number of defined datasources.

### getArcCount

    public int getArcCount()

  Returns number of defined archives.

  Returns:
    Number of defined archives.

### dump

    public java.lang.String dump()

  Returns string that represents all specified RRD creation parameters. Returned string has the syntax of RRDTool's `create` command.

  Returns:
    Dumped content of `RrdDb` object.

### exportXmlTemplate

    public void exportXmlTemplate(java.io.OutputStream out)

  Exports RrdDef object to output stream in XML format. Generated XML code can be parsed with `RrdDefTemplate` class.

  Parameters:
    `out` - Output stream

### exportXmlTemplate

    public java.lang.String exportXmlTemplate()

  Exports RrdDef object to string in XML format. Generated XML string can be parsed with `RrdDefTemplate` class.

  Returns:
    XML formatted string representing this RrdDef object

### exportXmlTemplate

    public void exportXmlTemplate(java.lang.String filePath)
                           throws java.io.IOException

  Exports RrdDef object to a file in XML format. Generated XML code can be parsed with `RrdDefTemplate` class.

  Parameters:
    `filePath` - Path to the file
  Throws:
    `java.io.IOException`

### getEstimatedSize

    public long getEstimatedSize()

  Returns the number of storage bytes required to create RRD from this RrdDef object.

  Returns:
    Estimated byte count of the underlying RRD storage.

### equals

    public boolean equals(java.lang.Object obj)

  Compares the current RrdDef with another. RrdDefs are considered equal if:

  - RRD steps match
  - all datasources have exactly the same definition in both RrdDef objects (datasource names, types, heartbeat, min and max values must match)
  - all archives have exactly the same definition in both RrdDef objects (archive consolidation functions, X-file factors, step and row counts must match)

  Parameters:
    `obj` - The second RrdDef object
  Returns:
    true if RrdDefs match exactly, false otherwise