Package org.rrd4j.core

Class RrdDbPool

java.lang.Object

org.rrd4j.core.RrdDbPool

public class RrdDbPool
extends Object

This class should be used to synchronize access to RRD files in a multithreaded environment. This class should be also used to prevent opening of too many RRD files at the same time (thus avoiding operating system limits).

It can also be used a factory for RrdDb, using a default backend factory.

In case of interruptions, it throws IllegalStateException.

Field Summary

Fields

Modifier and Type	Field	Description
static int	INITIAL_CAPACITY	Initial capacity of the pool i.e.

Constructor Summary

Constructors

Constructor	Description
RrdDbPool()	Constructor for RrdDbPool.
RrdDbPool(RrdBackendFactory defaultFactory)	Constructor for RrdDbPool.

Method Summary

Modifier and Type	Method	Description
int	getCapacity()	Returns the maximum number of simultaneously open RRD.
static RrdDbPool	getInstance()	Creates a single instance of the class on the first call, or returns already existing one.
int	getOpenCount(String path)	Returns the number of usage for a RRD.
int	getOpenCount(URI uri)	Returns the number of usage for a RRD.
int	getOpenCount(RrdDb rrdDb)	Returns the number of usage for a RRD.
int	getOpenFileCount()	Returns the number of open RRD.
String[]	getOpenFiles()	Returns an array of open RRD.
URI[]	getOpenUri()	Returns an array of open RRD URI.
java.util.stream.Stream<URI>	getOpenUriStream()	Returns an stream open RRD.
Lock	lockEmpty(long timeout, TimeUnit unit)	Wait until the pool is empty and return a lock that prevent any additions of new RrdDb references until it's released.
void	release(RrdDb rrdDb)	Deprecated. A RrdDb remember if it was open directly or from a pool, no need to manage it manually any more
RrdDb	requestRrdDb(String path)	Requests a RrdDb reference for the given RRD path.
RrdDb	requestRrdDb(String path, String sourcePath)	Requests a RrdDb reference for the given path.
RrdDb	requestRrdDb(URI uri)	Requests a RrdDb reference for the given RRD URI.
RrdDb	requestRrdDb(URI uri, String sourcePath)	Requests a RrdDb reference for the given URI.
(package private) RrdDb	requestRrdDb(URI uri, RrdBackendFactory factory)
(package private) RrdDb	requestRrdDb(URI uri, RrdBackendFactory factory, DataImporter importer)
RrdDb	requestRrdDb(RrdDef rrdDef)	Requests a RrdDb reference for the given RRD definition object.
(package private) RrdDb	requestRrdDb(RrdDef rrdDef, RrdBackendFactory factory)
void	setCapacity(int newCapacity)	Sets the maximum number of simultaneously open RRD.
void	setDefaultFactory(RrdBackendFactory defaultFactory)	Deprecated. the pool is no longer a singleton, create a new pool instead of changing it.

Methods inherited from class java.lang.Object

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

Field Detail

INITIAL_CAPACITY

public static final int INITIAL_CAPACITY

Initial capacity of the pool i.e. maximum number of simultaneously open RRD. The pool will never open too many RRD at the same time.

See Also:

Constant Field Values

Constructor Detail

RrdDbPool

public RrdDbPool()

Constructor for RrdDbPool. It will use the default backend factory.

Since:

3.5

RrdDbPool

public RrdDbPool(RrdBackendFactory defaultFactory)

Constructor for RrdDbPool.

Parameters:

defaultFactory - the default factory used when given a simple path of a RRD.

Since:

3.6

Method Detail

getInstance

public static RrdDbPool getInstance()

Creates a single instance of the class on the first call, or returns already existing one. Uses Initialization On Demand Holder idiom.

Returns:

Single instance of this class

getOpenFileCount

public int getOpenFileCount()

Returns the number of open RRD.

Returns:

Number of currently open RRD held in the pool.

getOpenUri

public URI[] getOpenUri()

Returns an array of open RRD URI.

Returns:

Array with URI to open RRD held in the pool.

getOpenUriStream

public java.util.stream.Stream<URI> getOpenUriStream()

Returns an stream open RRD.

Returns:

Stream with canonical URI to open RRD path held in the pool.

Since:

3.7

getOpenFiles

public String[] getOpenFiles()

Returns an array of open RRD.

Returns:

Array with canonical path to open RRD path held in the pool.

release

@Deprecated
public void release(RrdDb rrdDb)
             throws IOException

Deprecated.

A RrdDb remember if it was open directly or from a pool, no need to manage it manually any more

Releases RrdDb reference previously obtained from the pool. When a reference is released, its usage count is decremented by one. If usage count drops to zero, the underlying RRD will be closed.

Parameters:

rrdDb - RrdDb reference to be returned to the pool

Throws:

IOException - Thrown in case of I/O error

IllegalStateException - if the thread was interrupted

requestRrdDb

public RrdDb requestRrdDb(String path)
                   throws IOException

Requests a RrdDb reference for the given RRD path.

• If the RRD is already open, previously returned RrdDb reference will be returned. Its usage count will be incremented by one.
• If the RRD is not already open and the number of already open RRD is less than getCapacity(), it will be opened and a new RrdDb reference will be returned. If the RRD is not already open and the number of already open RRD is equal to getCapacity(), the method blocks until some RRD are closed.

The path is transformed to an URI using the default factory defined at the creation of the pool.

Parameters:

path - Path to existing RRD.

Returns:

reference for the given RRD.

Throws:

IOException - Thrown in case of I/O error

requestRrdDb

public RrdDb requestRrdDb(URI uri)
                   throws IOException

Requests a RrdDb reference for the given RRD URI.

• If the RRD is already open, previously returned RrdDb reference will be returned. Its usage count will be incremented by one.
• If the RRD is not already open and the number of already open RRD is less than getCapacity(), it will be opened and a new RrdDb reference will be returned. If the RRD is not already open and the number of already open RRD is equal to getCapacity(), the method blocks until some RRD are closed.

If the default backend factory for the pool can handle this URI, it will be used, or else RrdBackendFactory.findFactory(URI) will be used to find the backend factory used.

Parameters:

uri - URI to existing RRD file

Returns:

reference for the give RRD file

Throws:

IOException - Thrown in case of I/O error

requestRrdDb

RrdDb requestRrdDb(URI uri,
                   RrdBackendFactory factory)
            throws IOException

Throws:

IOException

requestRrdDb

RrdDb requestRrdDb(RrdDef rrdDef,
                   RrdBackendFactory factory)
            throws IOException

Throws:

IOException

requestRrdDb

RrdDb requestRrdDb(URI uri,
                   RrdBackendFactory factory,
                   DataImporter importer)
            throws IOException

Throws:

IOException

requestRrdDb

public RrdDb requestRrdDb(RrdDef rrdDef)
                   throws IOException

Requests a RrdDb reference for the given RRD definition object.

• If the RRD with the path specified in the RrdDef object is already open, the method blocks until the file is closed.
• If the RRD is not already open and the number of already open RRD is less than getCapacity(), a new RRD will be created and it's RrdDb reference will be returned. If the RRD is not already open and the number of already open RRD is equal to getCapacity(), the method blocks until some RrdDb references are closed.

If the factory defined when creating the pool can handle the URI, it will be used, or else RrdBackendFactory.findFactory(URI) will be used.

Parameters:

rrdDef - Definition of the RRD file to be created.

Returns:

Reference to the newly created RRD file.

Throws:

IOException - Thrown in case of I/O error

IllegalStateException - if the thread was interrupted

requestRrdDb

public RrdDb requestRrdDb(String path,
                          String sourcePath)
                   throws IOException

Requests a RrdDb reference for the given path. The RRD will be created from external data (from XML dump or RRDTool's binary RRD file).

• If the RRD with the path specified is already open, the method blocks until the file is closed.
• If the RRD is not already open and the number of already open RRD is less than getCapacity(), a new RRD will be created and it's RrdDb reference will be returned. If the RRD is not already open and the number of already open RRD is equal to getCapacity(), the method blocks until some RrdDb references are closed.

The path is transformed to an URI using the default factory of the pool.

Parameters:

path - Path to the RRD that should be created.

sourcePath - Path to external data which is to be converted to Rrd4j's native RRD file format.

Returns:

Reference to the newly created RRD.

Throws:

IOException - Thrown in case of I/O error

IllegalStateException - if the thread was interrupted

requestRrdDb

public RrdDb requestRrdDb(URI uri,
                          String sourcePath)
                   throws IOException

Requests a RrdDb reference for the given URI. The RRD will be created from external data (from XML dump or RRDTool's binary RRD file).

• If the RRD with the URI specified is already open, the method blocks until the file is closed.
• If the RRD is not already open and the number of already open RRD is less than getCapacity(), a new RRD will be created and it's RrdDb reference will be returned. If the RRD is not already open and the number of already open RRD is equal to getCapacity(), the method blocks until some RrdDb references are closed.

If the factory defined when creating the pool can handle the URI, it will be used, or else RrdBackendFactory.findFactory(URI) will be used to choose the factory.

Parameters:

uri - URI to the RRD that should be created

sourcePath - Path to external data which is to be converted to Rrd4j's native RRD file format

Returns:

Reference to the newly created RRD

Throws:

IOException - Thrown in case of I/O error

IllegalStateException - if the thread was interrupted

setDefaultFactory

@Deprecated
public void setDefaultFactory(RrdBackendFactory defaultFactory)

Deprecated.

the pool is no longer a singleton, create a new pool instead of changing it.

Sets the default factory to use when obtaining RrdDb reference from simple path and not URI.

Parameters:

defaultFactory - The factory to use.

Throws:

IllegalStateException - if called while the pool is not empty or the thread was interrupted

IllegalStateException - if the thread was interrupted

setCapacity

public void setCapacity(int newCapacity)

Sets the maximum number of simultaneously open RRD.

Parameters:

newCapacity - Maximum number of simultaneously open RRD.

Throws:

IllegalStateException - if called while the pool is not empty or the thread was interrupted.

getCapacity

public int getCapacity()

Returns the maximum number of simultaneously open RRD.

Returns:

maximum number of simultaneously open RRD

Throws:

IllegalStateException - if the thread was interrupted

getOpenCount

public int getOpenCount(RrdDb rrdDb)
                 throws IOException

Returns the number of usage for a RRD.

Parameters:

rrdDb - RrdDb reference for which informations is needed.

Returns:

the number of request for this RRD.

Throws:

IOException - if any

IllegalStateException - if the thread was interrupted

getOpenCount

public int getOpenCount(String path)
                 throws IOException

Returns the number of usage for a RRD.

The path is transformed to an URI using the default factory.

Parameters:

path - RRD's path for which informations is needed.

Returns:

the number of request for this RRD.

Throws:

IOException - if any

IllegalStateException - if the thread was interrupted

getOpenCount

public int getOpenCount(URI uri)
                 throws IOException

Returns the number of usage for a RRD.

Parameters:

uri - RRD's URI for which informations is needed.

Returns:

the number of request for this RRD.

Throws:

IOException - if any

IllegalStateException - if the thread was interrupted

lockEmpty

public Lock lockEmpty(long timeout,
                      TimeUnit unit)
               throws InterruptedException

Wait until the pool is empty and return a lock that prevent any additions of new RrdDb references until it's released.

Parameters:

timeout - the time to wait for the write lock

unit - the time unit of the timeout argument

Returns:

a lock to release when operations on this pool are finished.

Throws:

InterruptedException - if interrupted whole waiting for the lock

Since:

3.7