org.jrobin.core
Class RrdDbPool

java.lang.Object
  extended by 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
Overrides:
finalize in class java.lang.Object
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