oracle.jbo.pool
Class ResourcePool

java.lang.Object
  oracle.jbo.pool.ResourcePool

Direct Known Subclasses:

ApplicationPoolImpl, QueryCollectionPool

public abstract class ResourcePool
extends java.lang.Object

A base class for pooling resources. A resource is any java object which may be reused in the context of virtual machine. Pooled resources are acquired or created by invoking useResource(Properties). Pooled resources are released for reuse by invoking releaseResource(Object, Properties).

The base resource class implements some common pool features. These include:

(*) Initial pool size

(*) Maximum pool size

(*) Pool garbage collection

(*) Statistic collection and reporting

Field Summary

static long	MAX_WAIT_TIME
protected java.lang.Integer	mLock
protected ResourcePoolLogger	mLogger
static long	WAIT_TIME_INCREMENT

Constructor Summary

ResourcePool()

Method Summary

void	addResource(java.lang.Object resource) Add a resource to the resource pool.
void	addToRemoveList(java.lang.Object resource)
protected java.lang.Object	allocateResource() Allocate storage for a new resource.
protected void	beforeResourceFinalized(java.lang.Object resource) This method is invoked immediately before resource finalization.
protected boolean	canAllocateResource(java.lang.Object resource) Invoked by allocateResource to determine that an existing resource can be allocated to the invoker.
protected boolean	canFinalizeResource(java.lang.Object resource) Invoked by removeResource to determine if the resource can be removed from the pool by the current thread.
protected boolean	canRemoveResource(java.lang.Object resource) Invoked from gc() to ensure that the specified resource may be removed from the ResourcePool.
protected void	createInitializer(java.util.Properties properties)
protected ResourcePoolLogger	createPoolLogger()
protected java.lang.Object	createResource(java.util.Properties properties) Create a new pooled resource.
protected void	decrementRefCount(java.lang.Object resource)
protected void	destroy() Detroy the resource pool.
void	dumpPoolStatistics(java.io.PrintWriter pw) Dump pool statistics to the specified printwriter.
protected void	finalizeResource(java.lang.Object resource, java.lang.Object details) Invoked during pool high water mark resolution.
int	getAvailableResourceCount() Get the number of available resources in the resource pool.
protected long	getCreationTimeMillis(java.lang.Object resource) Return the time (ms) at which the resource was created.
java.lang.Thread	getInitializer() INTERNAL USE ONLY: Applications should not use this method
protected int	getInitPoolSize() Return get initial pool size.
protected int	getMaxAvailableSize() Return the maximum number of available instances that should exist in the pool after pool garbage collection.
protected int	getMaxInactiveAge() Return the duration in milliseconds that a resource may remain available before it is considered inactive.
protected int	getMaxPoolSize() Return the maximum pool size.
protected long	getMaxWaitTime() Return the maximum amount of time in milliseconds that a request should wait for an available pool resource.
protected int	getMinAvailableSize() Return the minimum number of available instances that should exist in the pool after pool garbage collection.
java.lang.String	getName()
protected int	getRefCount(java.lang.Object resource)
protected java.lang.Object	getResource(int index)
int	getResourceCount() Returns the number of resources that are currently registered with the pool.
protected java.lang.Object	getResourceDetails(java.lang.Object resource) This method is invoked for every removal candidate when the pool high water mark is reached.
protected ResourceInfo	getResourceInfo(java.lang.Object resource) Return the resource details object.
protected abstract java.lang.Object	getResourcePoolKey()
ResourcePoolStatistics	getResourcePoolStatistics() Copy pool statistics into a structure and return.
protected byte	getState(java.lang.Object resource)
java.lang.Object	getSyncLock() INTERNAL USE ONLY.
protected long	getTimeToCreateMillis(java.lang.Object resource) Return the time (ms) required to create the resource.
protected int	getTimeToLive() Return the duration in milliseconds that a resource may remain in the pool.
protected void	incrementRefCount(java.lang.Object resource)
void	initialize(java.util.Properties properties) Initializes the resource pool.
abstract java.lang.Object	instantiateResource(java.util.Properties properties) Instantiate a new pooled resource.
protected boolean	isAvailable(java.lang.Object resource) INTERNAL USE ONLY.
protected boolean	isUseExclusive() Determines if poooled resources are used serially.
protected void	logPoolEvent(byte eventType) INTERNAL USE ONLY.
void	markResourcesForRemove() Mark all resources in the pool for removal.
protected void	prepareForGCRemove(java.util.ArrayList resources, java.lang.Object resource)
protected void	prepareResource(java.lang.Object resource, java.util.Properties props) Invoked immediately before a resource is referenced.
void	releaseResource(java.lang.Object resource, java.util.Properties properties) Release a resource that was previously acquired from the pool with useResource(Properties).
protected boolean	removeFromManager()
java.lang.Object	removeResource(java.lang.Object resource) Remove a resource from the pool.
protected boolean	removeResourceInternal(java.lang.Object resource)
java.util.ArrayList	removeResources() Remove all resources from the resource pool.
protected void	resourceStateChanged(java.lang.Object resource, byte state, byte oldState) Invoked during setState.
protected java.lang.Object	seekLRUAvailableResource(java.lang.Object refResource) Return the least recently used available resource in the pool.
protected java.lang.Object	seekMRUAvailableResource(java.lang.Object refResource) Return the most recently used available resource in the pool.
protected void	setAvailable(java.lang.Object resource) INTERNAL USE ONLY.
protected void	setAvailable(java.lang.Object resource, boolean isAvailable) INTERNAL USE ONLY.
protected boolean	setState(java.lang.Object resource, byte state, java.util.Properties props)
java.lang.Object	useResource(java.util.Properties properties) Acquire a resource from the pool for exclusive use.
void	wakeup() Wakeup the resource pool.

Methods inherited from class java.lang.Object

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

Field Detail

mLock

protected final java.lang.Integer mLock

mLogger

protected transient ResourcePoolLogger mLogger

WAIT_TIME_INCREMENT

public static final long WAIT_TIME_INCREMENT

See Also:

Constant Field Values

MAX_WAIT_TIME

public static final long MAX_WAIT_TIME

See Also:

Constant Field Values

Constructor Detail

ResourcePool

public ResourcePool()

Method Detail

initialize

public void initialize(java.util.Properties properties)

Initializes the resource pool. Pool initialization is deferred until after construction because initialization may depend upon the values of pool properties which may be set at runtime. A pool may only be initialized once in a VM. After a pool has been initialized subsequent initialization requests are ignored.

Parameters:

properties - Initialization properties. These properties may be passed to initialization subroutines.

createInitializer

protected void createInitializer(java.util.Properties properties)

getName

public java.lang.String getName()

getInitializer

public java.lang.Thread getInitializer()

INTERNAL USE ONLY: Applications should not use this method

getResourceCount

public int getResourceCount()

Returns the number of resources that are currently registered with the pool.

useResource

public java.lang.Object useResource(java.util.Properties properties)

Acquire a resource from the pool for exclusive use. Attempts to acquire an existing, available resource if one exists. Otherwise, attempts to create a new pooled resource for the request.

Parameters:

properties - Resource creation properties. These properties are passed to instantiateResource(Properties) if it is necesary to create a new resource.

incrementRefCount

protected void incrementRefCount(java.lang.Object resource)

decrementRefCount

protected void decrementRefCount(java.lang.Object resource)

getRefCount

protected int getRefCount(java.lang.Object resource)

releaseResource

public void releaseResource(java.lang.Object resource,
                            java.util.Properties properties)

Release a resource that was previously acquired from the pool with useResource(Properties). Throws an exception if the resource was not checked out from the pool.

logPoolEvent

protected void logPoolEvent(byte eventType)

INTERNAL USE ONLY. Applications should not use this method.

dumpPoolStatistics

public void dumpPoolStatistics(java.io.PrintWriter pw)

Dump pool statistics to the specified printwriter. This call delegates to the pool logger which was created an registered with the pool when the pool was initialized.

See Also:

createPoolLogger()

getResourcePoolStatistics

public ResourcePoolStatistics getResourcePoolStatistics()

Copy pool statistics into a structure and return. This call delegates to the pool logger which was created an registered with the pool when the pool was initialized.

See Also:

createPoolLogger()

getSyncLock

public java.lang.Object getSyncLock()

INTERNAL USE ONLY. Applications should not use this method.

createResource

protected java.lang.Object createResource(java.util.Properties properties)

Create a new pooled resource. This method assumes that storage has already been allocated in the pool by invoking allocateResource().

Applications should not use or override this method. In order to specify how a resource is created applications should implement instantiateResource(Properties).

See Also:

instantiateResource(Properties)

getAvailableResourceCount

public int getAvailableResourceCount()

Get the number of available resources in the resource pool.

destroy

protected void destroy()

Detroy the resource pool.

removeResources

public java.util.ArrayList removeResources()

Remove all resources from the resource pool.

markResourcesForRemove

public void markResourcesForRemove()

Mark all resources in the pool for removal.

addResource

public void addResource(java.lang.Object resource)

Add a resource to the resource pool.

addToRemoveList

public void addToRemoveList(java.lang.Object resource)

canFinalizeResource

protected boolean canFinalizeResource(java.lang.Object resource)

Invoked by removeResource to determine if the resource can be removed from the pool by the current thread. If not the resource will be added to the deferred removal list.

This method may be customized to prevent the eager deferral of a resource. For example, the ApplicationPool will return false if the ApplicationModule is still referenced.

Invoked inside of the pool monitor.

canAllocateResource

protected boolean canAllocateResource(java.lang.Object resource)

Invoked by allocateResource to determine that an existing resource can be allocated to the invoker. Only available resources will be allocated. When an existing resource is allocated it is set as unavailable. It is assumed that the thread that allocated the resource will then use that resource.

canRemoveResource

protected boolean canRemoveResource(java.lang.Object resource)

Invoked from gc() to ensure that the specified resource may be removed from the ResourcePool.

removeResourceInternal

protected boolean removeResourceInternal(java.lang.Object resource)

removeResource

public java.lang.Object removeResource(java.lang.Object resource)

Remove a resource from the pool.

wakeup

public void wakeup()

Wakeup the resource pool. This method is invoked routinely by the resource pool monitor thread. The method may be implemented to perform routine pool maintenance like checking the pool high water mark.

removeFromManager

protected boolean removeFromManager()

getResourcePoolKey

protected abstract java.lang.Object getResourcePoolKey()

seekLRUAvailableResource

protected java.lang.Object seekLRUAvailableResource(java.lang.Object refResource)

Return the least recently used available resource in the pool.

Applications should not use this method.

Parameters:

refResource - if not null returns the resource that was less recently used than the reference resource.

seekMRUAvailableResource

protected java.lang.Object seekMRUAvailableResource(java.lang.Object refResource)

Return the most recently used available resource in the pool.

Applications should not use this method.

Parameters:

refResource - if not null returns the resource that was more recently used than the reference resource.

getTimeToCreateMillis

protected long getTimeToCreateMillis(java.lang.Object resource)

Return the time (ms) required to create the resource.

getCreationTimeMillis

protected long getCreationTimeMillis(java.lang.Object resource)

Return the time (ms) at which the resource was created.

isAvailable

protected boolean isAvailable(java.lang.Object resource)

INTERNAL USE ONLY. Applications should not use this method.

setAvailable

protected void setAvailable(java.lang.Object resource)

INTERNAL USE ONLY. Applications should not use this method.

getState

protected byte getState(java.lang.Object resource)

setState

protected boolean setState(java.lang.Object resource,
                           byte state,
                           java.util.Properties props)

resourceStateChanged

protected void resourceStateChanged(java.lang.Object resource,
                                    byte state,
                                    byte oldState)

Invoked during setState. Subclasses may customize this method to update internal data structures upon state transistion.

This block is executed while a pool monitor is held. Subclasses should be careful not to perform expensive operations.

setAvailable

protected void setAvailable(java.lang.Object resource,
                            boolean isAvailable)

INTERNAL USE ONLY. Applications should not use this method.

prepareResource

protected void prepareResource(java.lang.Object resource,
                               java.util.Properties props)

Invoked immediately before a resource is referenced. This block is unsynchronized. Subclassing pools may override this method to perform logic that prepares the resource for use.

This block will be executed while the resource latch is held. So, the block will have exclusive access to the resource.

The properties object represents the context that was passed to the request that resulted in the resource state transition.

finalizeResource

protected void finalizeResource(java.lang.Object resource,
                                java.lang.Object details)

Invoked during pool high water mark resolution. May be used to clean up resource state before the resource is removed from the pool.

allocateResource

protected java.lang.Object allocateResource()

Allocate storage for a new resource. This method is invoked by useResource(Properties) if it is necessary to create a new resource in the pool.

If the pool size equals the specified maximum pool size then the current thread will wait for the specified request timeout period for a resource to become available in the pool or for the pool size to be decreased via a remove resource invocation.

INTERNAL USE ONLY. Applications should not use this method.

getResourceDetails

protected java.lang.Object getResourceDetails(java.lang.Object resource)

This method is invoked for every removal candidate when the pool high water mark is reached. It provides subclassing pools an opportunity to provide more information about the target resource. This information is stored and passed back to the subclassing pool when finalizeResource is invoked.

beforeResourceFinalized

protected void beforeResourceFinalized(java.lang.Object resource)

This method is invoked immediately before resource finalization. This method represents the last point of consistency for the internal data structures that are maintained by the pool for this resource.

This method is invoked from within the pool monitor. Applications should be careful not to perform I/O from this method.

instantiateResource

public abstract java.lang.Object instantiateResource(java.util.Properties properties)

Instantiate a new pooled resource. Invoked by useResource(Properties) if it is necessary to create a new pooled resource. Applications should implement this method to return a new instance of a pooled resource.

getResource

protected java.lang.Object getResource(int index)

getMinAvailableSize

protected int getMinAvailableSize()

Return the minimum number of available instances that should exist in the pool after pool garbage collection. Pool garbage collection will remove inactive, available resources until there are no inactive, available resources to be removed or until the minimum available pool size has been reached.

An available resource is defined as inactive if it has not been used for a duration longer than the pool's maximum inactive age.

See Also:

getMaxInactiveAge()

getMaxAvailableSize

protected int getMaxAvailableSize()

Return the maximum number of available instances that should exist in the pool after pool garbage collection. Pool garbage collection will remove available resources until there are no available resources to be removed or until the maximum available pool size has been reached.

getMaxInactiveAge

protected int getMaxInactiveAge()

Return the duration in milliseconds that a resource may remain available before it is considered inactive. Inactive resources are always removed from the pool until the pool minimum available size has been reached.

See Also:

getMinAvailableSize()

getTimeToLive

protected int getTimeToLive()

Return the duration in milliseconds that a resource may remain in the pool.

getInitPoolSize

protected int getInitPoolSize()

Return get initial pool size.

getMaxPoolSize

protected int getMaxPoolSize()

Return the maximum pool size.

See Also:

allocateResource()

getMaxWaitTime

protected long getMaxWaitTime()

Return the maximum amount of time in milliseconds that a request should wait for an available pool resource.

See Also:

getMaxPoolSize(), allocateResource()

isUseExclusive

protected boolean isUseExclusive()

Determines if poooled resources are used serially. If true then only available resources will be returned by useResource. If false then useResource will return references to the 0 through maximum number of resources in round-robin fashion.

For example, assume that the pool maximum size is 5. If requests one through 5 acquire references to resources one through five respectively and in that order. If serial use is enabled then request six will wait until one of the other five resources released back to the pool. If serial use is not enabled then request six will acquire a reference to resource one. Continuing with the example, request seven would then acquire a reference to resource two.

See Also:

useResource(Properties)

createPoolLogger

protected ResourcePoolLogger createPoolLogger()

getResourceInfo

protected ResourceInfo getResourceInfo(java.lang.Object resource)

Return the resource details object. Throws an invalid resource exception if the specified resource does not belong to this pool.

prepareForGCRemove

protected void prepareForGCRemove(java.util.ArrayList resources,
                                  java.lang.Object resource)