Package org.rrd4j.core

Class RrdBackend

java.lang.Object

org.rrd4j.core.RrdBackend

Direct Known Subclasses:

ByteBufferBackend, RrdRandomAccessFileBackend

public abstract class RrdBackend
extends Object

Base implementation class for all backend classes. Each Round Robin Database object (RrdDb object) is backed with a single RrdBackend object which performs actual I/O operations on the underlying storage. Rrd4j supports multiple backends out of the box. E.g.:

• RrdRandomAccessFileBackend: objects of this class are created from the RrdRandomAccessFileBackendFactory class. This was the default backend used in all Rrd4j releases prior to 1.4.0. It uses java.io.* package and RandomAccessFile class to store RRD data in files on the disk.
• RrdNioBackend: objects of this class are created from the RrdNioBackendFactory class. The backend uses java.io.* and java.nio.* classes (mapped ByteBuffer) to store RRD data in files on the disk. This backend is fast, very fast, but consumes a lot of memory (borrowed not from the JVM but from the underlying operating system directly). This is the default backend used in Rrd4j since 1.4.0 release.
• RrdMemoryBackend: objects of this class are created from the RrdMemoryBackendFactory class. This backend stores all data in memory. Once JVM exits, all data gets lost. The backend is extremely fast and memory hungry.

To create your own backend in order to provide some custom type of RRD storage, you should do the following:

• Create your custom RrdBackend class (RrdCustomBackend, for example) by extending RrdBackend class. You have to implement all abstract methods defined in the base class.
• Create your custom RrdBackendFactory class (RrdCustomBackendFactory, for example) by extending RrdBackendFactory class. You have to implement all abstract methods defined in the base class. Your custom factory class will actually create custom backend objects when necessary.
• Create instance of your custom RrdBackendFactory and register it as a regular factory available to Rrd4j framework. See javadoc for RrdBackendFactory to find out how to do this.

Author:

Sasa Markovic

Field Summary

Fields

Modifier and Type	Field	Description
protected static ByteOrder	BYTEORDER	All ByteBuffer usage should use this standard order.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	RrdBackend(String path)	Creates backend for a RRD storage with the given path.

Method Summary

Modifier and Type	Method	Description
protected abstract void	close()	Closes the underlying backend.
(package private) void	done(RrdBackendFactory factory, PhantomReference<RrdDb> ref)
protected CharBuffer	getCharBuffer(long offset, int size)	Extract a CharBuffer from the backend, used by readString
RrdBackendFactory	getFactory()
abstract long	getLength()	Returns the number of RRD bytes in the underlying storage.
String	getPath()	Returns path to the storage.
URI	getUri()	Return the URI associated to this backend, using the factory to generate it from the path.
protected boolean	isCachingAllowed()	This method suggests the caching policy to the Rrd4j frontend (high-level) classes.
(package private) static boolean	isInstanceCreated()
protected abstract void	read(long offset, byte[] b)	Reads an array of bytes from the underlying storage starting from the given storage offset.
byte[]	readAll()	Reads all RRD bytes from the underlying storage.
protected double	readDouble(long offset)
protected double[]	readDouble(long offset, int count)
protected int	readInt(long offset)
protected long	readLong(long offset)
protected short	readShort(long offset)
protected String	readString(long offset)
protected void	rrdClose()	Closes the underlying backend.
protected abstract void	setLength(long length)	Sets the number of bytes in the underlying RRD storage.
protected abstract void	write(long offset, byte[] b)	Writes an array of bytes to the underlying storage starting from the given storage offset.
protected void	writeDouble(long offset, double value)
protected void	writeDouble(long offset, double[] values)
protected void	writeDouble(long offset, double value, int count)
protected void	writeInt(long offset, int value)
protected void	writeLong(long offset, long value)
protected void	writeShort(long offset, short value)
protected void	writeString(long offset, String value)
protected void	writeString(long offset, String value, int length)

Methods inherited from class java.lang.Object

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

Field Detail

BYTEORDER

protected static final ByteOrder BYTEORDER

All ByteBuffer usage should use this standard order.

Constructor Detail

RrdBackend

protected RrdBackend(String path)

Creates backend for a RRD storage with the given path.

Parameters:

path - String identifying RRD storage. For files on the disk, this argument should represent file path. Other storage types might interpret this argument differently.

Method Detail

done

void done(RrdBackendFactory factory,
          PhantomReference<RrdDb> ref)

Parameters:

factory - the factory to set

getFactory

public RrdBackendFactory getFactory()

Returns:

the factory

getPath

public String getPath()

Returns path to the storage.

Returns:

Storage path

getUri

public URI getUri()

Return the URI associated to this backend, using the factory to generate it from the path.

Returns:

URI to this backend's rrd.

write

protected abstract void write(long offset,
                              byte[] b)
                       throws IOException

Writes an array of bytes to the underlying storage starting from the given storage offset.

Parameters:

offset - Storage offset.

b - Array of bytes that should be copied to the underlying storage

Throws:

IOException - Thrown in case of I/O error

read

protected abstract void read(long offset,
                             byte[] b)
                      throws IOException

Reads an array of bytes from the underlying storage starting from the given storage offset.

Parameters:

offset - Storage offset.

b - Array which receives bytes from the underlying storage

Throws:

IOException - Thrown in case of I/O error

getLength

public abstract long getLength()
                        throws IOException

Returns the number of RRD bytes in the underlying storage.

Returns:

Number of RRD bytes in the storage.

Throws:

IOException - Thrown in case of I/O error.

setLength

protected abstract void setLength(long length)
                           throws IOException

Sets the number of bytes in the underlying RRD storage. This method is called only once, immediately after a new RRD storage gets created.

Parameters:

length - Length of the underlying RRD storage in bytes.

Throws:

IOException - Thrown in case of I/O error.

close

protected abstract void close()
                       throws IOException

Closes the underlying backend. Used internally, should not be called from external code.

Throws:

IOException - Thrown in case of I/O error

rrdClose

protected void rrdClose()
                 throws IOException

Closes the underlying backend. Call by RrdDb#close() when it's closed. All subclass must keep calling it.

Throws:

IOException - Thrown in case of I/O error

isCachingAllowed

protected boolean isCachingAllowed()

This method suggests the caching policy to the Rrd4j frontend (high-level) classes. If true is returned, frontend classes will cache frequently used parts of a RRD file in memory to improve performance. If false is returned, high level classes will never cache RRD file sections in memory.

Returns:

true if file caching is enabled, false otherwise. By default, the method returns true but it can be overridden in subclasses.

readAll

public final byte[] readAll()
                     throws IOException

Reads all RRD bytes from the underlying storage.

Returns:

RRD bytes

Throws:

IOException - Thrown in case of I/O error

writeShort

protected void writeShort(long offset,
                          short value)
                   throws IOException

Throws:

IOException

writeInt

protected void writeInt(long offset,
                        int value)
                 throws IOException

Throws:

IOException

writeLong

protected void writeLong(long offset,
                         long value)
                  throws IOException

Throws:

IOException

writeDouble

protected void writeDouble(long offset,
                           double value)
                    throws IOException

Throws:

IOException

writeDouble

protected void writeDouble(long offset,
                           double value,
                           int count)
                    throws IOException

Throws:

IOException

writeDouble

protected void writeDouble(long offset,
                           double[] values)
                    throws IOException

Throws:

IOException

writeString

protected final void writeString(long offset,
                                 String value)
                          throws IOException

Throws:

IOException

writeString

protected void writeString(long offset,
                           String value,
                           int length)
                    throws IOException

Throws:

IOException

readShort

protected short readShort(long offset)
                   throws IOException

Throws:

IOException

readInt

protected int readInt(long offset)
               throws IOException

Throws:

IOException

readLong

protected long readLong(long offset)
                 throws IOException

Throws:

IOException

readDouble

protected double readDouble(long offset)
                     throws IOException

Throws:

IOException

readDouble

protected double[] readDouble(long offset,
                              int count)
                       throws IOException

Throws:

IOException

getCharBuffer

protected CharBuffer getCharBuffer(long offset,
                                   int size)
                            throws IOException

Extract a CharBuffer from the backend, used by readString

Parameters:

offset - the offset in the rrd

size - the size of the buffer, in character

Returns:

a new CharBuffer

Throws:

IOException - if the read fails

readString

protected final String readString(long offset)
                           throws IOException

Throws:

IOException

isInstanceCreated

static boolean isInstanceCreated()