## org.jrobin.core
Class RrdDbPool

    java.lang.Object
      org.jrobin.core.RrdDbPool

All Implemented Interfaces:
  java.lang.Runnable

public class RrdDbPool
extends java.lang.Object
implements java.lang.Runnable

Class to represent the pool of open RRD files.

To open already existing RRD file with JRobin, you have to create a `RrdDb` object by specifying RRD file path as constructor argument. This operation can be time consuming especially with large RRD files with many datasources and several long archives.

In a multithreaded environment you might probably need a reference to the same RRD file from two different threads (RRD file updates are performed in one thread but data fetching and graphing is performed in another one). To make the RrdDb construction process more efficient it might be convenient to open all RRD files in a centralized place. That's the purpose of RrdDbPool class.

How does it work? The typical usage scenario goes like this:

     // obtain instance to RrdDbPool object
     RrdDbPool pool = RrdDbPool.getInstance();

     // request a reference to RrdDb object
     String path = "some_relative_or_absolute_path_to_any_RRD_file";
     RrdDb rrdDb = RrdDbPool.requestRrdDb(path);

     // reference obtained, do whatever you want with it...
     ...
     ...

     // once you don't need the reference, release it.
     // DO NOT CALL rrdDb.close() - files no longer in use are eventually closed by the pool
     pool.release(rrdDb);

It's that simple. When the reference is requested for the first time, RrdDbPool will open the RRD file for you and make some internal note that the RRD file is used only once. When the reference to the same file (same RRD file path) is requested for the second time, the same RrdDb reference will be returned, and its usage count will be increased by one. When the reference is released its usage count will be decremented by one.

When the reference count drops to zero, RrdDbPool will not close the underlying RRD file immediatelly. Instead of it, it will be marked as 'eligible for closing'. If someone request the same RRD file again (before it gets closed), the same reference will be returned again.

RrdDbPool has a 'garbage collector' which runs in a separate thread and gets activated only when the number of RRD files kept in the pool is too big (greater than number returned from `getCapacity()`). Only RRD files with a reference count equal to zero will be eligible for closing. Unreleased RrdDb references are never invalidated. RrdDbPool object keeps track of the time when each RRD file becomes eligible for closing so that the oldest RRD file gets closed first.

Initial RrdDbPool capacity is set to `INITIAL_CAPACITY`. Use `setCapacity(int)` method to change it at any time.

WARNING:Never use close() method on the reference returned from the pool. When the reference is no longer needed, return it to the pool with the `release()` method.

However, you are not forced to use RrdDbPool methods to obtain RrdDb references to RRD files, 'ordinary' RrdDb constructors are still available. But RrdDbPool class offers serious performance improvement especially in complex applications with many threads and many simultaneously open RRD files.

The pool is thread-safe.

WARNING: The pool cannot be used to manipulate RrdDb objects with `backends` different from default.

Field Summary
`static int` `INITIAL_CAPACITY` Constant to represent the maximum number of internally open RRD files which still does not force garbage collector (the process which closes RRD files) to run.

Method Summary
`java.lang.String` `dump()` Returns the internal state of the pool.
`protected void` `finalize()`
`int` `getCapacity()` Returns maximum number of internally open RRD files which still does not force garbage collector to run.
`static RrdDbPool` `getInstance()` Returns an instance to RrdDbPool object.
`double` `getPoolEfficency()` Calculates pool's efficency ratio.
`int` `getPoolHitsCount()` Returns the number of RRD requests served from the internal pool of open RRD files
`int` `getPoolRequestsCount()` Returns the total number of RRD requests successfully served by this pool.
`void` `release(RrdDb rrdDb)` Method used to report that the reference to a RRD file is no longer needed.
`RrdDb` `requestRrdDb(RrdDef rrdDef)` Returns a reference to a new RRD file.
`RrdDb` `requestRrdDb(java.lang.String path)` Returns a reference to an existing RRD file with the specified path.
`RrdDb` `requestRrdDb(java.lang.String path, java.lang.String xmlPath)` Returns a reference to a new RRD file.
`void` `reset()` Clears the internal state of the pool entirely.
`void` `run()` This method runs garbage collector in a separate thread.
`void` `setCapacity(int capacity)` Sets maximum number of internally open RRD files which still does not force garbage collector to run.

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### INITIAL_CAPACITY

    public static final int INITIAL_CAPACITY

  Constant to represent the maximum number of internally open RRD files which still does not force garbage collector (the process which closes RRD files) to run.

  See Also:
    Constant Field Values

Method Detail

### getInstance

    public static RrdDbPool getInstance()

  Returns an instance to RrdDbPool object. Only one such object may exist in each JVM.

  Returns:
    Instance to RrdDbPool object.

### requestRrdDb

    public RrdDb requestRrdDb(java.lang.String path)
                       throws java.io.IOException,
                              RrdException

  Returns a reference to an existing RRD file with the specified path. If the file is already open in the pool, existing reference to it will be returned. Otherwise, the file is open and a newly created reference to it is returned.

  Parameters:
    `path` - Relative or absolute path to a RRD file.
  Returns:
    Reference to a RrdDb object (RRD file).
  Throws:
    `java.io.IOException` - Thrown in case of I/O error.
    `RrdException` - Thrown in case of JRobin specific error.

### requestRrdDb

    public RrdDb requestRrdDb(java.lang.String path,
                              java.lang.String xmlPath)
                       throws java.io.IOException,
                              RrdException

  Returns a reference to a new RRD file. The new file will have the specified relative or absolute path, and its contents will be provided from the specified XML file (RRDTool comaptible).

  Parameters:
    `path` - Relative or absolute path to a new RRD file.
    `xmlPath` - Relative or absolute path to an existing XML dump file (RRDTool comaptible)
  Returns:
    Reference to a RrdDb object (RRD file).
  Throws:
    `java.io.IOException` - Thrown in case of I/O error.
    `RrdException` - Thrown in case of JRobin specific error.

### requestRrdDb

    public RrdDb requestRrdDb(RrdDef rrdDef)
                       throws java.io.IOException,
                              RrdException

  Returns a reference to a new RRD file. The new file will be created based on the definition contained in a RrdDef object.

  Parameters:
    `rrdDef` - RRD definition object
  Returns:
    Reference to a RrdDb object (RRD file).
  Throws:
    `java.io.IOException` - Thrown in case of I/O error.
    `RrdException` - Thrown in case of JRobin specific error.

### release

    public void release(RrdDb rrdDb)
                 throws java.io.IOException,
                        RrdException

  Method used to report that the reference to a RRD file is no longer needed. File that is no longer needed (all references to it are released) is marked 'eligible for closing'. It will be eventually closed by the pool when the number of open RRD files becomes too big. Most recently released files will be closed last.

  Parameters:
    `rrdDb` - Reference to RRD file that is no longer needed.
  Throws:
    `java.io.IOException` - Thrown in case of I/O error.
    `RrdException` - Thrown in case of JRobin specific error.

### run

    public void run()

  This method runs garbage collector in a separate thread. If the number of open RRD files kept in the pool is too big (greater than number returned from `getCapacity()`), garbage collector will try to close and remove RRD files with a reference count equal to zero. Never call this method directly.

  Specified by:
    `run` in interface `java.lang.Runnable`

### finalize

    protected void finalize()
                     throws java.io.IOException

  Throws:
    `java.io.IOException`

### reset

    public void reset()
               throws java.io.IOException

  Clears the internal state of the pool entirely. All open RRD files are closed.

  Throws:
    `java.io.IOException` - Thrown in case of I/O related error.

### dump

    public java.lang.String dump()
                          throws java.io.IOException

  Returns the internal state of the pool. Useful for debugging purposes.

  Returns:
    Internal pool state (list of open RRD files, with the number of usages for each one).
  Throws:
    `java.io.IOException` - Thrown in case of I/O error.

### getCapacity

    public int getCapacity()

  Returns maximum number of internally open RRD files which still does not force garbage collector to run.

  Returns:
    Desired nuber of open files held in the pool.

### setCapacity

    public void setCapacity(int capacity)

  Sets maximum number of internally open RRD files which still does not force garbage collector to run.

  Parameters:
    `capacity` - Desired number of open files to hold in the pool

### getPoolEfficency

    public double getPoolEfficency()

  Calculates pool's efficency ratio. The ratio is obtained by dividing the number of RrdDb requests served from the internal pool of open RRD files with the number of total RrdDb requests.

  Returns:
    Pool's efficiency ratio as a double between 1 (best) and 0 (worst). If no RrdDb reference was ever requested, 1 would be returned.

### getPoolHitsCount

    public int getPoolHitsCount()

  Returns the number of RRD requests served from the internal pool of open RRD files

  Returns:
    The number of pool "hits".

### getPoolRequestsCount

    public int getPoolRequestsCount()

  Returns the total number of RRD requests successfully served by this pool.

  Returns:
    Total number of RRD requests