| java.lang.Object
 org.ofbiz.minerva.pool.ObjectPool
| ObjectPool | | public class ObjectPool implements PoolEventListener(Code) | | A generic object pool. You must provide a PoolObjectFactory (or the class
of a Java Bean) so the pool knows what kind of objects to create. It has
many configurable parameters, such as the minimum and maximum size of the
pool, whether to enable idle timeouts, etc. If the pooled objects
implement PooledObject, they will automatically be returned to the pool at
the appropriate times.
In general, the appropriate way to use a pool is:
- Create it
- Configure it (set factory, name, parameters, etc.)
- Initialize it (once done, further configuration is not allowed)
- Use it
- Shut it down
See Also: org.ofbiz.minerva.pool.PooledObject
author:
Aaron Mulder (ammulder@alumni.princeton.edu)
author:
danch (Dan Christopherson)
author:
Revision:
author:
20010701 danch added code for timeout in blocking. |
| Method Summary | |
| public void | fillToMin()
| | public int | getBlockingTimeout()
| | public long | getGCInterval()
Gets the length of time between garbage collection and idle timeout runs. | | public long | getGCMinIdleTime()
Gets the minimum idle time to make an object eligible for garbage
collection. | | public long | getIdleTimeout()
Gets the minimum idle time to release an unused object from the pool. | | public float | getMaxIdleTimeoutPercent()
Gets the idle timeout percent as a fraction between 0 and 1. | | public int | getMaxSize()
Gets the maximum size of the pool. | | public int | getMinSize()
Gets the minimum size of the pool. | | public String | getName()
Gets the name of the pool. | | long | getNextGCMillis(long now)
| | public Object | getObject()
Gets an object from the pool. | | public Object | getObject(Object parameters)
Gets an object that fits the specified parameters from the pool.
If all the objects in the pool are in use or don't fit, creates
a new object, adds it to the pool, and returns it. | | public void | initialize()
Prepares the pool for use. | | public boolean | isBlocking()
Gets whether a request for an object will block if the pool size is
maxed out and no objects are available. | | public boolean | isGCEnabled()
Gets whether garbage collection is enabled. | | public boolean | isIdleTimeoutEnabled()
Gets whether the pool releases instances that have not been used
recently. | | public boolean | isInvalidateOnError()
Gets whether objects are removed from the pool in case of errors. | | boolean | isTimeToGC()
| | public boolean | isTimestampUsed()
Gets whether object clients can update the last used time. | | public void | markObjectAsInvalid(Object object)
Indicates that an object is no longer valid, and should be removed from
the pool entirely. | | public void | objectClosed(PoolEvent evt)
If the object has been closed, release it. | | public void | objectError(PoolEvent evt)
If the invalidateOnError flag is set, the object will be removed from
the pool entirely when the client has finished with it. | | public void | objectUsed(PoolEvent evt)
If we're tracking the last used times, update the last used time for the
specified object. | | public void | releaseObject(Object object)
Returns an object to the pool. | | void | runGCandShrink()
| | public void | setBlocking(boolean blocking)
Sets whether a request for an object will block if the pool size is
maxed out and no objects are available. | | public void | setBlockingTimeout(int blockingTimeout)
sets how long to wait for a free object when blocking, -1 indicating
forever. | | public void | setGCEnabled(boolean enabled)
Sets whether garbage collection is enabled. | | public void | setGCInterval(long millis)
Sets the length of time between garbage collection and idle timeout runs.
This is inexact - if there are many pools with garbage collection and/or
the idle timeout enabled, there will not be a thread for each one, and
several nearby actions may be combined. | | public void | setGCMinIdleTime(long millis)
Sets the minimum idle time to make an object eligible for garbage
collection. | | public void | setIdleTimeout(long millis)
Sets the minimum idle time to release an unused object from the pool. | | public void | setIdleTimeoutEnabled(boolean enableTimeout)
Sets whether the pool should release instances that have not been used
recently. | | public void | setInvalidateOnError(boolean invalidate)
Sets the response for object errors. | | public void | setLastUsed(Object object)
Sets the last used time for an object in the pool that is currently
in use. | | public void | setMaxIdleTimeoutPercent(float percent)
Sets the idle timeout percent as a fraction between 0 and 1. | | public void | setMaxSize(int size)
Sets the maximum size of the pool. | | public void | setMinSize(int size)
Sets the minimum size of the pool. | | public void | setName(String name)
Sets the name of the pool. | | public void | setObjectFactory(PoolObjectFactory factory)
Sets the object factory for the pool. | | public void | setObjectFactory(Class javaBeanClass)
Sets the object factory as a new factory for Java Beans. | | public void | setTimestampUsed(boolean timestamp)
Sets whether object clients can update the last used time. | | public void | shutDown()
Shuts down the pool. | | public String | toString()
Returns the pool name and status. |
| ObjectPool | | public ObjectPool(PoolObjectFactory factory, String poolName)(Code) | | Creates a new pool with the specified parameters. It cannot be used
until you initialize it.
Parameters:
factory - The object factory that will create the objects to go inthe pool.
Parameters:
poolName - The name of the pool. This does not have to be uniqueacross all pools, but it is strongly recommended (and it may be arequirement for certain uses of the pool).
See Also: ObjectPool.initialize |
| ObjectPool | | public ObjectPool(Class javaBeanClass, String poolName)(Code) | | Creates a new pool with the specified parameters. It cannot be used
until you initialize it.
Parameters:
javaBeanClass - The Class of a Java Bean. New instances for thepool will be created with the no-argument constructor, and noparticular initialization or cleanup will be performed on theinstances. Use a PoolObjectFactory if you want more control overthe instances.
Parameters:
poolName - The name of the pool. This does not have to be uniqueacross all pools, but it is strongly recommended (and it may be arequirement for certain uses of the pool).
See Also: ObjectPool.initialize |
| fillToMin | | public void fillToMin()(Code) | | |
| getBlockingTimeout | | public int getBlockingTimeout()(Code) | | get how long this pool will wait for a free object while blocking
|
| getGCInterval | | public long getGCInterval()(Code) | | Gets the length of time between garbage collection and idle timeout runs.
See Also: ObjectPool.setGCInterval |
| getGCMinIdleTime | | public long getGCMinIdleTime()(Code) | | Gets the minimum idle time to make an object eligible for garbage
collection.
See Also: ObjectPool.setGCMinIdleTime |
| getName | | public String getName()(Code) | | Gets the name of the pool.
|
| getNextGCMillis | | long getNextGCMillis(long now)(Code) | | |
| getObject | | public Object getObject()(Code) | | Gets an object from the pool. If all the objects in the pool are in use,
creates a new object, adds it to the pool, and returns it. If all
objects are in use and the pool is at maximum size, will block or
return null.
See Also: ObjectPool.setBlocking |
| getObject | | public Object getObject(Object parameters)(Code) | | Gets an object that fits the specified parameters from the pool.
If all the objects in the pool are in use or don't fit, creates
a new object, adds it to the pool, and returns it. If all
objects are in use or don't fit and the pool is at maximum size,
will block or return null.
See Also: ObjectPool.setBlocking |
| initialize | | public void initialize()(Code) | | Prepares the pool for use. This must be called exactly once before
getObject is even called. The pool name and object factory must be set
before this call will succeed.
throws:
java.lang.IllegalStateException - Occurs when you try to initialize the pool without setting the objectfactory or name, or you initialize the pool more than once. |
| isBlocking | | public boolean isBlocking()(Code) | | Gets whether a request for an object will block if the pool size is
maxed out and no objects are available.
See Also: ObjectPool.setBlocking |
| isIdleTimeoutEnabled | | public boolean isIdleTimeoutEnabled()(Code) | | Gets whether the pool releases instances that have not been used
recently. This is different than garbage collection, which returns
instances to the pool if a client checked an instance out but has not
used it and not returned it to the pool.
See Also: ObjectPool.setIdleTimeoutEnabled |
| isInvalidateOnError | | public boolean isInvalidateOnError()(Code) | | Gets whether objects are removed from the pool in case of errors.
|
| isTimeToGC | | boolean isTimeToGC()(Code) | | |
| isTimestampUsed | | public boolean isTimestampUsed()(Code) | | Gets whether object clients can update the last used time.
|
| markObjectAsInvalid | | public void markObjectAsInvalid(Object object)(Code) | | Indicates that an object is no longer valid, and should be removed from
the pool entirely. This should be called before the object is returned
to the pool (specifically, before factory.returnObject returns), or else
the object may be given out again by the time this is called! Also, you
still need to actually return the object to the pool by calling
releaseObject, if you aren't calling this during that process already.
Parameters:
object - The object to invalidate, which must be the exact objectreturned by getObject |
| objectClosed | | public void objectClosed(PoolEvent evt)(Code) | | If the object has been closed, release it.
|
| objectError | | public void objectError(PoolEvent evt)(Code) | | If the invalidateOnError flag is set, the object will be removed from
the pool entirely when the client has finished with it.
|
| objectUsed | | public void objectUsed(PoolEvent evt)(Code) | | If we're tracking the last used times, update the last used time for the
specified object.
|
| releaseObject | | public void releaseObject(Object object)(Code) | | Returns an object to the pool. This must be the exact object that was
given out by getObject, and it must be returned to the same pool that
generated it. If other clients are blocked waiting on an object, the
object may be re-released immediately.
throws:
java.lang.IllegalArgumentException - Occurs when the object is not in this pool. |
| runGCandShrink | | void runGCandShrink()(Code) | | |
| setBlocking | | public void setBlocking(boolean blocking)(Code) | | Sets whether a request for an object will block if the pool size is
maxed out and no objects are available. If set to block, the request
will not return until an object is available. Otherwise, the request
will return null immediately (and may be retried). If multiple
requests block, there is no guarantee which will return first. The
default is to block.
throws:
java.lang.IllegalStateException - Occurs when you try to set the blocking parameter after thepool has been initialized. |
| setBlockingTimeout | | public void setBlockingTimeout(int blockingTimeout)(Code) | | sets how long to wait for a free object when blocking, -1 indicating
forever.
|
| setGCEnabled | | public void setGCEnabled(boolean enabled)(Code) | | Sets whether garbage collection is enabled. This is the process of
returning objects to the pool if they have been checked out of the pool
but have not been used in a long periond of time. This is meant to
reclaim resources, generally caused by unexpected failures on the part
of the pool client (which forestalled returning an object to the pool).
This runs on the same schedule as the idle timeout (if enabled), but
objects that were just garbage collected will not be eligible for the
idle timeout immediately (after all, they presumably represented "active"
clients). Objects that are garbage collected will be checked out again
immediately if a client is blocking waiting for an object. The default
value is disabled.
See Also: ObjectPool.setGCMinIdleTime
See Also: ObjectPool.setGCInterval
throws:
java.lang.IllegalStateException - Occurs when you try to set the garbage collection state after the poolhas been initialized. |
| setGCInterval | | public void setGCInterval(long millis)(Code) | | Sets the length of time between garbage collection and idle timeout runs.
This is inexact - if there are many pools with garbage collection and/or
the idle timeout enabled, there will not be a thread for each one, and
several nearby actions may be combined. Likewise if the collection
process is lengthy for certain types of pooled objects (not recommended),
other actions may be delayed. This is to prevend an unnecessary
proliferation of threads. Note that this parameter controls
both garbage collection and the idle timeout - and they will be performed
together if both are enabled. The deafult value is 2 minutes.
throws:
java.lang.IllegalStateException - Occurs when you try to set the garbage collection interval after thepool has been initialized. |
| setGCMinIdleTime | | public void setGCMinIdleTime(long millis)(Code) | | Sets the minimum idle time to make an object eligible for garbage
collection. If the object is in use and has not been used for this
amount of time, it may be returned to the pool. If timestamps are
enabled, the client may update the last used time (this is generally
recommended if garbage collection is enabled). Otherwise, the last used
time is only updated when an object is acquired or released. The default
value is 20 minutes.
See Also: ObjectPool.setGCEnabled
Parameters:
millis - The idle time, in milliseconds.
throws:
java.lang.IllegalStateException - Occurs when you try to set the garbage collection idle time after thepool has been initialized. |
| setIdleTimeout | | public void setIdleTimeout(long millis)(Code) | | Sets the minimum idle time to release an unused object from the pool. If
the object is not in use and has not been used for this amount of time,
it will be released from the pool. If timestamps are enabled, the client
may update the last used time. Otherwise, the last used time is only
updated when an object is acquired or released. The default value is
30 minutes.
See Also: ObjectPool.setIdleTimeoutEnabled
Parameters:
millis - The idle time, in milliseconds.
throws:
java.lang.IllegalStateException - Occurs when you try to set the idle timeout after the poolhas been initialized. |
| setIdleTimeoutEnabled | | public void setIdleTimeoutEnabled(boolean enableTimeout)(Code) | | Sets whether the pool should release instances that have not been used
recently. This is intended to reclaim resources (memory, database
connections, file handles, etc) during periods of inactivity. This runs
as often as garbage collection (even if garbage collection is disabled,
this uses the same timing parameter), but the required period of
inactivity is different. All objects that have been unused for more
than the idle timeout are closed, but if you set the MaxIdleShrinkPercent
parameter, the pool may recreate some objects so the total number of
pooled instances doesn't shrink as rapidly. Also, under no circumstances
will the number of pooled instances fall below the minimum size.
The default is disabled.
See Also: ObjectPool.setGCInterval
See Also: ObjectPool.setIdleTimeout
See Also: ObjectPool.setMaxIdleTimeoutPercent
See Also: ObjectPool.setMinSize
throws:
java.lang.IllegalStateException - Occurs when you try to set the idle timeout state after the pool hasbeen initialized. |
| setInvalidateOnError | | public void setInvalidateOnError(boolean invalidate)(Code) | | Sets the response for object errors. If this flag is set and an error
event occurs, the object is removed from the pool entirely. Otherwise,
the object is returned to the pool of available objects. For example, a
SQL error may not indicate a bad database connection (flag not set),
while a TCP/IP error probably indicates a bad network connection (flag
set). If this flag is not set, you can still manually invalidate
objects using markObjectAsInvalid.
See Also: ObjectPool.markObjectAsInvalid
See Also: ObjectPool.objectError |
| setMaxIdleTimeoutPercent | | public void setMaxIdleTimeoutPercent(float percent)(Code) | | Sets the idle timeout percent as a fraction between 0 and 1. If a number
of objects are determined to be idle, they will all be closed and
removed from the pool. However, if the ratio of objects released to
objects in the pool is greater than this fraction, some new objects
will be created to replace the closed objects. This prevents the pool
size from decreasing too rapidly. Set to 0 to decrease the pool size by
a maximum of 1 object per test, or 1 to never replace objects that have
exceeded the idle timeout. The pool will always replace enough closed
connections to stay at the minimum size.
See Also: ObjectPool.setIdleTimeoutEnabled
throws:
java.lang.IllegalStateException - Occurs when you try to set the idle timeout percent after the poolhas been initialized.
throws:
java.lang.IllegalArgumentException - Occurs when the percent parameter is not between 0 and 1. |
| setMaxSize | | public void setMaxSize(int size)(Code) | | Sets the maximum size of the pool. Once the pool has grown to hold this
number of instances, it will not add any more instances. If one of the
pooled instances is available when a request comes in, it will be
returned. If none of the pooled instances are available, the pool will
either block until an instance is available, or return null. The default
is no maximum size.
See Also: ObjectPool.setBlocking
Parameters:
size - The maximum size of the pool, or 0 if the pool should growindefinitely (not recommended).
throws:
java.lang.IllegalStateException - Occurs when you try to set the maximum size after the pool has beeninitialized. |
| setMinSize | | public void setMinSize(int size)(Code) | | Sets the minimum size of the pool. The pool will create this many
instances at startup, and once running, it will never shrink below this
size. The default is zero.
throws:
java.lang.IllegalStateException - Occurs when you try to set the minimum size after the pool has beeninitialized. |
| setName | | public void setName(String name)(Code) | | Sets the name of the pool. This is not required to be unique across all
pools, but is strongly recommended. Certain uses of the pool (such as
a JNDI object factory) may require it. This must be set exactly once
for each pool (it may be set in the constructor).
throws:
java.lang.IllegalStateException - Occurs when you try to set the name of the pool more than once. |
| setObjectFactory | | public void setObjectFactory(PoolObjectFactory factory)(Code) | | Sets the object factory for the pool. The object factory controls the
instances created for the pool, and can initialize instances given out
by the pool and cleanup instances returned to the pool.
throws:
java.lang.IllegalStateException - Occurs when you try to set the object factory after the pool has beeninitialized. |
| setObjectFactory | | public void setObjectFactory(Class javaBeanClass)(Code) | | Sets the object factory as a new factory for Java Beans. New instances
for the pool will be created with the no-argument constructor, and no
particular initialization or cleanup will be performed on the
instances.
throws:
java.lang.IllegalStateException - Occurs when you try to set the object factory after the pool has beeninitialized. |
| setTimestampUsed | | public void setTimestampUsed(boolean timestamp)(Code) | | Sets whether object clients can update the last used time. If not, the
last used time will only be updated when the object is given to a client
and returned to the pool. This time is important if the idle timeout or
garbage collection is enabled (particularly the latter). The default
is false.
throws:
java.lang.IllegalStateException - Occurs when you try to set the timestamp parameter after thepool has been initialized. |
| shutDown | | public void shutDown()(Code) | | Shuts down the pool. All outstanding objects are closed and all objects
are released from the pool. No getObject or releaseObject calls will
succeed after this method is called - and they will probably fail during
this method call.
|
| toString | | public String toString()(Code) | | Returns the pool name and status.
|
|
|