/**
* Closes RRD. No further operations are allowed on this RrdDb object.
*
* @Thrown in case of I/O related error.
*/
public void close()
{
lock (sync)
{
if (!closed)
{
closed = true;
backend.close();
}
}
}
/**
* <p>Constructor used to create RRD files from external file sources with a backend type
* different from default. Supported external file sources are:</p>
* <p/>
* <ul>
* <li>RRDTool/Rrd4n XML file dumps (i.e files created with <code>rrdtool dump</code> command).
* <li>RRDTool binary files.
* </ul>
* <p/>
* <p>Rrd4n and RRDTool use the same format for XML dump and this constructor should be used to
* (re)create Rrd4n RRD files from XML dumps. First, dump the content of a RRDTool
* RRD file (use command line):</p>
* <p/>
* <pre>
* rrdtool dump original.rrd > original.xml
* </pre>
* <p/>
* <p>Than, use the file <code>original.xml</code> to create Rrd4n RRD file named
* <code>copy.rrd</code>:</p>
* <p/>
* <pre>
* RrdDb rrd = new RrdDb("copy.rrd", "original.xml");
* </pre>
* <p/>
* <p>or:</p>
* <p/>
* <pre>
* RrdDb rrd = new RrdDb("copy.rrd", "xml:/original.xml");
* </pre>
* <p/>
* <p>See documentation for {@link #dumpXml(String) dumpXml()} method
* to see how to convert Rrd4n files to RRDTool's format.</p>
* <p/>
* <p>To read RRDTool files directly, specify <code>rrdtool:/</code> prefix in the
* <code>externalPath</code> argument. For example, to create Rrd4n compatible file named
* <code>copy.rrd</code> from the file <code>original.rrd</code> created with RRDTool, use
* the following code:</p>
* <p/>
* <pre>
* RrdDb rrd = new RrdDb("copy.rrd", "rrdtool:/original.rrd");
* </pre>
* <p/>
* <p>Note that the prefix <code>xml:/</code> or <code>rrdtool:/</code> is necessary to distinguish
* between XML and RRDTool's binary sources. If no prefix is supplied, XML format is assumed</p>
*
* @param rrdPath Path to RRD which will be created
* @param externalPath Path to an external file which should be imported, with an optional
* <code>xml:/</code> or <code>rrdtool:/</code> prefix.
* @param factory Backend factory which will be used to create storage (backend) for this RRD.
* @Thrown in case of I/O error
* @see RrdBackendFactory
*/
public RrdDb(String rrdPath, String externalPath, RrdBackendFactory factory)
{
DataImporter reader;
// if (externalPath.startsWith(PREFIX_RRDTool)) {
// String rrdToolPath = externalPath.substring(PREFIX_RRDTool.Length);
// reader = new RrdToolReader(rrdToolPath);
// }
// else if (externalPath.startsWith(PREFIX_XML)) {
// externalPath = externalPath.substring(PREFIX_XML.Length);
// reader = new XmlReader(externalPath);
// }
// else {
reader = new XmlImporter(externalPath);
// }
backend = factory.open(rrdPath, false);
try {
backend.setLength(reader.getEstimatedSize());
// create header
header = new Header(this, reader);
// // create Datasources
// Datasources = new Datasource[reader.getDsCount()];
// for (int i = 0; i < Datasources.Length; i++) {
// Datasources[i] = new Datasource(this, reader, i);
// }
// // create archives
// archives = new Archive[reader.getArcCount()];
// for (int i = 0; i < archives.Length; i++) {
// archives[i] = new Archive(this, reader, i);
// }
reader.release();
// XMLReader is a rather huge DOM tree, release memory ASAP
reader = null;
}
catch (IOException e)
{
backend.close();
throw e;
}
}
/**
* Constructor used to open already existing RRD backed
* with a storage (backend) different from default. Constructor
* obtains read or read/write access to this RRD.
*
* @param path Path to existing RRD.
* @param readOnly Should be set to <code>false</code> if you want to update
* the underlying RRD. If you want just to fetch data from the RRD file
* (read-only access), specify <code>true</code>. If you try to update RRD file
* open in read-only mode (<code>readOnly</code> set to <code>true</code>),
* <code>IOException</code> will be thrown.
* @param factory Backend factory which will be used for this RRD.
* @throws FileNotFoundException Thrown if the requested file does not exist.
* @ Thrown in case of general I/O error (bad RRD file, for example).
* @see RrdBackendFactory
*/
public RrdDb(String path, bool readOnly, RrdBackendFactory factory)
{
if (!factory.exists(path))
{
throw new System.IO.FileNotFoundException("Could not open " + path + " [non existent]");
}
backend = factory.open(path, readOnly);
try
{
// restore header
header = new Header(this, (RrdDef)null);
if (factory.shouldValidateHeader(path))
{
header.validateHeader();
}
// restore Datasources
int dsCount = header.getDsCount();
Datasources = new Datasource[dsCount];
for (int i = 0; i < dsCount; i++)
{
Datasources[i] = new Datasource(this, null);
}
// restore archives
int arcCount = header.getArcCount();
archives = new Archive[arcCount];
for (int i = 0; i < arcCount; i++)
{
archives[i] = new Archive(this, null);
}
}
catch (IOException e)
{
backend.close();
log.ErrorFormat("RrdDb ctor failed on:{0} [{1]}", path, e.Message);
throw e;
}
}
/**
* Constructor used to create new RRD object from the definition object but with a storage
* (backend) different from default.
*
* <p>Rrd4n uses <i>factories</i> to create RRD backend objecs. There are three different
* backend factories supplied with Rrd4n, and each factory has its unique name:</p>
* <p/>
* <ul>
* <li><b>FILE</b>: backends created from this factory will store RRD data to files by using
* java.io.* classes and methods
* <li><b>NIO</b>: backends created from this factory will store RRD data to files by using
* java.nio.* classes and methods
* <li><b>MEMORY</b>: backends created from this factory will store RRD data in memory. This might
* be useful in runtime environments which prohibit disk utilization, or for storing temporary,
* non-critical data (it gets lost as soon as JVM exits).
* </ul>
* <p/>
* <p>For example, to create RRD in memory, use the following code</p>
* <pre>
* RrdBackendFactory factory = RrdBackendFactory.getFactory("MEMORY");
* RrdDb rrdDb = new RrdDb(rrdDef, factory);
* rrdDb.close();
* </pre>
* <p/>
* <p>New RRD file structure is specified with an object of class
* {@link RrdDef <b>RrdDef</b>}. The underlying RRD storage is created as soon
* as the constructor returns.</p>
*
* @param rrdDef RRD definition object
* @param factory The factory which will be used to create storage for this RRD
* @Thrown in case of I/O error
* @see RrdBackendFactory
*/
public RrdDb(RrdDef rrdDef, RrdBackendFactory factory)
{
if (!rrdDef.hasDatasources())
{
throw new ArgumentException("No RRD Datasource specified. At least one is needed.");
}
if (!rrdDef.hasArchives())
{
throw new ArgumentException("No RRD archive specified. At least one is needed.");
}
String path = rrdDef.getPath();
backend = factory.open(path, false);
try
{
backend.setLength(rrdDef.getEstimatedSize());
// create header
header = new Header(this, rrdDef);
// create Datasources
DsDef[] dsDefs = rrdDef.getDsDefs();
Datasources = new Datasource[dsDefs.Length];
for (int i = 0; i < dsDefs.Length; i++)
{
Datasources[i] = new Datasource(this, dsDefs[i]);
}
// create archives
ArcDef[] arcDefs = rrdDef.getArcDefs();
archives = new Archive[arcDefs.Length];
for (int i = 0; i < arcDefs.Length; i++)
{
archives[i] = new Archive(this, arcDefs[i]);
}
}
catch (IOException e)
{
backend.close();
throw;
}
}
/**
* <p>Constructor used to create RRD files from external file sources with a backend type
* different from default. Supported external file sources are:</p>
* <p/>
* <ul>
* <li>RRDTool/Rrd4n XML file dumps (i.e files created with <code>rrdtool dump</code> command).
* <li>RRDTool binary files.
* </ul>
* <p/>
* <p>Rrd4n and RRDTool use the same format for XML dump and this constructor should be used to
* (re)create Rrd4n RRD files from XML dumps. First, dump the content of a RRDTool
* RRD file (use command line):</p>
* <p/>
* <pre>
* rrdtool dump original.rrd > original.xml
* </pre>
* <p/>
* <p>Than, use the file <code>original.xml</code> to create Rrd4n RRD file named
* <code>copy.rrd</code>:</p>
* <p/>
* <pre>
* RrdDb rrd = new RrdDb("copy.rrd", "original.xml");
* </pre>
* <p/>
* <p>or:</p>
* <p/>
* <pre>
* RrdDb rrd = new RrdDb("copy.rrd", "xml:/original.xml");
* </pre>
* <p/>
* <p>See documentation for {@link #dumpXml(String) dumpXml()} method
* to see how to convert Rrd4n files to RRDTool's format.</p>
* <p/>
* <p>To read RRDTool files directly, specify <code>rrdtool:/</code> prefix in the
* <code>externalPath</code> argument. For example, to create Rrd4n compatible file named
* <code>copy.rrd</code> from the file <code>original.rrd</code> created with RRDTool, use
* the following code:</p>
* <p/>
* <pre>
* RrdDb rrd = new RrdDb("copy.rrd", "rrdtool:/original.rrd");
* </pre>
* <p/>
* <p>Note that the prefix <code>xml:/</code> or <code>rrdtool:/</code> is necessary to distinguish
* between XML and RRDTool's binary sources. If no prefix is supplied, XML format is assumed</p>
*
* @param rrdPath Path to RRD which will be created
* @param externalPath Path to an external file which should be imported, with an optional
* <code>xml:/</code> or <code>rrdtool:/</code> prefix.
* @param factory Backend factory which will be used to create storage (backend) for this RRD.
* @Thrown in case of I/O error
* @see RrdBackendFactory
*/
public RrdDb(String rrdPath, String externalPath, RrdBackendFactory factory) {
DataImporter reader;
// if (externalPath.startsWith(PREFIX_RRDTool)) {
// String rrdToolPath = externalPath.substring(PREFIX_RRDTool.Length);
// reader = new RrdToolReader(rrdToolPath);
// }
// else if (externalPath.startsWith(PREFIX_XML)) {
// externalPath = externalPath.substring(PREFIX_XML.Length);
// reader = new XmlReader(externalPath);
// }
// else {
reader = new XmlImporter(externalPath);
// }
backend = factory.open(rrdPath, false);
try {
backend.setLength(reader.getEstimatedSize());
// create header
header = new Header(this, reader);
// // create Datasources
// Datasources = new Datasource[reader.getDsCount()];
// for (int i = 0; i < Datasources.Length; i++) {
// Datasources[i] = new Datasource(this, reader, i);
// }
// // create archives
// archives = new Archive[reader.getArcCount()];
// for (int i = 0; i < archives.Length; i++) {
// archives[i] = new Archive(this, reader, i);
// }
reader.release();
// XMLReader is a rather huge DOM tree, release memory ASAP
reader = null;
}
catch (IOException e)
{
backend.close();
throw e;
}
}
/**
* Constructor used to open already existing RRD backed
* with a storage (backend) different from default. Constructor
* obtains read or read/write access to this RRD.
*
* @param path Path to existing RRD.
* @param readOnly Should be set to <code>false</code> if you want to update
* the underlying RRD. If you want just to fetch data from the RRD file
* (read-only access), specify <code>true</code>. If you try to update RRD file
* open in read-only mode (<code>readOnly</code> set to <code>true</code>),
* <code>IOException</code> will be thrown.
* @param factory Backend factory which will be used for this RRD.
* @throws FileNotFoundException Thrown if the requested file does not exist.
* @ Thrown in case of general I/O error (bad RRD file, for example).
* @see RrdBackendFactory
*/
public RrdDb(String path, bool readOnly, RrdBackendFactory factory)
{
if (!factory.exists(path)) throw new System.IO.FileNotFoundException("Could not open " + path + " [non existent]");
backend = factory.open(path, readOnly);
try
{
// restore header
header = new Header(this, (RrdDef)null);
if (factory.shouldValidateHeader(path))
{
header.validateHeader();
}
// restore Datasources
int dsCount = header.getDsCount();
Datasources = new Datasource[dsCount];
for (int i = 0; i < dsCount; i++)
{
Datasources[i] = new Datasource(this, null);
}
// restore archives
int arcCount = header.getArcCount();
archives = new Archive[arcCount];
for (int i = 0; i < arcCount; i++)
{
archives[i] = new Archive(this, null);
}
}
catch (IOException e)
{
backend.close();
log.ErrorFormat("RrdDb ctor failed on:{0} [{1]}", path, e.Message);
throw e;
}
}
/**
* Constructor used to create new RRD object from the definition object but with a storage
* (backend) different from default.
*
* <p>Rrd4n uses <i>factories</i> to create RRD backend objecs. There are three different
* backend factories supplied with Rrd4n, and each factory has its unique name:</p>
* <p/>
* <ul>
* <li><b>FILE</b>: backends created from this factory will store RRD data to files by using
* java.io.* classes and methods
* <li><b>NIO</b>: backends created from this factory will store RRD data to files by using
* java.nio.* classes and methods
* <li><b>MEMORY</b>: backends created from this factory will store RRD data in memory. This might
* be useful in runtime environments which prohibit disk utilization, or for storing temporary,
* non-critical data (it gets lost as soon as JVM exits).
* </ul>
* <p/>
* <p>For example, to create RRD in memory, use the following code</p>
* <pre>
* RrdBackendFactory factory = RrdBackendFactory.getFactory("MEMORY");
* RrdDb rrdDb = new RrdDb(rrdDef, factory);
* rrdDb.close();
* </pre>
* <p/>
* <p>New RRD file structure is specified with an object of class
* {@link RrdDef <b>RrdDef</b>}. The underlying RRD storage is created as soon
* as the constructor returns.</p>
*
* @param rrdDef RRD definition object
* @param factory The factory which will be used to create storage for this RRD
* @Thrown in case of I/O error
* @see RrdBackendFactory
*/
public RrdDb(RrdDef rrdDef, RrdBackendFactory factory)
{
if (!rrdDef.hasDatasources())
{
throw new ArgumentException("No RRD Datasource specified. At least one is needed.");
}
if (!rrdDef.hasArchives())
{
throw new ArgumentException("No RRD archive specified. At least one is needed.");
}
String path = rrdDef.getPath();
backend = factory.open(path, false);
try
{
backend.setLength(rrdDef.getEstimatedSize());
// create header
header = new Header(this, rrdDef);
// create Datasources
DsDef[] dsDefs = rrdDef.getDsDefs();
Datasources = new Datasource[dsDefs.Length];
for (int i = 0; i < dsDefs.Length; i++)
{
Datasources[i] = new Datasource(this, dsDefs[i]);
}
// create archives
ArcDef[] arcDefs = rrdDef.getArcDefs();
archives = new Archive[arcDefs.Length];
for (int i = 0; i < arcDefs.Length; i++)
{
archives[i] = new Archive(this, arcDefs[i]);
}
}
catch (IOException e)
{
backend.close();
throw;
}
}