org.rrd4j.core

## Class RrdBackendFactory

- java.lang.Object
- - org.rrd4j.core.RrdBackendFactory

- All Implemented Interfaces:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    RrdFileBackendFactory, RrdMemoryBackendFactory

      public abstract class RrdBackendFactory
      extends Object
      implements Closeable

  Base (abstract) backend factory class which holds references to all concrete backend factories and defines abstract methods which must be implemented in all concrete factory implementations.

  Factory classes are used to create concrete `RrdBackend` implementations. Each factory creates unlimited number of specific backend objects.

  Rrd4j supports six different backend types (backend factories) out of the box:

  - `RrdRandomAccessFileBackend`: objects of this class are created from the `RrdRandomAccessFileBackendFactory` class. This was the default backend used in all Rrd4j releases before 1.4.0 release. It uses java.io.* package and RandomAccessFile class to store RRD data in files on the disk.
  - `RrdSafeFileBackend`: objects of this class are created from the `RrdSafeFileBackendFactory` class. It uses java.io.* package and RandomAccessFile class to store RRD data in files on the disk. This backend is SAFE: it locks the underlying RRD file during update/fetch operations, and caches only static parts of a RRD file in memory. Therefore, this backend is safe to be used when RRD files should be shared between several JVMs at the same time. However, this backend is *slow* since it does not use fast java.nio.* package (it's still based on the RandomAccessFile class).
  - `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 is the default backend 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.

  Each backend factory used to be identified by its `name`. Constructors are provided in the `RrdDb` class to create RrdDb objects (RRD databases) backed with a specific backend.

  A more generic management was added in version 3.2 that allows multiple instances of a backend to be used. Each backend can manage custom URL. They are tried in the declared order by the `setActiveFactories(RrdBackendFactory...)` or `addFactories(RrdBackendFactory...)` and the method `canStore(URI)` return true when it can manage the given URI. Using `setActiveFactories(RrdBackendFactory...)` with new created instance is the preferred way to manage factories, as it provides a much precise control of creation and end of life of factories.

  Since 3.4, using only `setActiveFactories(RrdBackendFactory...)` and `addActiveFactories(RrdBackendFactory...)` will not register any named backend at all. `getDefaultFactory()` will return the first active factory. All methods using named backend and the registry of factory were deprecated.

  For default implementation, the path is separated in a root URI prefix and the path components. The root URI can be used to identify different name spaces or just be `/`.

  See javadoc for `RrdBackend` to find out how to create your custom backends.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `cachingAllowed`
    `static String` | `DEFAULTFACTORY` Default backend factory name.
    `protected String` | `name`
    `protected String` | `scheme`
    `protected boolean` | `validateHeader`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `RrdBackendFactory()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addActiveFactories(RrdBackendFactory... newFactories)` Add factories to the list of active factories, i.e.
    `static URI` | `buildGenericUri(String rrdpath)` Try to detect an URI from a path.
    `boolean` | `canStore(URI uri)`
    `void` | `checkClosing()` Check that all phantom reference are indeed safely closed.
    `void` | `close()` A generic close handle, default implementation does nothing.
    `protected abstract boolean` | `exists(String path)` Determines if a storage with the given path already exists.
    `protected boolean` | `exists(URI uri)` Determines if a storage with the given URI already exists.
    `static RrdBackendFactory` | `findFactory(URI uri)` For a given URI, try to find a factory that can manage it in the list of active factories.
    `static java.util.stream.Stream<RrdBackendFactory>` | `getActiveFactories()` Return the current active factories as a stream.
    `(package private) RrdBackend` | `getBackend(RrdDb rrdDb, String path, boolean readOnly)` Creates RrdBackend object for the given storage path.
    `(package private) RrdBackend` | `getBackend(RrdDb rrdDb, URI uri, boolean readOnly)` Creates RrdBackend object for the given storage path.
    `URI` | `getCanonicalUri(URI uri)` Ensure that an URI is returned in a non-ambiguous way.
    `static RrdBackendFactory` | `getDefaultFactory()` Returns the default backend factory.
    `String` | `getName()` Returns the name (primary ID) for the factory.
    `String` | `getPath(URI uri)` Extract the local path from an URI.
    `protected URI` | `getRootUri()`
    `String` | `getScheme()`
    `URI` | `getUri(String path)` Transform an path in a valid URI for this backend.
    `protected abstract RrdBackend` | `open(String path, boolean readOnly)`
    `protected URI` | `resolve(URI rootUri, URI uri, boolean relative)` Try to match an URI against a root URI using a few rules: scheme must match if they are given.
    `static void` | `setActiveFactories(RrdBackendFactory... newFactories)` Set the list of active factories, i.e.
    `protected boolean` | `shouldValidateHeader(String path)` Determines if the header should be validated.
    `protected boolean` | `shouldValidateHeader(URI uri)` Determines if the header should be validated.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### cachingAllowed

          protected final boolean cachingAllowed

    - #### DEFAULTFACTORY

          public static final String DEFAULTFACTORY

      Default backend factory name.
      See Also:
        Constant Field Values

    - #### name

          protected final String name

    - #### scheme

          protected final String scheme

    - #### validateHeader

          protected final boolean validateHeader

  - ### Constructor Detail

    - #### RrdBackendFactory

          protected RrdBackendFactory()

  - ### Method Detail

    - #### addActiveFactories

          public static void addActiveFactories(RrdBackendFactory... newFactories)

      Add factories to the list of active factories, i.e. the factory used to resolve URI.
      Parameters:
        `newFactories` - active factories to add.

    - #### buildGenericUri

          public static URI buildGenericUri(String rrdpath)

      Try to detect an URI from a path. It's needed because of Microsoft Windows path that look's like an URI and to URL-encode the path.
      Parameters:
        `rrdpath` - a file URI that can be a Windows path
      Returns:
        an URI

    - #### canStore

          public boolean canStore(URI uri)

    - #### checkClosing

          public void checkClosing()

      Check that all phantom reference are indeed safely closed.

    - #### close

          public void close()
                     throws IOException

      A generic close handle, default implementation does nothing.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `IOException` - if the close fails

    - #### exists

          protected abstract boolean exists(String path)
                                     throws IOException

      Determines if a storage with the given path already exists.
      Parameters:
        `path` - Storage path
      Returns:
        a boolean.
      Throws:
        `IOException` - in case of I/O error.

    - #### exists

          protected boolean exists(URI uri)
                            throws IOException

      Determines if a storage with the given URI already exists.
      Parameters:
        `uri` - Storage URI.
      Returns:
        a boolean.
      Throws:
        `IOException` - in case of I/O error.

    - #### findFactory

          public static RrdBackendFactory findFactory(URI uri)

      For a given URI, try to find a factory that can manage it in the list of active factories.
      Parameters:
        `uri` - URI to try.
      Returns:
        a `RrdBackendFactory` that can manage that URI.
      Throws:
        `IllegalArgumentException` - when no matching factory is found.

    - #### getActiveFactories

          public static java.util.stream.Stream<RrdBackendFactory> getActiveFactories()

      Return the current active factories as a stream.
      Returns:
        the Stream

    - #### getBackend

          RrdBackend getBackend(RrdDb rrdDb,
                                String path,
                                boolean readOnly)
                         throws IOException

      Creates RrdBackend object for the given storage path.
      Parameters:
        `path` - Storage path
        `readOnly` - True, if the storage should be accessed in read/only mode. False otherwise.
      Returns:
        Backend object which handles all I/O operations for the given storage path
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### getBackend

          RrdBackend getBackend(RrdDb rrdDb,
                                URI uri,
                                boolean readOnly)
                         throws IOException

      Creates RrdBackend object for the given storage path.
      Parameters:
        `rrdDb` -
        `uri` - Storage uri
        `readOnly` - True, if the storage should be accessed in read/only mode. False otherwise.
      Returns:
        Backend object which handles all I/O operations for the given storage path
      Throws:
        `IOException` - Thrown in case of I/O error.

    - #### getCanonicalUri

          public URI getCanonicalUri(URI uri)

      Ensure that an URI is returned in a non-ambiguous way.
      Parameters:
        `uri` - a valid URI for this backend.
      Returns:
        the canonized URI.

    - #### getDefaultFactory

          public static RrdBackendFactory getDefaultFactory()

      Returns the default backend factory. This factory is used to construct `RrdDb` objects if no factory is specified in the RrdDb constructor.
      Returns:
        Default backend factory.

    - #### getName

          public String getName()

      Returns the name (primary ID) for the factory.
      Returns:
        Name of the factory.

    - #### getPath

          public String getPath(URI uri)

      Extract the local path from an URI.
      Parameters:
        `uri` - The URI to parse.
      Returns:
        the local path from the URI.

    - #### getRootUri

          protected URI getRootUri()

    - #### getScheme

          public String getScheme()

      Returns:
        the scheme name for URI, default to getName().toLowerCase()

    - #### getUri

          public URI getUri(String path)

      Transform an path in a valid URI for this backend.
      Parameters:
        `path` - a path local to the current backend.
      Returns:
        an URI that the current backend can handle.

    - #### open

          protected abstract RrdBackend open(String path,
                                             boolean readOnly)
                                      throws IOException

      Throws:
        `IOException`

    - #### resolve

          protected URI resolve(URI rootUri,
                                URI uri,
                                boolean relative)

      Try to match an URI against a root URI using a few rules:
      - scheme must match if they are given.
      - authority must match if they are given.
      - if uri is opaque (scheme:nonabsolute), the scheme specific part is resolve as a relative path.
      - query and fragment is kept as is.
      Parameters:
        `rootUri` - the URI to match against
        `uri` - an URI that the current backend can handle.
        `relative` - if true, return an URI relative to the `rootUri`
      Returns:
        a calculate normalized absolute URI or null if the tried URL don't match against the root.

    - #### setActiveFactories

          public static void setActiveFactories(RrdBackendFactory... newFactories)

      Set the list of active factories, i.e. the factory used to resolve URI.
      Parameters:
        `newFactories` - the new active factories.

    - #### shouldValidateHeader

          protected boolean shouldValidateHeader(String path)

      Determines if the header should be validated.
      Parameters:
        `path` - Storage path
      Returns:
        a boolean.

    - #### shouldValidateHeader

          protected boolean shouldValidateHeader(URI uri)

      Determines if the header should be validated.
      Parameters:
        `uri` - Storage URI
      Returns:
        a boolean.