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 and Description
    --- | ---
    `static int` | `INITIAL_CAPACITY` Initial capacity of the pool i.e.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RrdDbPool()` Constructor for RrdDbPool.
    `RrdDbPool(RrdBackendFactory defaultFactory)` Constructor for RrdDbPool.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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(RrdDb rrdDb)` Returns the number of usage for a RRD.
    `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` | `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.
    `RrdDb` | `requestRrdDb(RrdDef rrdDef)` Requests a RrdDb reference for the given RRD definition object.
    `(package private) RrdDb` | `requestRrdDb(RrdDef rrdDef, RrdBackendFactory factory)`
    `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.
    `(package private) RrdDb` | `requestRrdDb(URI uri, RrdBackendFactory factory)`
    `(package private) RrdDb` | `requestRrdDb(URI uri, RrdBackendFactory factory, DataImporter importer)`
    `RrdDb` | `requestRrdDb(URI uri, String sourcePath)` Requests a RrdDb reference for the given URI.
    `void` | `setCapacity(int newCapacity)` Sets the maximum number of simultaneously open RRD.

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

    - #### RrdDbPool

          public RrdDbPool(RrdBackendFactory defaultFactory)

      Constructor for RrdDbPool.
      Parameters:
        `defaultFactory` - the default factory used when given a simple path of a RRD.

  - ### Method Detail

    - #### 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

    - #### 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

    - #### getOpenCount

          public int getOpenCount(RrdDb rrdDb)

      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:
        `IllegalStateException` - if the thread was interrupted

    - #### getOpenCount

          public int getOpenCount(String path)

      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:
        `IllegalStateException` - if the thread was interrupted

    - #### getOpenCount

          public int getOpenCount(URI uri)

      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:
        `IllegalStateException` - if the thread was interrupted

    - #### getOpenFileCount

          public int getOpenFileCount()

      Returns the number of open RRD.
      Returns:
        Number of currently open RRD held in the pool.

    - #### getOpenFiles

          public String[] getOpenFiles()

      Returns an array of open RRD.
      Returns:
        Array with canonical path to open RRD path 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.

    - #### 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

    - #### 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

          RrdDb requestRrdDb(RrdDef rrdDef,
                             RrdBackendFactory factory)
                      throws IOException

      Throws:
        `IOException`

    - #### 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(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)
                             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(URI uri,
                             RrdBackendFactory factory,
                             DataImporter importer)
                      throws IOException

      Throws:
        `IOException`

    - #### 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

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