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.

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `RrdBackend(String path)` Creates backend for a RRD storage with the given path.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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()` 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.
    `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 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 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 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

    - #### 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

    - #### done

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

      Parameters:
        `factory` - the factory to set

    - #### 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

    - #### getFactory

          public RrdBackendFactory getFactory()

      Returns:
        the factory

    - #### 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.

    - #### 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.

    - #### 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.

    - #### isInstanceCreated

          static boolean isInstanceCreated()

      Checks if a backend instance has been created.
      Returns:
        true if a backend instance has been created, false otherwise.

    - #### 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

    - #### 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

    - #### readDouble

          protected double readDouble(long offset)
                               throws IOException

      Reads a double value from the underlying storage at the given offset.
      Parameters:
        `offset` - Storage offset.
      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` - Storage offset.
        `count` - Number of double values to read.
      Returns:
        Array of double values 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` - Storage offset.
      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` - Storage offset.
      Returns:
        The long value read from 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` - Storage offset.
      Returns:
        The short value read from storage.
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### readString

          protected final String readString(long offset)
                                     throws IOException

      Reads a string from the underlying storage at the given offset.
      Parameters:
        `offset` - Storage offset.
      Returns:
        The string value read from storage.
      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

    - #### 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.

    - #### 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

    - #### writeDouble

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

      Writes a double value to the underlying storage at the given offset.
      Parameters:
        `offset` - Storage offset.
        `value` - Double value to write.
      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` - Storage offset.
        `values` - Array of double values 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` - Storage offset.
        `value` - Double value to write.
        `count` - Number of times to write the value.
      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` - Storage offset.
        `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` - Storage offset.
        `value` - Long value to write.
      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` - Storage offset.
        `value` - Short value 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` - Storage offset.
        `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` - Storage offset.
        `value` - String value to write.
        `length` - Fixed length for the string storage.
      Throws:
        `IOException` - Thrown in case of I/O error.