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

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.