Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Application Development Framework Model and Business Components Java API Reference 10g Release 3 (10.1.3) B16005-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.jbo.pool
Class ResourcePool

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

Direct Known Subclasses:
  ApplicationPoolImpl

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` | `canFinalizeResource(java.lang.Object resource)` Invoked by removeResource to determine if the resource can be removed from the pool by the current thread.
`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)`
`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.
`protected void` | `prepareSharedResource(java.lang.Object resource, java.util.Properties props)` Invoked immediately before a shared resource is first 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)`
`com.sun.java.util.collections.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.

### removeResources

    public com.sun.java.util.collections.ArrayList removeResources()

  Remove all resources from the resource pool.

### 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.

### 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.

### prepareSharedResource

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

  Invoked immediately before a shared resource is first referenced. This block is unsynchronized. Subclassing pools may override this method to perform logic that prepare 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Application Development Framework Model and Business Components Java API Reference 10g Release 3 (10.1.3) B16005-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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