Oracle Fusion Middleware Java API Reference for Oracle ADF Model
11g Release 2 (11.1.2.0.0)

E17483-01

oracle.jbo.pool
Class ResourcePool

java.lang.Object
  extended by 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
           
static double MAX_WEIGHT_DEFAULT
           
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  double getMaxWeight()
          Returns the maximum weight allowed in the pool.
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  double getWeight(ResourceInfo resourceInfo)
          Calculates the weight of the resource.
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)
          Deprecated. 
protected  void prepareForGCRemove(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

MAX_WEIGHT_DEFAULT

public static final double MAX_WEIGHT_DEFAULT
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()

getMaxWeight

protected double getMaxWeight()
Returns the maximum weight allowed in the pool.

See Also:
QueryCollectionPool.getMaxWeight()

getWeight

protected double getWeight(ResourceInfo resourceInfo)
Calculates the weight of the resource.

Parameters:
resourceInfo - the resource to calculate
Returns:
the weight of the resource
See Also:
QueryCollectionPool.getWeight(ResourceInfo)

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

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


prepareForGCRemove

protected void prepareForGCRemove(java.lang.Object resource)

Oracle Fusion Middleware Java API Reference for Oracle ADF Model
11g Release 2 (11.1.2.0.0)

E17483-01

Copyright © 1997, 2011, Oracle. All rights reserved.