ResourcePool (ATG Java API)

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

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, 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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description

ResourcePool()
Constructs an uninitialized ResourcePool.

Constructors
Constructor and Description
`ResourcePool()` Constructs an uninitialized ResourcePool.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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`	`dumpCheckOutLocationsOfOpenResources()` Dump out the check out stack locations for all checked out resources.
`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`	`isDumpCheckOutLocationsOfOpenResources()` Returns property dumpCheckOutLocationsOfOpenResources.
`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`	`setDumpCheckOutLocationsOfOpenResources(boolean pDumpCheckOutLocationsOfOpenResources)` Sets property dumpCheckOutLocationsOfOpenResources.
`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, toString

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, 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
  - dumpCheckOutLocationsOfOpenResources
```
public void dumpCheckOutLocationsOfOpenResources()
```
    Dump out the check out stack locations for all checked out resources. Only populated if the dumpCheckOutLocationsOfOpenResources property was set to true at resource checkout time.
  - 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.
  - setDumpCheckOutLocationsOfOpenResources
```
public void setDumpCheckOutLocationsOfOpenResources(boolean pDumpCheckOutLocationsOfOpenResources)
```
    Sets property dumpCheckOutLocationsOfOpenResources. Whether to dump out the location of open resources at shutdown to stderr.
  - isDumpCheckOutLocationsOfOpenResources
```
public boolean isDumpCheckOutLocationsOfOpenResources()
```
    Returns property dumpCheckOutLocationsOfOpenResources. Whether to dump out the location of open resources at shutdown to stderr. A true value also enables tracking of checkouts; that data can be dumped at any time via the dumpCheckOutLocationsOfOpenResources() method.
  - getCurrentStack
```
protected java.lang.String getCurrentStack()
```
    Get the current stack trace for debugging

Class ResourcePool

Pool Size

Pool Death

Pool Deadlock

Field Summary

Fields inherited from class atg.nucleus.GenericService

Fields inherited from interface atg.service.resourcepool.ResourcePoolResourceKeys

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

Constructor Summary

Method Summary

Methods inherited from class atg.nucleus.GenericService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

Methods inherited from class java.lang.Object

Field Detail

CLASS_VERSION

mPool

mFreeResources

mUnusedPoolSlots

mCreatingResources

mMin

mMax

mMaxFree

mBlocking

mCheckoutBlockTime

mCreationTimeLimit

mMaxPendingCreations

mMaxStartupAttempts

mStartupSleepTime

mResourceClassName

mHealthy

Constructor Detail

ResourcePool

Method Detail

setMin

getMin

setMax

getMax

setMaxFree

getMaxFree

setBlocking

getBlocking

setCheckoutBlockTime

getCheckoutBlockTime

setWarnOnNestedCheckouts

isWarnOnNestedCheckouts

setMaxThreadsWithResourcesOut

getMaxThreadsWithResourcesOut

setMaxResourcesPerThread

getMaxResourcesPerThread

setCreationTimeLimit

getCreationTimeLimit

setMaxPendingCreations

getMaxPendingCreations

setStartupAttempts

getStartupAttempts

setStartupFailureSleepTime

getStartupFailureSleepTime

setMaxIdleAge

getMaxIdleAge

setMaxResourceAge

getMaxResourceAge

setResourceClassName

getResourceClassName

isEnabled

getNumFreeResources

getNumTotalResources

getNumCheckedOutResources

setLastError

getLastError

getAverageResourceCreationTime

getMaxSimultaneousResourcesOut

getMaxConcurrentThreads

getMaxConcurrentResourcesPerThread

doStartService

doStopService

dumpCheckOutLocationsOfOpenResources

finalize

createResource

destroyResource