org.jboss.minerva.pools
Class PoolObjectFactory

java.lang.Object
  |
  +--org.jboss.minerva.pools.PoolObjectFactory
Direct Known Subclasses:
JDBCConnectionFactory, XAConnectionFactory

public abstract class PoolObjectFactory
extends java.lang.Object

Creates objects to be used in an object pool. This is a class instead of an interface so you can ignore any of the methods you don't need.

Version:
$Revision: 1.4 $
Author:
Aaron Mulder (ammulder@alumni.princeton.edu)

Constructor Summary
PoolObjectFactory()
           
 
Method Summary
abstract  java.lang.Object createObject()
          Creates a new object to be stored in an object pool.
 void deleteObject(java.lang.Object pooledObject)
          Permanently closes an object, after it is removed from the pool.
 java.lang.Object isUniqueRequest()
          Decides whether a request for an object should be fulfilled by an object checked out of the pool previously, or a new object.
 void poolClosing(ObjectPool pool)
          Indicates to the factory that the pool is closing down.
 void poolStarted(ObjectPool pool, java.io.PrintWriter log)
          Indicates to the factory that the pool has started up.
 java.lang.Object prepareObject(java.lang.Object pooledObject)
          Prepares an object to be returned to the client.
 java.lang.Object returnObject(java.lang.Object clientObject)
          Prepares an object to be returned to the pool.
 java.lang.Object translateObject(java.lang.Object clientObject)
          If the objects supplied to the client are different than the objects in the pool, extracts a pool object from a client object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PoolObjectFactory

public PoolObjectFactory()
Method Detail

createObject

public abstract java.lang.Object createObject()
Creates a new object to be stored in an object pool. This is the instance that will actually be sotred in the pool and reused. If you want to wrap it somehow, or return instances of a different type that refers to these, you can implement prepareObject.
See Also:
prepareObject(java.lang.Object)

poolStarted

public void poolStarted(ObjectPool pool,
                        java.io.PrintWriter log)
Indicates to the factory that the pool has started up. This will be called before any other methods of the factory are called (on behalf of this pool).
Parameters:
pool - The pool that is starting. You may decide to allow multiple pools you use your factory, or to restrict it to a one-to-one relationship.
log - A writer you can use to log messages. Use this in preference to System.xxx.println.
Throws:
java.lang.IllegalArgumentException - Occurs when the pool is null.

prepareObject

public java.lang.Object prepareObject(java.lang.Object pooledObject)
Prepares an object to be returned to the client. This may be used to configure the object somehow, or actually return a completely different object (so long as the original can be recovered in translateObject or returnObject). This will be called whenever an object is returned to the client, whether a new object or a previously pooled object.
Parameters:
pooledObject - The object in the pool, as created by createObject.
Returns:
The object to return to the client. If different, the pooled object must be recoverable by translateObject and returnObject.

translateObject

public java.lang.Object translateObject(java.lang.Object clientObject)
If the objects supplied to the client are different than the objects in the pool, extracts a pool object from a client object. This should only be called between prepareObject and returnObject for any given pool object (and associated client object). However, it may be called once after an object has been released if the garbage collector and a client attempt to release an object at the same time. In this case, this method may work, return null, or throw an exception and the pool will handle it gracefully. The default implementation returns the parameter object (assumes client and pooled objects are the same).
Parameters:
clientObject - The client object, as returned by prepareObject
Returns:
The pooled object, as originally returned by createObject

returnObject

public java.lang.Object returnObject(java.lang.Object clientObject)
Prepares an object to be returned to the pool. Any cleanup or reset actions should be performed here. This also has the same effect as translateObject (only relevant if the pooled objects are different than the objects supplied to the client).
Parameters:
clientObject - The client object, as returned by prepareObject
Returns:
The pooled object, as originally returned by createObject, ready to be put back in the pool and reused.

poolClosing

public void poolClosing(ObjectPool pool)
Indicates to the factory that the pool is closing down. This will be called before all the instances are destroyed. There may be calls to returnObject or translateObject after this, but no calls to createObject or prepareObject (on behalf of this pool).
Parameters:
pool - The pool that is closing. You may decide to allow multiple pools you use your factory, or to restrict it to a one-to-one relationship.
Throws:
java.lang.IllegalArgumentException - Occurs when the pool is null.

deleteObject

public void deleteObject(java.lang.Object pooledObject)
Permanently closes an object, after it is removed from the pool. The object will not be returned to the pool - after this, it is gone. This is called when the pool shrinks, and when the pool is shut down.

isUniqueRequest

public java.lang.Object isUniqueRequest()
Decides whether a request for an object should be fulfilled by an object checked out of the pool previously, or a new object. In general, every request should generate a new object, so this should return null.
Returns:
An existing object, if this request is effectively the same as a previous request and the result should be shared. null if this is a unique request and should be fulfilled by a unique object.


Copyright © 2000 The jBoss Organization. All Rights Reserved.