java.lang.Object
org.rrd4j.core.RrdBackend
Direct Known Subclasses:
ByteBufferBackend, RrdRandomAccessFileBackend
public abstract class RrdBackendextends 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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final ByteOrder
    BYTEORDER
    All ByteBuffer usage should use this standard order.
    private static final char
    ENDPRIVATEAREA
    Last character of the unicode private area.
    private static final int
    ENDPRIVATEAREACODEPOINT
    Code point of the last private character.
    private RrdBackendFactory
    factory
    The factory that created the backend.
    private static boolean
    instanceCreated
    True once a single use backend was created.
    private static final int
    MAXUNSIGNEDSHORT
    Largest value held in an unsigned short.
    private long
    nextBigStringOffset
    Where the next big string is written.
    private final String
    path
    The path of the backend's storage.
    private static final int
    PRIVATEAREASIZE
    Number of characters in the private area.
    private PhantomReference<RrdDb>
    ref
    Reference to the database using the backend.
    private static final char
    STARTPRIVATEAREA
    First character of the unicode private area.
    private static final int
    STARTPRIVATEAREACODEPOINT
    Code point of the first private character.

  • 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)
    Set the factory and reference for this backend.
    protected CharBuffer
    getCharBuffer(long offset, int size)
    Extract a CharBuffer from the backend, used by readString
    private static double
    getDouble(byte[] b)
    Decodes a double from big endian bytes.
    private static byte[]
    getDoubleBytes(double value)
    Encodes a double in big endian bytes.
    RrdBackendFactory
    getFactory()
    Get the factory for this backend.
    private static int
    getInt(byte[] b)
    Decodes an int from big endian bytes.
    private static byte[]
    getIntBytes(int value)
    Encodes an int in big endian bytes.
    abstract long
    getLength()
    Returns the number of RRD bytes in the underlying storage.
    private static long
    getLong(byte[] b)
    Decodes a long from big endian bytes.
    private static byte[]
    getLongBytes(long value)
    Encodes a long in big endian bytes.
    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()
    Checks if a backend instance has been created.
    protected abstract void
    read(long offset, byte[] b)
    Reads an array of bytes from the underlying storage starting from the given storage offset.
    final byte[]
    readAll()
    Reads all RRD bytes from the underlying storage.
    protected double
    readDouble(long offset)
    Reads a double value from the underlying storage at the given offset.
    protected double[]
    readDouble(long offset, int count)
    Reads an array of double values from the underlying storage at the given offset.
    protected int
    readInt(long offset)
    Reads an integer value from the underlying storage at the given offset.
    protected long
    readLong(long offset)
    Reads a long value from the underlying storage at the given offset.
    protected short
    readShort(long offset)
    Reads a short value from the underlying storage at the given offset.
    protected final String
    readString(long offset)
    Reads a string from the underlying storage at the given 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)
    Writes a double value to the underlying storage at the given offset.
    protected void
    writeDouble(long offset, double[] values)
    Writes an array of double values to the underlying storage at the given offset.
    protected void
    writeDouble(long offset, double value, int count)
    Writes multiple copies of a double value to the underlying storage at the given offset.
    protected void
    writeInt(long offset, int value)
    Writes an integer value to the underlying storage at the given offset.
    protected void
    writeLong(long offset, long value)
    Writes a long value to the underlying storage at the given offset.
    protected void
    writeShort(long offset, short value)
    Writes a short value to the underlying storage at the given offset.
    protected final void
    writeString(long offset, String value)
    Writes a string to the underlying storage at the given offset.
    protected void
    writeString(long offset, String value, int length)
    Writes a string to the underlying storage at the given offset with a fixed length.

    Methods inherited from class Object

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

  • Field Details

    • BYTEORDER

      protected static final ByteOrder BYTEORDER
      All ByteBuffer usage should use this standard order.

    • STARTPRIVATEAREA

      private static final char STARTPRIVATEAREA
      First character of the unicode private area.
      See Also:

    • ENDPRIVATEAREA

      private static final char ENDPRIVATEAREA
      Last character of the unicode private area.
      See Also:

    • STARTPRIVATEAREACODEPOINT

      private static final int STARTPRIVATEAREACODEPOINT
      Code point of the first private character.

    • ENDPRIVATEAREACODEPOINT

      private static final int ENDPRIVATEAREACODEPOINT
      Code point of the last private character.

    • PRIVATEAREASIZE

      private static final int PRIVATEAREASIZE
      Number of characters in the private area.

    • MAXUNSIGNEDSHORT

      private static final int MAXUNSIGNEDSHORT
      Largest value held in an unsigned short.
      See Also:

    • instanceCreated

      private static volatile boolean instanceCreated
      True once a single use backend was created.

    • path

      private final String path
      The path of the backend's storage.

    • factory

      private RrdBackendFactory factory
      The factory that created the backend.

    • nextBigStringOffset

      private long nextBigStringOffset
      Where the next big string is written.

    • ref

      private PhantomReference<RrdDb> ref
      Reference to the database using the backend.

  • Constructor Details

    • 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 Details

    • done

      void done(RrdBackendFactory factory, PhantomReference<RrdDb> ref)
      Set the factory and reference for this backend.
      Parameters:
      factory - the factory to set
      ref - the phantom reference

    • getFactory

      public RrdBackendFactory getFactory()
      Get the factory for this backend.
      Returns:
      the factory that supplies this backend's URI and caching policy

    • getPath

      public String getPath()
      Returns path to the storage.
      Returns:
      the storage path this backend was opened with

    • 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 - Byte offset into the RRD storage.
      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 - Byte offset into the RRD storage.
      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:
      every RRD byte, read from offset 0 into a buffer sized by getLength()
      Throws:
      IOException - Thrown in case of I/O error

    • writeShort

      protected void writeShort(long offset, short value) throws IOException
      Writes a short value to the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      value - Short value to write.
      Throws:
      IOException - Thrown in case of I/O error.

    • writeInt

      protected void writeInt(long offset, int value) throws IOException
      Writes an integer value to the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      value - Integer value to write.
      Throws:
      IOException - Thrown in case of I/O error.

    • writeLong

      protected void writeLong(long offset, long value) throws IOException
      Writes a long value to the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      value - Long value to write.
      Throws:
      IOException - Thrown in case of I/O error.

    • writeDouble

      protected void writeDouble(long offset, double value) throws IOException
      Writes a double value to the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      value - Double value to write.
      Throws:
      IOException - Thrown in case of I/O error.

    • writeDouble

      protected void writeDouble(long offset, double value, int count) throws IOException
      Writes multiple copies of a double value to the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      value - Double value to write.
      count - Number of times to write the value.
      Throws:
      IOException - Thrown in case of I/O error.

    • writeDouble

      protected void writeDouble(long offset, double[] values) throws IOException
      Writes an array of double values to the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      values - Array of double values to write.
      Throws:
      IOException - Thrown in case of I/O error.

    • writeString

      protected final void writeString(long offset, String value) throws IOException
      Writes a string to the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      value - String value to write.
      Throws:
      IOException - Thrown in case of I/O error.

    • writeString

      protected void writeString(long offset, String value, int length) throws IOException
      Writes a string to the underlying storage at the given offset with a fixed length.
      Parameters:
      offset - Byte offset into the RRD storage.
      value - String value to write.
      length - Fixed length for the string storage.
      Throws:
      IOException - Thrown in case of I/O error.

    • readShort

      protected short readShort(long offset) throws IOException
      Reads a short value from the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      Returns:
      The short value read from storage.
      Throws:
      IOException - Thrown in case of I/O error.

    • readInt

      protected int readInt(long offset) throws IOException
      Reads an integer value from the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      Returns:
      The integer value read from storage.
      Throws:
      IOException - Thrown in case of I/O error.

    • readLong

      protected long readLong(long offset) throws IOException
      Reads a long value from the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      Returns:
      The long value read from storage.
      Throws:
      IOException - Thrown in case of I/O error.

    • readDouble

      protected double readDouble(long offset) throws IOException
      Reads a double value from the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      Returns:
      The double value read from storage.
      Throws:
      IOException - Thrown in case of I/O error.

    • readDouble

      protected double[] readDouble(long offset, int count) throws IOException
      Reads an array of double values from the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      count - Number of double values to read.
      Returns:
      Array of double values read from storage.
      Throws:
      IOException - Thrown in case of I/O error.

    • 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
      Reads a string from the underlying storage at the given offset.
      Parameters:
      offset - Byte offset into the RRD storage.
      Returns:
      The string value read from storage.
      Throws:
      IOException - Thrown in case of I/O error.

    • getIntBytes

      private static byte[] getIntBytes(int value)
      Encodes an int in big endian bytes.
      Parameters:
      value - the value to encode
      Returns:
      the four bytes

    • getLongBytes

      private static byte[] getLongBytes(long value)
      Encodes a long in big endian bytes.
      Parameters:
      value - the value to encode
      Returns:
      the eight bytes

    • getDoubleBytes

      private static byte[] getDoubleBytes(double value)
      Encodes a double in big endian bytes.
      Parameters:
      value - the value to encode
      Returns:
      the eight bytes

    • getInt

      private static int getInt(byte[] b)
      Decodes an int from big endian bytes.
      Parameters:
      b - the four bytes to read
      Returns:
      the integer decoded

    • getLong

      private static long getLong(byte[] b)
      Decodes a long from big endian bytes.
      Parameters:
      b - the eight bytes to read
      Returns:
      the long decoded

    • getDouble

      private static double getDouble(byte[] b)
      Decodes a double from big endian bytes.
      Parameters:
      b - the eight bytes to read
      Returns:
      the double decoded

    • isInstanceCreated

      static boolean isInstanceCreated()
      Checks if a backend instance has been created.
      Returns:
      true if a backend instance has been created, false otherwise.