Class RrdBackendFactory
- All Implemented Interfaces:
Closeable
,AutoCloseable
- Direct Known Subclasses:
RrdFileBackendFactory
,RrdMemoryBackendFactory
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 theRrdRandomAccessFileBackendFactory
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 theRrdSafeFileBackendFactory
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 theRrdNioBackendFactory
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 theRrdMemoryBackendFactory
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
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic void
addActiveFactories
(RrdBackendFactory... newFactories) Add factories to the list of active factories, i.e.static void
addFactories
(RrdBackendFactory... newFactories) Deprecated.static URI
buildGenericUri
(String rrdpath) Try to detect an URI from a path.boolean
void
Check that all phantom reference are indeed safely closed.void
close()
A generic close handle, default implementation does nothing.protected abstract boolean
Determines if a storage with the given path already exists.protected boolean
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>
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.getCanonicalUri
(URI uri) Ensure that an URI is returned in a non-ambiguous way.static RrdBackendFactory
Returns the default backend factory.static RrdBackendFactory
getFactory
(String name) Deprecated.Uses active factory insteadgetName()
Returns the name (primary ID) for the factory.Extract the local path from an URI.protected URI
Transform an path in a valid URI for this backend.protected abstract RrdBackend
static void
Deprecated.UsessetActiveFactories(RrdBackendFactory...)
instead.static void
registerFactory
(RrdBackendFactory factory) Deprecated.Uses active factory insteadprotected URI
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.static void
setDefaultFactory
(String factoryName) Deprecated.Uses active factory insteadprotected boolean
shouldValidateHeader
(String path) Determines if the header should be validated.protected boolean
shouldValidateHeader
(URI uri) Determines if the header should be validated.
-
Field Details
-
DEFAULTFACTORY
The default factory type. It will also put in the active factories list.- See Also:
-
name
-
cachingAllowed
protected final boolean cachingAllowed -
scheme
-
validateHeader
protected final boolean validateHeader
-
-
Constructor Details
-
RrdBackendFactory
protected RrdBackendFactory()
-
-
Method Details
-
getFactory
Deprecated.Uses active factory insteadReturns backend factory for the given backend factory name.- Parameters:
name
- Backend factory name. Initially supported names are:- FILE: Default factory which creates backends based on the java.io.* package. RRD data is stored in files on the disk
- SAFE: Default factory which creates backends based on the java.io.* package. RRD data is stored in files on the disk. This backend is "safe". Being safe means that RRD files can be safely shared between several JVM's.
- NIO: Factory which creates backends based on the java.nio.* package. RRD data is stored in files on the disk
- MEMORY: Factory which creates memory-oriented backends. RRD data is stored in memory, it gets lost as soon as JVM exits.
- BERKELEY: a memory-oriented backend that ensure persistent in a Berkeley Db storage.
- MONGODB: a memory-oriented backend that ensure persistent in a MongoDB storage.
- Returns:
- Backend factory for the given factory name
-
registerFactory
Deprecated.Uses active factory insteadRegisters new (custom) backend factory within the Rrd4j framework.- Parameters:
factory
- Factory to be registered
-
registerAndSetAsDefaultFactory
Deprecated.UsessetActiveFactories(RrdBackendFactory...)
instead.Registers new (custom) backend factory within the Rrd4j framework and sets this factory as the default.- Parameters:
factory
- Factory to be registered and set as default
-
getDefaultFactory
Returns the default backend factory. This factory is used to constructRrdDb
objects if no factory is specified in the RrdDb constructor.- Returns:
- Default backend factory.
-
setDefaultFactory
Deprecated.Uses active factory insteadReplaces the default backend factory with a new one. This method must be called before the first RRD gets created.It also clear the list of actives factories and set it to the default factory.
- Parameters:
factoryName
- Name of the default factory..
-
setActiveFactories
Set the list of active factories, i.e. the factory used to resolve URI.- Parameters:
newFactories
- the new active factories.
-
getActiveFactories
Return the current active factories as a stream.- Returns:
- Since:
- 3.7
-
addFactories
Deprecated.UsesaddActiveFactories(RrdBackendFactory...)
instead.Add factories to the list of active factories, i.e. the factory used to resolve URI.- Parameters:
newFactories
- active factories to add.
-
addActiveFactories
Add factories to the list of active factories, i.e. the factory used to resolve URI.- Parameters:
newFactories
- active factories to add.
-
findFactory
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
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
-
checkClosing
public void checkClosing()Check that all phantom reference are indeed safely closed. -
getScheme
- Returns:
- the scheme name for URI, default to getName().toLowerCase()
-
getRootUri
-
canStore
-
resolve
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 againsturi
- an URI that the current backend can handle.relative
- if true, return an URI relative to therootUri
- Returns:
- a calculate normalized absolute URI or null if the tried URL don't match against the root.
-
getCanonicalUri
Ensure that an URI is returned in a non-ambiguous way.- Parameters:
uri
- a valid URI for this backend.- Returns:
- the canonized URI.
-
getUri
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
Extract the local path from an URI.- Parameters:
uri
- The URI to parse.- Returns:
- the local path from the URI.
-
open
- Throws:
IOException
-
getBackend
Creates RrdBackend object for the given storage path.- Parameters:
path
- Storage pathreadOnly
- 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
Creates RrdBackend object for the given storage path.- Parameters:
rrdDb
-uri
- Storage urireadOnly
- 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
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
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.
-
shouldValidateHeader
Determines if the header should be validated.- Parameters:
path
- Storage path- Returns:
- a boolean.
- Throws:
IOException
- if header validation fails
-
shouldValidateHeader
Determines if the header should be validated.- Parameters:
uri
- Storage URI- Returns:
- a boolean.
- Throws:
IOException
- if header validation fails
-
getName
Returns the name (primary ID) for the factory.- Returns:
- Name of the factory.
-
close
A generic close handle, default implementation does nothing.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
- if the close fails- Since:
- 3.4
-
addActiveFactories(RrdBackendFactory...)
instead.