|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.jrobin.core.RrdDbPool
public class RrdDbPool
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 |
---|
public static final int INITIAL_CAPACITY
Method Detail |
---|
public static RrdDbPool getInstance()
public RrdDb requestRrdDb(java.lang.String path) throws java.io.IOException, RrdException
path
- Relative or absolute path to a RRD file.
java.io.IOException
- Thrown in case of I/O error.
RrdException
- Thrown in case of JRobin specific error.public RrdDb requestRrdDb(java.lang.String path, java.lang.String xmlPath) throws java.io.IOException, RrdException
path
- Relative or absolute path to a new RRD file.xmlPath
- Relative or absolute path to an existing XML dump file (RRDTool comaptible)
java.io.IOException
- Thrown in case of I/O error.
RrdException
- Thrown in case of JRobin specific error.public RrdDb requestRrdDb(RrdDef rrdDef) throws java.io.IOException, RrdException
rrdDef
- RRD definition object
java.io.IOException
- Thrown in case of I/O error.
RrdException
- Thrown in case of JRobin specific error.public void release(RrdDb rrdDb) throws java.io.IOException, RrdException
rrdDb
- Reference to RRD file that is no longer needed.
java.io.IOException
- Thrown in case of I/O error.
RrdException
- Thrown in case of JRobin specific error.public void run()
getCapacity()
), garbage collector will try
to close and remove RRD files with a reference count equal to zero.
Never call this method directly.
run
in interface java.lang.Runnable
protected void finalize() throws java.io.IOException
finalize
in class java.lang.Object
java.io.IOException
public void reset() throws java.io.IOException
java.io.IOException
- Thrown in case of I/O related error.public java.lang.String dump() throws java.io.IOException
java.io.IOException
- Thrown in case of I/O error.public int getCapacity()
public void setCapacity(int capacity)
capacity
- Desired number of open files to hold in the poolpublic double getPoolEfficency()
public int getPoolHitsCount()
public int getPoolRequestsCount()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |