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 Details

  • 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)
      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()