|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object atg.nucleus.logging.VariableArgumentApplicationLoggingImpl atg.nucleus.GenericService atg.service.resourcepool.ResourcePool
public class ResourcePool
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.
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.
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.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 |
---|
public static java.lang.String CLASS_VERSION
public ResourceObject[] mPool
public atg.core.util.IntQueue mFreeResources
public atg.core.util.IntStack mUnusedPoolSlots
public atg.core.util.IntStack mCreatingResources
public int mMin
public int mMax
public int mMaxFree
public boolean mBlocking
public long mCheckoutBlockTime
public long mCreationTimeLimit
public int mMaxPendingCreations
public int mMaxStartupAttempts
public long mStartupSleepTime
public java.lang.String mResourceClassName
public boolean mHealthy
Constructor Detail |
---|
public ResourcePool()
Method Detail |
---|
public void setMin(int pMin)
pMin
- the minimumpublic int getMin()
public void setMax(int pMax)
pMax
- the maximumpublic int getMax()
public void setMaxFree(int pMaxFree)
pMaxFree
- the maximum freepublic int getMaxFree()
public void setBlocking(boolean pBlocking)
pBlocking
- flag for blockingpublic boolean getBlocking()
public void setCheckoutBlockTime(long pBlockTime)
pBlockTime
- the checkout block timeout in milli-secondspublic long getCheckoutBlockTime()
public void setWarnOnNestedCheckouts(boolean pWarnOnNestedCheckouts)
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.
pWarnOnNestedCheckouts
- new value to setpublic boolean isWarnOnNestedCheckouts()
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.
public void setMaxThreadsWithResourcesOut(int pMaxThreadsWithResourcesOut)
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.
pMaxThreadsWithResourcesOut
- new value to setpublic int getMaxThreadsWithResourcesOut()
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.
public void setMaxResourcesPerThread(int pMaxResourcesPerThread)
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.
pMaxResourcesPerThread
- new value to setpublic int getMaxResourcesPerThread()
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.
public void setCreationTimeLimit(long pCreateTime)
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.
pCreateTime
- resource creation time limit in milli-secondspublic long getCreationTimeLimit()
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.
public void setMaxPendingCreations(int pCreateAttempts)
The pool will be disabled if the following criteria are met:
public int getMaxPendingCreations()
The pool will be disabled if the following criteria are met:
public void setStartupAttempts(int pValue)
public int getStartupAttempts()
public void setStartupFailureSleepTime(long pSleepTime)
pSleepTime
- time to sleep in milli-secondspublic long getStartupFailureSleepTime()
public void setMaxIdleAge(long pMaxIdleAge)
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.
pMaxIdleAge
- new value to setpublic long getMaxIdleAge()
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.
public void setMaxResourceAge(long pMaxResourceAge)
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.
pMaxResourceAge
- new value to setpublic long getMaxResourceAge()
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.
public void setResourceClassName(java.lang.String pResourceClassName)
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.
pResourceClassName
- the resource class namepublic java.lang.String getResourceClassName()
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.
public boolean isEnabled()
public int getNumFreeResources()
public int getNumTotalResources()
public int getNumCheckedOutResources()
public void setLastError(java.lang.String pLastError)
public java.lang.String getLastError()
public long getAverageResourceCreationTime()
public int getMaxSimultaneousResourcesOut()
public int getMaxConcurrentThreads()
public int getMaxConcurrentResourcesPerThread()
public void doStartService() throws ServiceException
doStartService
in class GenericService
ServiceException
- if an error occurred during the operationpublic void doStopService() throws ServiceException
doStopService
in class GenericService
ServiceException
- if an error occurred during the operationpublic void finalize()
finalize
in class java.lang.Object
public java.lang.Object createResource() throws ResourcePoolException
ResourcePoolException
- if there was a problem creating the
resourcepublic void destroyResource(java.lang.Object pResource)
pResource
- the Object to destroypublic boolean verifyResourceValidity(ResourceObject pResource)
pResource
- the ResourceObject to verify
public ResourceObject checkOut(java.lang.String pCheckOutTag) throws ResourcePoolException
ResourcePoolException
- if an error occurred during the
operationpublic void checkIn(ResourceObject pResource) throws ResourcePoolException
pResource
- a resource checked out from this pool
ResourcePoolException
- if an error occurred during the
operationpublic void block(long pTimeout)
public void unblock()
public void invalidateAllResources()
public void pruneFreeResources()
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.
public void resetMaxSimultaneousResourcesOut()
public void resetMaxConcurrentThreads()
public void resetMaxConcurrentResourcesPerThread()
public void populateSlot(int pIndex) throws ResourcePoolException
ResourcePoolException
protected void reclaimResource(ResourceObject pRobj) throws ResourcePoolException
ResourcePoolException
protected void addAdminInfo(javax.servlet.http.HttpServletRequest pRequest, javax.servlet.http.HttpServletResponse pResponse, javax.servlet.ServletOutputStream pOut) throws javax.servlet.ServletException, java.io.IOException
javax.servlet.ServletException
java.io.IOException
protected javax.servlet.Servlet createAdminServlet()
createAdminServlet
in class GenericService
public void setDebugConnections(boolean pDebugConnections)
public boolean getDebugConnections()
protected java.lang.String getCurrentStack()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |