java.lang.Object
org.rrd4j.core.RrdBackendFactory
All Implemented Interfaces:
Closeable, AutoCloseable
Direct Known Subclasses:
RrdFileBackendFactory, RrdMemoryBackendFactory
public abstract class RrdBackendFactoryextends 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...) 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 Details

    • DEFAULTFACTORY

      public static final String DEFAULTFACTORY
      Default backend factory name.
      See Also:

    • activeFactories

      private static final List<RrdBackendFactory> activeFactories
      The factories with backends currently open.

    • URIPATTERN

      private static final Pattern URIPATTERN
      Parses a backend URI into scheme, authority, path, query and fragment.

    • refQueue

      private final ReferenceQueue<RrdDb> refQueue
      Queue the closing references enqueue themselves on.

    • name

      protected final String name
      Storage name this factory reports to RrdDb.

    • cachingAllowed

      protected final boolean cachingAllowed
      Whether this factory's backends may cache data in memory.

    • scheme

      protected final String scheme
      URI scheme this factory's storage URIs start with.

    • validateHeader

      protected final boolean validateHeader
      Whether opened files must carry the RRD header.

  • Constructor Details

    • RrdBackendFactory

      protected RrdBackendFactory()
      Reads the storage settings off the subclass's backend annotation.

  • Method Details

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

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

    • getActiveFactories

      public static java.util.stream.Stream<RrdBackendFactory> getActiveFactories()
      Return the current active factories as a stream.
      Returns:
      a stream over the active factories, in registration order

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

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

    • 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:
      the URI, or a file: URI when the path is really a Windows path

    • checkClosing

      public void checkClosing()
      Check that all phantom reference are indeed safely closed.

    • getScheme

      public String getScheme()
      The URI scheme that selects this backend, used to build every RRD URI the factory hands out.
      Returns:
      the scheme name for URI, default to getName().toLowerCase()

    • getRootUri

      protected URI getRootUri()
      Builds the root URI for this factory's scheme.
      Returns:
      the root URI formed from this factory's scheme, or an exception if the scheme is not a legal URI scheme

    • canStore

      public boolean canStore(URI uri)
      Tests whether this factory recognises a storage URI.
      Parameters:
      uri - the candidate storage URI to test against this factory
      Returns:
      false unless a subclass overrides this to recognise its own URIs

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

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

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

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

    • open

      protected abstract RrdBackend open(String path, boolean readOnly) throws IOException
      Opens the backend serving a storage path.
      Parameters:
      path - the storage path, relative to this factory's root URI
      readOnly - true to open the storage for reading only, false to allow writes
      Returns:
      the backend that performs all I/O for the given storage path
      Throws:
      IOException - if the storage cannot be opened

    • getBackend

      RrdBackend getBackend(RrdDb rrdDb, String path, boolean readOnly) throws IOException
      Creates RrdBackend object for the given storage path.
      Parameters:
      rrdDb - the pool database the backend is registered against, so it can be told when the backend is closed
      path - File system path of the RRD storage.
      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 - the pool database the backend is registered against, so it can be told when the backend is closed
      uri - Storage uri, resolved to a path by getPath(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.

    • exists

      protected abstract boolean exists(String path) throws IOException
      Determines if a storage with the given path already exists.
      Parameters:
      path - File system path to probe for.
      Returns:
      true if a storage already exists at the given path
      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, resolved to a path by getPath(URI).
      Returns:
      true if a storage already exists at the path the URI resolves to
      Throws:
      IOException - in case of I/O error.

    • shouldValidateHeader

      protected boolean shouldValidateHeader(String path)
      Determines if the header should be validated.
      Parameters:
      path - File system path the decision applies to; the answer does not depend on it.
      Returns:
      true if the RRD header at the given path should be validated

    • shouldValidateHeader

      protected boolean shouldValidateHeader(URI uri)
      Determines if the header should be validated.
      Parameters:
      uri - Storage URI, resolved to a path before the check.
      Returns:
      true if the RRD header should be validated, as decided for the path the URI resolves to

    • getName

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

    • close

      public void close() throws IOException
      A generic close handle, default implementation does nothing.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException - if the close fails