org.locomotive.util
Class ObjectPool

java.lang.Object
  |
  +--org.locomotive.util.ObjectPool
Direct Known Subclasses:
DBConnectionPool, ServletPool

public abstract class ObjectPool
extends java.lang.Object
implements LocomotiveService

Manages a pool of objects. Will broker the objects out until there are no more to give out, whereupon it will either attempt to create a new object and send that out, or block if the maximum number of objects are already open until an object is available.

To subclass this, you'll probably want to override the return and wipe methods to do an instanceof check for your particular object type, and you may want to check the object's state in returnToPool.


Inner Class Summary
 class ObjectPool.PoolEntry
          The internal class to use as our Object entry.
 
Field Summary
protected  java.lang.String classname
          This gets prepended to each logging message.
protected  int current_open
           
protected  boolean isRunning
           
protected  Log log
           
protected  int log_level
           
protected  int max_open
           
protected  int min_open
           
protected  java.util.Hashtable pe_in_use_hash
          This holds objects in use.
protected  java.util.Stack pe_stack
          the stack to use to hold the objects
protected  int poolentry_id_sequence
           
 
Constructor Summary
ObjectPool()
          Default constructor for the object pool
ObjectPool(int min_open_in, int max_open_in)
          creates a new pool, and fills it with the specified minumum number of objects
ObjectPool(int min_open_in, int max_open_in, Log l, int log_lvl_in)
          creates a new pool, and fills it with the specified minumum number of objects
 
Method Summary
 void closeCurrentPoolMembers()
          Closes all objects in the pool at the time of the call.
protected abstract  java.lang.Object createNewObject()
          This is called internally whenever a new object is created and added to the pool.
protected abstract  void destroyObject(java.lang.Object obj)
          This should be overridden in sub classes to clean up any of an object's resources before the object get's removed from the pool.
 int getLogLevel()
          Get the log level for this object pool.
 int getMaxSize()
          Get the maximum size of the object pool.
 int getMinSize()
          Get the minimum size of the object pool.
protected  int getNextId()
          Each PoolEntry has a numeric ID, this method increments it and gives it out.
 java.lang.Object getObject()
          gets an object from the pool.
 int getPoolSize()
          returns the current number of open db objects in the pool
 void initialize()
          This needs to be called after the pool is created
 boolean isRunning()
          Check if the object pool is started.
protected  void log(java.lang.String message)
          Log a statement.
protected  void logError(java.lang.String message, java.lang.Throwable t)
          Log an error.
 void returnToPool(java.lang.Object obj)
          returns this object to the pool, allowing other threads to have access to it.
 void setLog(Log log)
          Set the log for this object pool.
 void setLogLevel(int logLevel)
          Set the log level for this object pool.
 void setMaxSize(int maxSize)
          Set the maximum size of the object pool.
 void setMinSize(int minSize)
          Set the minimum size of the object pool.
 void startService()
          Start the object pool service.
 void stopService()
          Stop the object pool service.
 void wipeFromPool(java.lang.Object obj)
          removes the specified object from the pool.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

pe_stack

protected java.util.Stack pe_stack
the stack to use to hold the objects

pe_in_use_hash

protected java.util.Hashtable pe_in_use_hash
This holds objects in use. Key: object; value: pooled entry

min_open

protected int min_open

max_open

protected int max_open

current_open

protected int current_open

poolentry_id_sequence

protected int poolentry_id_sequence

log

protected Log log

log_level

protected int log_level

isRunning

protected boolean isRunning

classname

protected java.lang.String classname
This gets prepended to each logging message. It will automatically get set to the class name minus any packages in the constructor. subclasses can set it anything they like after calling super().
Constructor Detail

ObjectPool

public ObjectPool(int min_open_in,
                  int max_open_in)
           throws InitializationException
creates a new pool, and fills it with the specified minumum number of objects
Parameters:
min_open_in - the minumum number of objects to remain in the pool
max_open_in - the maximum number of objects to maintain at any given time

ObjectPool

public ObjectPool(int min_open_in,
                  int max_open_in,
                  Log l,
                  int log_lvl_in)
           throws InitializationException
creates a new pool, and fills it with the specified minumum number of objects
Parameters:
min_open_in - the minumum number of objects to remain in the pool
max_open_in - the maximum number of objects to maintain at any given time
l - the log to use to log any major events. Leave as null for no logging
log_lvl_in - the log level to use when logging

ObjectPool

public ObjectPool()
Default constructor for the object pool
Method Detail

initialize

public void initialize()
                throws InitializationException
This needs to be called after the pool is created

startService

public void startService()
                  throws ServiceException
Start the object pool service. Subclasses should make sure to call this method if they override, so the object pool is initialized correctly.
Specified by:
startService in interface LocomotiveService
Throws:
ServiceException - is thrown if an error occured to startup.

stopService

public void stopService()
                 throws ServiceException
Stop the object pool service.
Specified by:
stopService in interface LocomotiveService
Throws:
ServiceException - if the object pool not could be stopped.

isRunning

public boolean isRunning()
Check if the object pool is started.
Specified by:
isRunning in interface LocomotiveService
Returns:
Return true if the object pool is started, false otherwise.

createNewObject

protected abstract java.lang.Object createNewObject()
                                             throws InitializationException
This is called internally whenever a new object is created and added to the pool. Override this for each subclass.

destroyObject

protected abstract void destroyObject(java.lang.Object obj)
This should be overridden in sub classes to clean up any of an object's resources before the object get's removed from the pool.

getObject

public java.lang.Object getObject()
gets an object from the pool. If the pool is currently empty (meaning all objects are in use by other threads) and the current total is less than the configured maximum, a new object is created and returned. Otherwise this method blocks until an object is released by another thread.

getPoolSize

public int getPoolSize()
returns the current number of open db objects in the pool

returnToPool

public void returnToPool(java.lang.Object obj)
returns this object to the pool, allowing other threads to have access to it. This should be called when the calling thread no longer needs the object. Subclasses may want to override to check the type of the Object being returned.

wipeFromPool

public void wipeFromPool(java.lang.Object obj)
removes the specified object from the pool. Usually used if an object has been put into some bad state, like a closed connection, for instance.

closeCurrentPoolMembers

public void closeCurrentPoolMembers()
Closes all objects in the pool at the time of the call. If other objects are returned to the pool after this call, they will not be closed, and this call would need to be made again.

getNextId

protected int getNextId()
Each PoolEntry has a numeric ID, this method increments it and gives it out.

log

protected void log(java.lang.String message)
Log a statement. Will provide the class name for the object pool at the the beginning of the statement. Will use the log level and log specified in the constructor; if they're null, then it won't log

logError

protected void logError(java.lang.String message,
                        java.lang.Throwable t)
Log an error. Will provide the class name for the object pool at the the beginning of the statement. Will use the log level and log specified in the constructor; if they're null, then it won't log

setMinSize

public void setMinSize(int minSize)
Set the minimum size of the object pool.
Parameters:
minSize - The minimum size of the object pool.

getMinSize

public int getMinSize()
Get the minimum size of the object pool.
Returns:
The minimum size of the object pool.

setMaxSize

public void setMaxSize(int maxSize)
Set the maximum size of the object pool.
Parameters:
maxSize - The maximum size of the object pool.

getMaxSize

public int getMaxSize()
Get the maximum size of the object pool.
Returns:
The maximum size of the object pool.

setLog

public void setLog(Log log)
Set the log for this object pool.
Parameters:
log - The log object for this connetion pool.

setLogLevel

public void setLogLevel(int logLevel)
Set the log level for this object pool.
Parameters:
logLevel - The log level for this object pool.

getLogLevel

public int getLogLevel()
Get the log level for this object pool.
Returns:
The log level for this object pool.