com.metamatrix.common.pooling.api
Interface ResourcePoolMgr

All Known Implementing Classes:

ResourcePoolMgrImpl

public interface ResourcePoolMgr

The ResourcePoolMgr is the center point for managing and sharing a common object type among common users. The benefit of managing an object as a resource is so that common users can share the object without the overhead of reoccurring object creation, desctruction and cleanup. To utilize the resource pooling feature the following needs to be done:

1. Create ResourceType:
   the resource type categorically identifies the resource (e.g., JDBCConnectionResourceType). The resource type can provide defaults that will be applied to all the specific ResourceDescriptor implementations that are of that type. Therefore, there is a one-to-many relationship between the resource type and descriptor, respectfully.
2. Create ResourceDescriptor:/
   the descriptor describes the the resource and how it should be managed in the pool. The descriptor also represents the identifier the ResourcePoolMgr uses to identify each pool. The combination of the descriptor's name and ResourceType provides the unique identifier.
   • Create Resource:
     the resource is a wrapper class that will expose the necessary methods of the physical resource object. The resource should be implemented by extending BaseResource.
   • Create ResourceAdapter:
     the adpater will be used by the ResourcePool to create new resource object instances, as well as, close existing instances.

Once the appropriate set of classes have been implemented for a resource, the following are the steps for using a resource:

Instantiate the specific ResourceDescriptor and call getResource(com.metamatrix.common.config.api.ResourceDescriptor, java.lang.String) to obtain a resource instance from the pool.

When the user is finished with the resource, Resource.closeResource() method must be called in order to release the resource back to the pool for reuse.

Method Summary

java.util.Collection	getAllResourceDescriptorIDs() Call to get id's for all the current resource pools.
java.util.Collection	getAllResourceDescriptors() Call to get all the resource descriptors for the current pools.
Resource	getResource(ResourceDescriptor descriptor, java.lang.String userName) Call to get a resource from the pool defined by descriptor.
ResourceDescriptor	getResourceDescriptor(ResourceDescriptorID descriptorID) Call to get the resource descriptor for the specified id
java.util.Collection	getResourcePoolStatistics() Returns all the ResourcePoolStatistics currently active.
ResourcePoolStatistics	getResourcePoolStatistics(ResourceDescriptorID descriptorID) Returns the statistics for a specific resource descriptor id.
java.util.Collection	getResourcesStatisticsForPool(ResourceDescriptorID descriptorID) Returns all the ResourceStatistics for the pool.
void	shutDown() Call to shutdown all resource pools and all the resources within those pools.
void	shutDown(ResourceDescriptorID descriptorID) Call to shutdown all resources in the specific pool identified by the descriptor ID.
void	updateResourcePool(ResourceDescriptorID resourceDescriptorID, java.util.Properties properties) Call to update the pool management parameters based on the resource descriptor.

Method Detail

getResource

Resource getResource(ResourceDescriptor descriptor,
                     java.lang.String userName)
                     throws ResourcePoolException

Call to get a resource from the pool defined by descriptor.

Parameters:

descriptor - that describes the resource to obtain

userName - of the one requesting the resource

Returns:

Resource that is defined by the descriptor

Throws:

ResourcePoolException - is thrown if an error occurs. Check for type ResourceWaitTimeOutException

getAllResourceDescriptorIDs

java.util.Collection getAllResourceDescriptorIDs()
                                                 throws ResourcePoolException

Call to get id's for all the current resource pools.

Returns:

Collection of type ResourceDescriptorID for all the resource pools.

Throws:

ResourcePoolException - is thrown if an error occurs. Check for type ResourceWaitTimeOutException ResourceDescriptorID

getAllResourceDescriptors

java.util.Collection getAllResourceDescriptors()
                                               throws ResourcePoolException

Call to get all the resource descriptors for the current pools.

Returns:

Collection of type ResourceDescriptor for all the resource pools.

Throws:

ResourcePoolException - is thrown if an error occurs. ResourceDescriptor

getResourceDescriptor

ResourceDescriptor getResourceDescriptor(ResourceDescriptorID descriptorID)
                                         throws ResourcePoolException

Call to get the resource descriptor for the specified id

Parameters:

descriptorID - is the id that identifies the resource descriptor

Returns:

ResourceDescriptor identified by the id

Throws:

ResourcePoolException - is thrown if an error occurs.

updateResourcePool

void updateResourcePool(ResourceDescriptorID resourceDescriptorID,
                        java.util.Properties properties)
                        throws ResourcePoolException

Call to update the pool management parameters based on the resource descriptor. This could include changing the size of the pool.

Parameters:

resourceDescriptorID - identifies the pool to update

properties - are the changes to be applied

Throws:

ResourcePoolException - is thrown if an error occurs.

getResourcePoolStatistics

java.util.Collection getResourcePoolStatistics()
                                               throws ResourcePoolException

Returns all the ResourcePoolStatistics currently active. An empty collection will be returned if no resource pools are active.

Returns:

Collection of type ResourcePoolStatistics

Throws:

ResourcePoolException - is thrown if an error occurs.

getResourcesStatisticsForPool

java.util.Collection getResourcesStatisticsForPool(ResourceDescriptorID descriptorID)
                                                   throws ResourcePoolException

Returns all the ResourceStatistics for the pool. An empty collection will be returned if no resources exist in the pool.

Returns:

Collection of type ResourceStatistics

Throws:

ResourcePoolException - is thrown if an error occurs.

getResourcePoolStatistics

ResourcePoolStatistics getResourcePoolStatistics(ResourceDescriptorID descriptorID)
                                                 throws ResourcePoolException

Returns the statistics for a specific resource descriptor id. If the ResourcePool does not exist for the descriptorID, then a null will be returned.

Returns:

ResourcePoolStatistics for a specific resource pool; null if resource pool does not exit.

Throws:

ResourcePoolException - is thrown if an error occurs.

shutDown

void shutDown(ResourceDescriptorID descriptorID)
              throws ResourcePoolException

Call to shutdown all resources in the specific pool identified by the descriptor ID.

Parameters:

descriptorID - for the pool to be shutdown

Throws:

ResourcePoolException - is thrown if an error occurs.

shutDown

void shutDown()
              throws ResourcePoolException

Call to shutdown all resource pools and all the resources within those pools.

Throws:

ResourcePoolException