atg.service.resourcepool
Class ResourcePool

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.service.resourcepool.ResourcePool

All Implemented Interfaces:

atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, atg.service.resourcepool.ResourcePoolResourceKeys, java.util.EventListener

Direct Known Subclasses:

JDBCConnectionPool, JNDIInitialContextPool, MonitoredDataSource, SenderResourcePool

public class ResourcePool
extends GenericService
implements atg.service.resourcepool.ResourcePoolResourceKeys

ResourcePool manages a pool of objects which can be checked in and out for reuse. Resources are wrapped in a ResourceObject which contains various information about the resource.

In its simplest form, the pooled object's class name can be specified via the resourceClassName property and the pool will create and destroy the objects. The class is designed for extending so more advanced uses may be implemented. A typical sub-class would override the methods createResource(), destroyResource(), and verifyResourceValidity(). The methods checkOut() and checkIn() can also be overridden if special operations on pooled resources are required.

IMPORTANT NOTE: The ResourceObject wrappers generated by this pool change with each checkout. The underlying resources will stay the same if not flagged invalid, but the wrapping ResourceObjects will not stay the same across checkouts. Do not depend on the actual instance of the ResourceObject wrapping the pooled resource.

Pool Size

The size of the pool is controlled through the properties max, min, and maxFree.

The property max sets the largest number of resources that can exist in the pool. As needed, the pool will create and pool new resources up to the maximum. Upon reaching the maximum the pool will either block or throw an exception indicating that the maximum has been reached.

The property min sets the minimum number of resources the pool should start out with. Since resource creation can be expensive, some applications will want a starting minimum number of resources already in the pool before the pool becomes active. This minimum is only a starting minimum and will not be maintained throughout the life of the pool. As invalid resources are checked back into the pool, the number of pooled resources can drop below the starting minimum. After startup, resource creation is driven by resource demand.

The maxFree property causes the pool to destroy any resources being checked in that would exceed the specified limit. Incoming resources will only be destroyed if doing so would not cause the total number of resources being managed by the pool to drop below the minimum. In this, the pool can be configured with a soft and hard limit, sometimes useful when resources are expensive to keep around.

Pool Death

Some pooled resources can be troublesome to create. ResourcePool offers to its children ways to detect that the pool has died, i.e. creation of new resources has halted. When a pool death has been detected the pool is disabled. Once disabled, the pool allows only one checkOut() call to attempt resource creation. All other calls throw a ResourcePoolException. Thus once a pool has been identified as unhealthy, at any given time only one call to checkOut() will be potentially hung. The pool is re-enabled when a successful resource creation is made. To tune the pool death detections, see the properties:

• creationTimeLimit
• maxPendingCreations

Pool Deadlock

When code is written that allows a thread to nest checkouts of resources, i.e. checking out a second resource before a first resource is returned to the pool, the potential for deadlock is created. The properties maxThreadsWithResourcesOut and maxResourcesPerThread can be used to control resource usage and prevent pool deadlocks. The property warnOnNestedCheckouts can be useful for identifying potential deadlock scenerios.

See Also:

ResourceObject

Field Summary

static java.lang.String	CLASS_VERSION Class version string
boolean	mBlocking Whether or not the pool is to block on check outs.
long	mCheckoutBlockTime Maximum time in milli-seconds to block.
atg.core.util.IntStack	mCreatingResources List of slots currently being filled.
long	mCreationTimeLimit Resource creation time limit in milli-seconds for a healthy pool.
atg.core.util.IntQueue	mFreeResources The pool of free objects.
boolean	mHealthy Whether or not the pool is active.
int	mMax The maximum number of objects to pool.
int	mMaxFree The maximum number of free pooled objects at a time.
int	mMaxPendingCreations Concurrent creation attempts allowed for a healthy pool.
int	mMaxStartupAttempts Maximum startup attempts.
int	mMin The minimum number of objects to pool.
ResourceObject[]	mPool The pool of checked in objects.
java.lang.String	mResourceClassName The class name of the object being pooled.
long	mStartupSleepTime Time in millis to sleep between startup attempts.
atg.core.util.IntStack	mUnusedPoolSlots The list of unused spaces in the pool.

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.service.resourcepool.ResourcePoolResourceKeys

RESOURCE_BUNDLE, RSRC_blockTimeout, RSRC_ciCreateFailure, RSRC_ciForeignResource, RSRC_ciWrongResource, RSRC_coNonRunning, RSRC_creationLimit, RSRC_creationTimeout, RSRC_failedInitialPopulation, RSRC_hitPoolMax, RSRC_maxResourcePerThread, RSRC_maxThreads, RSRC_misconfiguration, RSRC_nestedCheckout, RSRC_nonOwningThread, RSRC_notImplemented, RSRC_poolDisabled, RSRC_startupFailure, RSRC_usingClosedConnection

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

ResourcePool()
Constructs an uninitialized ResourcePool.

Method Summary

protected void	addAdminInfo(javax.servlet.http.HttpServletRequest pRequest, javax.servlet.http.HttpServletResponse pResponse, javax.servlet.ServletOutputStream pOut) Adds to the HTML Admin response any information specific to the the ResourcePool subclass.
void	block(long pTimeout) Causes this thread to block.
void	checkIn(ResourceObject pResource) Checks a resource into the pool.
ResourceObject	checkOut(java.lang.String pCheckOutTag) Checks a resource out of the pool.
protected javax.servlet.Servlet	createAdminServlet() Creates and returns a new Servlet that will administer this service.
java.lang.Object	createResource() Creates an object for pooling.
void	destroyResource(java.lang.Object pResource) Destroys a resource object of this pool.
void	doStartService() This is called after the service has been created, added to the Registry, and configured.
void	doStopService() This is called when the service is to be stopped.
void	finalize() Destroys all resources in the pool regardless of whether or not they are checked out and uninitializes the pool.
long	getAverageResourceCreationTime() Returns the average time in milli-seconds required to successfully create a resource for the pool.
boolean	getBlocking() Returns whether or not this pool is to block on check outs that cannot be fulfilled.
long	getCheckoutBlockTime() The maximum time in milli-seconds to block waiting for a resource on checkout.
long	getCreationTimeLimit() This is the resource creation time limit in milli-seconds.
protected java.lang.String	getCurrentStack() Get the current stack trace for debugging
boolean	getDebugConnections()
java.lang.String	getLastError()
int	getMax() Returns the maximum number of objects to have pooled at any given time, free or checked out.
int	getMaxConcurrentResourcesPerThread() Returns property maxConcurrentResourcesPerThread.
int	getMaxConcurrentThreads() Returns property maxConcurrentThreads.
int	getMaxFree() The maximum number of free objects to have pooled at any given time.
long	getMaxIdleAge() Returns property maxIdleAge.
int	getMaxPendingCreations() This is the maximum number of pending resource creation attempts to allow when there are no valid resources being managed by the pool.
long	getMaxResourceAge() Sets property maxResourceAge.
int	getMaxResourcesPerThread() Returns property maxResourcesPerThread.
int	getMaxSimultaneousResourcesOut() Returns property maxSimultaneousResourcesOut.
int	getMaxThreadsWithResourcesOut() Sets property maxThreadsWithResourcesOut.
int	getMin() Returns the minimum number of objects to have pooled at start-up.
int	getNumCheckedOutResources() Returns the number of resources checked out.
int	getNumFreeResources() Returns the number of free resources in the pool.
int	getNumTotalResources() Returns the number of total resources in the pool.
java.lang.String	getResourceClassName() Returns the class name of the pooled resource.
int	getStartupAttempts() The number of startup attempts to make.
long	getStartupFailureSleepTime() The time in milli-seconds to sleep between startup attempts.
void	invalidateAllResources() Runs through the list of all resources (in or out of the pool) and flags them as invalid.
boolean	isEnabled() Whether or not this pool is still considered active.
boolean	isWarnOnNestedCheckouts() Returns property warnOnNestedCheckouts.
void	populateSlot(int pIndex) Populates the specified slot with a valid resource and appropriate meta-data.
void	pruneFreeResources() Runs through the list of free resources and destroys all of them.
protected void	reclaimResource(ResourceObject pRobj) A separate method for reclaiming resources incase sub-classes need to do this differently.
void	resetMaxConcurrentResourcesPerThread() Resets the maxConcurrentResourcesPerThread property to zero.
void	resetMaxConcurrentThreads() Resets the maxConcurrentThreads property to zero.
void	resetMaxSimultaneousResourcesOut() Resets the maxSimultaneousResourcesOut property to zero.
void	setBlocking(boolean pBlocking) Sets whether or not this pool is to block on check outs that cannot be fulfilled.
void	setCheckoutBlockTime(long pBlockTime) The maximum time in milli-seconds to block waiting for a resource on checkout.
void	setCreationTimeLimit(long pCreateTime) This is the resource creation time limit in milli-seconds.
void	setDebugConnections(boolean pDebugConnections) Sets the property DebugConnections.
void	setLastError(java.lang.String pLastError) Sets the property LastError.
void	setMax(int pMax) Sets the maximum number of objects to have pooled at any given time, free or checked out.
void	setMaxFree(int pMaxFree) The maximum number of free objects to have pooled at any given time.
void	setMaxIdleAge(long pMaxIdleAge) Sets property maxIdleAge.
void	setMaxPendingCreations(int pCreateAttempts) This is the maximum number of pending resource creation attempts to allow when there are no valid resources being managed by the pool.
void	setMaxResourceAge(long pMaxResourceAge) Sets property maxResourceAge.
void	setMaxResourcesPerThread(int pMaxResourcesPerThread) Sets property maxResourcesPerThread.
void	setMaxThreadsWithResourcesOut(int pMaxThreadsWithResourcesOut) Sets property maxThreadsWithResourcesOut.
void	setMin(int pMin) Sets the minimum number of objects to have pooled at startup.
void	setResourceClassName(java.lang.String pResourceClassName) Sets the class name of the resource to be pooled.
void	setStartupAttempts(int pValue) The number of startup attempts to make.
void	setStartupFailureSleepTime(long pSleepTime) The time in milli-seconds to sleep between startup attempts.
void	setWarnOnNestedCheckouts(boolean pWarnOnNestedCheckouts) Sets property warnOnNestedCheckouts.
void	unblock() Unblocks associated blocked threads.
boolean	verifyResourceValidity(ResourceObject pResource) Returns whether or not the given resource is still suitable for use in the pool.

Methods inherited from class atg.nucleus.GenericService

addLogListener, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

mPool

public ResourceObject[] mPool

The pool of checked in objects.

mFreeResources

public atg.core.util.IntQueue mFreeResources

The pool of free objects.

mUnusedPoolSlots

public atg.core.util.IntStack mUnusedPoolSlots

The list of unused spaces in the pool.

mCreatingResources

public atg.core.util.IntStack mCreatingResources

List of slots currently being filled.

mMin

public int mMin

The minimum number of objects to pool.

mMax

public int mMax

The maximum number of objects to pool.

mMaxFree

public int mMaxFree

The maximum number of free pooled objects at a time.

mBlocking

public boolean mBlocking

Whether or not the pool is to block on check outs.

mCheckoutBlockTime

public long mCheckoutBlockTime

Maximum time in milli-seconds to block.

mCreationTimeLimit

public long mCreationTimeLimit

Resource creation time limit in milli-seconds for a healthy pool.

mMaxPendingCreations

public int mMaxPendingCreations

Concurrent creation attempts allowed for a healthy pool.

mMaxStartupAttempts

public int mMaxStartupAttempts

Maximum startup attempts.

mStartupSleepTime

public long mStartupSleepTime

Time in millis to sleep between startup attempts.

mResourceClassName

public java.lang.String mResourceClassName

The class name of the object being pooled.

mHealthy

public boolean mHealthy

Whether or not the pool is active.

Constructor Detail

ResourcePool

public ResourcePool()

Constructs an uninitialized ResourcePool.

Method Detail

setMin

public void setMin(int pMin)

Sets the minimum number of objects to have pooled at startup.

Parameters:

pMin - the minimum

getMin

public int getMin()

Returns the minimum number of objects to have pooled at start-up.

Returns:

int

setMax

public void setMax(int pMax)

Sets the maximum number of objects to have pooled at any given time, free or checked out.

Parameters:

pMax - the maximum

getMax

public int getMax()

Returns the maximum number of objects to have pooled at any given time, free or checked out.

Returns:

int

setMaxFree

public void setMaxFree(int pMaxFree)

The maximum number of free objects to have pooled at any given time. Use this if the pooled resources are expensive to keep around, setting it to an ideal number. Max free will not affect the minimum number of resources kept in the pool. For example, if the pooled minimum is 5 and max free is 3, only 3 free resource will be in the pool at any given time, as long as the total number of resources being managed by the pool doesn't drop below 5. Therefore, if no resources are checked out, then there will be 5 free resources in the pool. If destroying free objects is not desirable, then max free should be set to (-1), the default value and behaviour. There is no harm in having max free exceed the max objects in the pool, as this too will prevent the destruction of free objects.

Parameters:

pMaxFree - the maximum free

getMaxFree

public int getMaxFree()

The maximum number of free objects to have pooled at any given time. Use this if the pooled resources are expensive to keep around, setting it to an ideal number. Max free will not affect the minimum number of resources kept in the pool. For example, if the pooled minimum is 5 and max free is 3, only 3 free resource will be in the pool at any given time, as long as the total number of resources being managed by the pool doesn't drop below 5. Therefore, if no resources are checked out, then there will be 5 free resources in the pool. If destroying free objects is not desirable, then max free should be set to (-1), the default value and behaviour. There is no harm in having max free exceed the max objects in the pool, as this too will prevent the destruction of free objects.

Returns:

int

setBlocking

public void setBlocking(boolean pBlocking)

Sets whether or not this pool is to block on check outs that cannot be fulfilled.

Parameters:

pBlocking - flag for blocking

getBlocking

public boolean getBlocking()

Returns whether or not this pool is to block on check outs that cannot be fulfilled.

Returns:

boolean true if pool blocks
false if pool will not block

setCheckoutBlockTime

public void setCheckoutBlockTime(long pBlockTime)

The maximum time in milli-seconds to block waiting for a resource on checkout. A value of zero (the default) indicates indefinite blocking.

Parameters:

pBlockTime - the checkout block timeout in milli-seconds

getCheckoutBlockTime

public long getCheckoutBlockTime()

The maximum time in milli-seconds to block waiting for a resource on checkout. A value of zero (the default) indicates indefinite blocking.

Returns:

long the checkout block timeout in milli-seconds

setWarnOnNestedCheckouts

public void setWarnOnNestedCheckouts(boolean pWarnOnNestedCheckouts)

Sets property warnOnNestedCheckouts.

Whether or not to warn on nested resource checkouts. A nested checkout is defined as checking out a second resource before a first resource is returned to the pool. This is sometimes masked by the second checkout being in a method call. The nested checkout warning message states how many resources a thread has out concurrently. Since nested checkouts potentially produce pool deadlocks, this warning message can be useful.

Note: this property is subordinate to the loggingWarning property. If loggingWarning is turned off and this property is turned on, no warning will be logged. If loggingWarning is turned on and this property is turned off, no warning will logged. Only when both properties are turned on will a warning be logged.

Parameters:

pWarnOnNestedCheckouts - new value to set

isWarnOnNestedCheckouts

public boolean isWarnOnNestedCheckouts()

Returns property warnOnNestedCheckouts.

Whether or not to warn on nested resource checkouts. A nested checkout is defined as checking out a second resource before a first resource is returned to the pool. This is sometimes masked by the second checkout being in a method call. The nested checkout warning message states how many resources a thread has out concurrently. Since nested checkouts potentially produce pool deadlocks, this warning message can be useful.

Note: this property is subordinate to the loggingWarning property. If loggingWarning is turned off and this property is turned on, no warning will be logged. If loggingWarning is turned on and this property is turned off, no warning will logged. Only when both properties are turned on will a warning be logged.

Returns:

boolean

setMaxThreadsWithResourcesOut

public void setMaxThreadsWithResourcesOut(int pMaxThreadsWithResourcesOut)

Sets property maxThreadsWithResourcesOut.
The maximum number of threads allowed to have resources out of the pool concurrently.

When code is written that allows a thread to nest checkouts of resources, i.e. checking out a second resource before a first resource is returned to the pool, the potential for deadlock is created. A simple solution to this problem is to make sure that there are enough resources in the pool for all threads and their nested checkouts. But in some cases resources are expensive and the pool must be kept small. In such a situation if the number of resources a thread will ever have concurrently out of the pool is known, then limiting the number of threads allowed to have resources out of the pool concurrently will prevent deadlocks. The limit of course would be maximum pool size divided by the maximum number of resources any given thread might have out of the pool concurrently.

The default value is 0. Setting this property to any value less than 1 will turn off this functionality.

The warning message controlled by the warnOnNestedCheckouts property is useful for finding out the maximum number of resources any given thread might have out of the pool concurrently.

The property maxThreadsWithResourcesOut can be used to limit the number of resources an thread can have out of the pool concurrently.

Parameters:

pMaxThreadsWithResourcesOut - new value to set

getMaxThreadsWithResourcesOut

public int getMaxThreadsWithResourcesOut()

Sets property maxThreadsWithResourcesOut.
The maximum number of threads allowed to have resources out of the pool concurrently.

When code is written that allows a thread to nest checkouts of resources, i.e. checking out a second resource before a first resource is returned to the pool, the potential for deadlock is created. A simple solution to this problem is to make sure that there are enough resources in the pool for all threads and their nested checkouts. But in some cases resources are expensive and the pool must be kept small. In such a situation if the number of resources a thread will ever have concurrently out of the pool is known, then limiting the number of threads allowed to have resources out of the pool concurrently will prevent deadlocks. The limit of course would be maximum pool size divided by the maximum number of resources any given thread might have out of the pool concurrently.

The default value is 0. Setting this property to any value less than 1 will turn off this functionality.

The warning message controlled by the warnOnNestedCheckouts property is useful for finding out the maximum number of resources any given thread might have out of the pool concurrently.

The property maxThreadsWithResourcesOut can be used to limit the number of resources an thread can have out of the pool concurrently.

Returns:

int

setMaxResourcesPerThread

public void setMaxResourcesPerThread(int pMaxResourcesPerThread)

Sets property maxResourcesPerThread.
The maximum number of resources any thread can have out of the pool concurrently.

When code is written that allows a thread to nest checkouts of resources, i.e. checking out a second resource before a first resource is returned to the pool, the potential for deadlock is created. Since nested calls can happen inadvertently through method calls, this property can be used to throw an exception when a thread tries to exceed the specified number of nested checkouts. The default value is 0. Setting this property to any value less than 1 will turn off this functionality.

Parameters:

pMaxResourcesPerThread - new value to set

getMaxResourcesPerThread

public int getMaxResourcesPerThread()

Returns property maxResourcesPerThread.
The maximum number of resources any thread can have out of the pool concurrently.

When code is written that allows a thread to nest checkouts of resources, i.e. checking out a second resource before a first resource is returned to the pool, the potential for deadlock is created. Since nested calls can happen inadvertently through method calls, this property can be used to throw an exception when a thread tries to exceed the specified number of nested checkouts. The default value is 0. Setting this property to any value less than 1 will turn off this functionality.

Returns:

int

setCreationTimeLimit

public void setCreationTimeLimit(long pCreateTime)

This is the resource creation time limit in milli-seconds. This property is used to detect a possible pool death. There are two behaviours associated with this property:

First behaviour: If a resource creation fails and the attempt exceeded the creation time limit (this property), then the pool will be disabled.

Second behaviour: Before a resource creation attempt is made, a check is done to see if there is a resource creation attempt already in progress that has exceeded the time limit. If such an attempt is found, then the pool will be disabled.

Note: the resource creation time limit will not cause resource creations to timeout.

A value of zero (the default) disables the resource creation time limit.

Parameters:

pCreateTime - resource creation time limit in milli-seconds

getCreationTimeLimit

public long getCreationTimeLimit()

This is the resource creation time limit in milli-seconds. This property is used to detect a possible pool death. There are two behaviours associated with this property:

First behaviour: If a resource creation fails and the attempt exceeded the creation time limit (this property), then the pool will be disabled.

Second behaviour: Before a resource creation attempt is made, a check is done to see if there is a resource creation attempt already in progress that has exceeded the time limit. If such an attempt is found, then the pool will be disabled.

Note: the resource creation time limit will not cause resource creations to timeout.

A value of zero (the default) disables the resource creation time limit.

Returns:

long the resource creation time limit in milli-seconds

setMaxPendingCreations

public void setMaxPendingCreations(int pCreateAttempts)

This is the maximum number of pending resource creation attempts to allow when there are no valid resources being managed by the pool. This property is used to detect a possible pool death.

The pool will be disabled if the following criteria are met:

• the pool is not in its start-up cycle
• minimum allowed resources is greater than zero
• there are no valid resources being managed by the pool
• the number of outstanding resource creation attempts exceeds the maximum number of pending resource creation attempts (this property)

A value of zero (the default) disables this feature.

getMaxPendingCreations

public int getMaxPendingCreations()

This is the maximum number of pending resource creation attempts to allow when there are no valid resources being managed by the pool. This property is used to detect a possible pool death.

The pool will be disabled if the following criteria are met:

• the pool is not in its start-up cycle
• minimum allowed resources is greater than zero
• there are no valid resources being managed by the pool
• the number of outstanding resource creation attempts exceeds the maximum number of pending resource creation attempts (this property)

A value of zero (the default) disables this feature.

setStartupAttempts

public void setStartupAttempts(int pValue)

The number of startup attempts to make. When a minimum number of resources is specified for a pool, those resources are created at service start time. If the creation of the minimum number of resources fails, the pool will make repeat attempts to initialize the resource minimum.

getStartupAttempts

public int getStartupAttempts()

The number of startup attempts to make. When a minimum number of resources is specified for a pool, those resources are created at service start time. If the creation of the minimum number of resources fails, the pool will make repeat attempts to initialize the resource minimum.

setStartupFailureSleepTime

public void setStartupFailureSleepTime(long pSleepTime)

The time in milli-seconds to sleep between startup attempts.

Parameters:

pSleepTime - time to sleep in milli-seconds

getStartupFailureSleepTime

public long getStartupFailureSleepTime()

The time in milli-seconds to sleep between startup attempts.

Returns:

long time to sleep in milli-seconds

setMaxIdleAge

public void setMaxIdleAge(long pMaxIdleAge)

Sets property maxIdleAge.

Maximum idle age for a resource in milli-seconds.

Free resources are queued allowing all of them to be cycled through over time, but in a rarely used pool, resources might be idle longer than is good for them. If idle resources (like a socket) are known to timeout after a certain amount of idle time, then setting this property to the appropriate value will prevent potentially bad resources from being checked out of the pool.

Parameters:

pMaxIdleAge - new value to set

getMaxIdleAge

public long getMaxIdleAge()

Returns property maxIdleAge.

Maximum idle age for a resource in milli-seconds.

Free resources are queued allowing all of them to be cycled through over time, but in a rarely used pool, resources might be idle longer than is good for them. If idle resources (like a socket) are known to timeout after a certain amount of idle time, then setting this property to the appropriate value will prevent potentially bad resources from being checked out of the pool. Resources that exceed this age limit will be destroyed and replaced with new resources.

A value of (-1) or 0 will disable this feature and no resources will be destroyed due to their idle age.

Returns:

long

setMaxResourceAge

public void setMaxResourceAge(long pMaxResourceAge)

Sets property maxResourceAge.

Maximum age for a resource in milli-seconds.

Some resources may be time sensitive and have a limited life span whether idle or not. Setting this property will prevent resources that are potentially too old from being checked out of the pool. Resources that exceed this age limit will be destroyed and replaced with new resources.

A value of (-1) or 0 will disable this feature and no resources will be destroyed due to their age.

Parameters:

pMaxResourceAge - new value to set

getMaxResourceAge

public long getMaxResourceAge()

Sets property maxResourceAge.

Maximum age for a resource in milli-seconds.

Some resources may be time sensitive and have a limited life span whether idle or not. Setting this property will prevent resources that are potentially too old from being checked out of the pool. Resources that exceed this age limit will be destroyed and replaced with new resources.

A value of (-1) or 0 will disable this feature and no resources will be destroyed due to their age. Maximum age for a resource.

Returns:

long

setResourceClassName

public void setResourceClassName(java.lang.String pResourceClassName)

Sets the class name of the resource to be pooled.

Setting this property on ResourcePool will cause the pool to create and destroy objects of this class automatically. The resource must be able to be instantiated with an empty constructor for the pool to operate in this manner.

Parameters:

pResourceClassName - the resource class name

getResourceClassName

public java.lang.String getResourceClassName()

Returns the class name of the pooled resource.

Setting this property on ResourcePool will cause the pool to create and destroy objects of this class automatically. The resource must be able to be instantiated with an empty constructor for the pool to operate in this manner.

Returns:

String

isEnabled

public boolean isEnabled()

Whether or not this pool is still considered active. If there is trouble creating resources a pool can flag itself inactive so that threads requesting resources will not hang.

getNumFreeResources

public int getNumFreeResources()

Returns the number of free resources in the pool. This number refers to actually created resources that are not currently checked out. It does not include how many more resource are allowed to be created as set by the maximum number of resources allowed in the pool.

Returns:

int

getNumTotalResources

public int getNumTotalResources()

Returns the number of total resources in the pool. This number refers to actually created resources and is not an indication of how many more resources may be created and used in the pool.

Returns:

int

getNumCheckedOutResources

public int getNumCheckedOutResources()

Returns the number of resources checked out.

setLastError

public void setLastError(java.lang.String pLastError)

Sets the property LastError.

getLastError

public java.lang.String getLastError()

Returns:

The value of the property LastError.

getAverageResourceCreationTime

public long getAverageResourceCreationTime()

Returns the average time in milli-seconds required to successfully create a resource for the pool.

getMaxSimultaneousResourcesOut

public int getMaxSimultaneousResourcesOut()

Returns property maxSimultaneousResourcesOut.
The most resources that were ever out of the pool at one time.

Returns:

int

getMaxConcurrentThreads

public int getMaxConcurrentThreads()

Returns property maxConcurrentThreads.
The maximum number of threads that had resources out of the pool concurrently.

Returns:

int

getMaxConcurrentResourcesPerThread

public int getMaxConcurrentResourcesPerThread()

Returns property maxConcurrentResourcesPerThread.
The maximum number of resources any thread had out of the pool concurrently.

Returns:

int

doStartService

public void doStartService()
                    throws ServiceException

This is called after the service has been created, added to the Registry, and configured. This method should start any processes required to run the service.

Overrides:

doStartService in class GenericService

Throws:

ServiceException - if an error occurred during the operation

doStopService

public void doStopService()
                   throws ServiceException

This is called when the service is to be stopped. The service should stop any processes that it started, basically performing the opposite function as startService(). The service should also release any resources it has. After this method is called, Nucleus may choose to discard the service. Note: this method sets the pool to NOT allow check outs. Checked out items are not harmed and are allowed to be checked in.

Overrides:

doStopService in class GenericService

Throws:

ServiceException - if an error occurred during the operation

finalize

public void finalize()

Destroys all resources in the pool regardless of whether or not they are checked out and uninitializes the pool.

Overrides:

finalize in class java.lang.Object

createResource

public java.lang.Object createResource()
                                throws ResourcePoolException

Creates an object for pooling. Note that the object is not wrapped in a ResourceObject, checked in, or associated with the pool in any way. NOTE: If this class is sub-classed to pool a specific object, this method should probably be over-loaded to create the object being pooled.

Returns:

Object on success

Throws:

ResourcePoolException - if there was a problem creating the resource

destroyResource

public void destroyResource(java.lang.Object pResource)

Destroys a resource object of this pool. Note that the pool is not modified in any way, the object alone is destroyed. NOTE: If this class is sub-classed to pool a specific object, this method should probably be over-loaded to destroy the object being pooled.

Parameters:

pResource - the Object to destroy

verifyResourceValidity

public boolean verifyResourceValidity(ResourceObject pResource)

Returns whether or not the given resource is still suitable for use in the pool. NOTE: If this class is sub-classed to pool a specific object, this method should probably be over-loaded to verify the object being pooled.

Parameters:

pResource - the ResourceObject to verify

Returns:

boolean true if the resource is still usable
false if the resource is not usable

checkOut

public ResourceObject checkOut(java.lang.String pCheckOutTag)
                        throws ResourcePoolException

Checks a resource out of the pool. If there are no free resources and the pool max has been reached, the pool will either block (if blocking has been turned on) or throw an exception. Null will never be returned.

Returns:

The object or null if mConfig.mPoolMax has been reached

Throws:

ResourcePoolException - if an error occurred during the operation

checkIn

public void checkIn(ResourceObject pResource)
             throws ResourcePoolException

Checks a resource into the pool.

Parameters:

pResource - a resource checked out from this pool

Throws:

ResourcePoolException - if an error occurred during the operation

block

public void block(long pTimeout)

Causes this thread to block.

unblock

public void unblock()

Unblocks associated blocked threads.

invalidateAllResources

public void invalidateAllResources()

Runs through the list of all resources (in or out of the pool) and flags them as invalid. Upon checkin or checkout they will be destroyed. This is a way of invalidating all resources currently managed by the pool. Resources currently out of the pool will likely continue to be used but once returned to the pool they will be destroyed and eventually replaced.

pruneFreeResources

public void pruneFreeResources()

Runs through the list of free resources and destroys all of them. This method used to destroy them down to the pool minimum, but since the intent of this method was to allow sites that needed to clean out their pool to do so, it makes little sense to leave any free resources hanging around.

Note that the introduction of maxIdleAge may make this method obsolete.

This method is only useful for pools that have very brief periods of activity and then are not used for extended periods of time. This method should not be called on an active pool, only on an idle pool.

resetMaxSimultaneousResourcesOut

public void resetMaxSimultaneousResourcesOut()

Resets the maxSimultaneousResourcesOut property to zero.

resetMaxConcurrentThreads

public void resetMaxConcurrentThreads()

Resets the maxConcurrentThreads property to zero.

resetMaxConcurrentResourcesPerThread

public void resetMaxConcurrentResourcesPerThread()

Resets the maxConcurrentResourcesPerThread property to zero.

populateSlot

public void populateSlot(int pIndex)
                  throws ResourcePoolException

Populates the specified slot with a valid resource and appropriate meta-data. The slot is identified during resource creation as being in limbo so that pool death is easier to detect. If a resource fails to create and exceeds the creation time limit, the pool is set to inactive and all blocked threads are notified.

Throws:

ResourcePoolException

reclaimResource

protected void reclaimResource(ResourceObject pRobj)
                        throws ResourcePoolException

A separate method for reclaiming resources incase sub-classes need to do this differently.

Throws:

ResourcePoolException

addAdminInfo

protected void addAdminInfo(javax.servlet.http.HttpServletRequest pRequest,
                            javax.servlet.http.HttpServletResponse pResponse,
                            javax.servlet.ServletOutputStream pOut)
                     throws javax.servlet.ServletException,
                            java.io.IOException

Adds to the HTML Admin response any information specific to the the ResourcePool subclass. Yes, this is a hack.

Throws:

javax.servlet.ServletException

java.io.IOException

createAdminServlet

protected javax.servlet.Servlet createAdminServlet()

Creates and returns a new Servlet that will administer this service. By default, this creates a ServiceAdminServlet, but subclasses may create their own servlets.

Overrides:

createAdminServlet in class GenericService

setDebugConnections

public void setDebugConnections(boolean pDebugConnections)

Sets the property DebugConnections. This causes the stack trace of where each resource is checked out to be recorded so that you can view if from the component browser. Use this to find places that may be leaking connections.

getDebugConnections

public boolean getDebugConnections()

Returns:

The value of the property DebugConnections.

getCurrentStack

protected java.lang.String getCurrentStack()

Get the current stack trace for debugging