Apache Commons Pool 2.12.0 · org.apache.commons.pool2.impl.SoftReferenceObjectPool

Modifier and Type	Field and Description
private final ArrayList<PooledSoftReference<T>>	allReferences All references - checked out or waiting to be borrowed.
private long	createCount Total number of instances that have been created
private long	destroyCount Total number of instances that have been destroyed
private final PooledObjectFactory<T>	factory Factory to source pooled objects
private final LinkedBlockingDeque<PooledSoftReference<T>>	idleReferences Idle references - waiting to be borrowed
private int	numActive Count of instances that have been checkout out to pool clients
private final ReferenceQueue<T>	refQueue Queue of broken references that might be able to be removed from `_pool`.

Access	Constructor and Description
public	SoftReferenceObjectPool(final PooledObjectFactory<T> object factory to use. factory) Constructs a `SoftReferenceObjectPool` with the specified factory.

Method Summary

Modifier and Type	Method and Description
public synchronized void	addObject() Overrides org.apache.commons.pool2.BaseObjectPool.addObject. Implements org.apache.commons.pool2.ObjectPool.addObject. Creates an object, and places it into the pool.
public synchronized T	Returns: a valid, activated object instance borrowObject() Implements abstract org.apache.commons.pool2.BaseObjectPool.borrowObject. Implements org.apache.commons.pool2.ObjectPool.borrowObject. Borrows an object from the pool.
public synchronized void	clear() Overrides org.apache.commons.pool2.BaseObjectPool.clear. Implements org.apache.commons.pool2.ObjectPool.clear. Clears any objects sitting idle in the pool.
public void	close() Overrides org.apache.commons.pool2.BaseObjectPool.close. Implements org.apache.commons.pool2.ObjectPool.close. Closes this pool, and frees any resources associated with it.
private void	destroy(final PooledSoftReference<T> PooledSoftReference to destroy toDestroy) Destroys a `PooledSoftReference` and removes it from the idle and all references pools.
private PooledSoftReference<T>	Returns: PooledSoftReference wrapping a soft reference to obj findReference(final T returning object obj) Finds the PooledSoftReference in allReferences that points to obj.
public synchronized PooledObjectFactory<T>	Returns: the factory getFactory() Gets the `PooledObjectFactory` used by this pool to create and manage object instances.
public synchronized int	Returns: the number of instances currently borrowed from this pool getNumActive() Overrides org.apache.commons.pool2.BaseObjectPool.getNumActive. Implements org.apache.commons.pool2.ObjectPool.getNumActive. Gets the number of instances currently borrowed from this pool.
public synchronized int	Returns: estimated number of idle instances in the pool getNumIdle() Overrides org.apache.commons.pool2.BaseObjectPool.getNumIdle. Implements org.apache.commons.pool2.ObjectPool.getNumIdle. Gets an approximation not less than the of the number of idle instances in the pool.
public synchronized void	invalidateObject(final T a `borrowed` instance to be disposed. obj) Implements abstract org.apache.commons.pool2.BaseObjectPool.invalidateObject. Implements org.apache.commons.pool2.ObjectPool.invalidateObject. Invalidates an object from the pool.
private void	pruneClearedReferences() If any idle objects were garbage collected, remove their `Reference` wrappers from the idle object pool.
private void	removeClearedReferences(final Iterator<PooledSoftReference<T>> iterator over idle/allReferences iterator) Clears cleared references from iterator's collection
public synchronized void	returnObject(final T instance to return to the pool obj) Implements abstract org.apache.commons.pool2.BaseObjectPool.returnObject. Implements org.apache.commons.pool2.ObjectPool.returnObject. Returns an instance to the pool after successful validation and passivation.
protected void	toStringAppendFields(final StringBuilder Field names and values are appended to this object builder) Overrides org.apache.commons.pool2.BaseObjectPool.toStringAppendFields. Used by sub-classes to include the fields defined by the sub-class in the `toString()` output.

Inherited from org.apache.commons.pool2.BaseObjectPool:: assertOpen isClosed

allReferences	back to summary
private final ArrayList<PooledSoftReference<T>> allReferences All references - checked out or waiting to be borrowed.

createCount	back to summary
private long createCount Total number of instances that have been created

destroyCount	back to summary
private long destroyCount Total number of instances that have been destroyed

factory	back to summary
private final PooledObjectFactory<T> factory Factory to source pooled objects

idleReferences	back to summary
private final LinkedBlockingDeque<PooledSoftReference<T>> idleReferences Idle references - waiting to be borrowed

numActive	back to summary
private int numActive Count of instances that have been checkout out to pool clients

refQueue	back to summary
private final ReferenceQueue<T> refQueue Queue of broken references that might be able to be removed from `_pool`. This is used to help `getNumIdle()` be more accurate with minimal performance overhead.

SoftReferenceObjectPool	back to summary
public SoftReferenceObjectPool(final PooledObjectFactory<T> factory) Constructs a `SoftReferenceObjectPool` with the specified factory. Parameters factory:PooledObjectFactory<T> object factory to use.

Method Detail

addObject back to summary

addObject	back to summary
public synchronized void addObject() throws Exception Overrides org.apache.commons.pool2.BaseObjectPool.addObject. Implements org.apache.commons.pool2.ObjectPool.addObject. Creates an object, and places it into the pool. addObject() is useful for "pre-loading" a pool with idle objects. Before being added to the pool, the newly created instance is `validated` and `passivated`. If validation fails, the new instance is `destroyed`. Exceptions generated by the factory `makeObject` or `passivate` are propagated to the caller. Exceptions destroying instances are silently swallowed. Annotations @Override Exceptions Exception: when the `factory` has a problem creating or passivating an object. IllegalStateException: if invoked on a `closed` pool

public synchronized void addObject() throws Exception

Overrides org.apache.commons.pool2.BaseObjectPool.addObject.

Implements org.apache.commons.pool2.ObjectPool.addObject.

Creates an object, and places it into the pool. addObject() is useful for "pre-loading" a pool with idle objects.

Before being added to the pool, the newly created instance is validated and passivated. If validation fails, the new instance is destroyed. Exceptions generated by the factory makeObject or passivate are propagated to the caller. Exceptions destroying instances are silently swallowed.

Annotations

@Override

Exceptions

Exception:: when the factory has a problem creating or passivating an object.
IllegalStateException:: if invoked on a closed pool

borrowObject back to summary

borrowObject	back to summary
public synchronized T borrowObject() throws Exception Implements abstract org.apache.commons.pool2.BaseObjectPool.borrowObject. Implements org.apache.commons.pool2.ObjectPool.borrowObject. Borrows an object from the pool. If there are no idle instances available in the pool, the configured factory's `PooledObjectFactory#makeObject()` method is invoked to create a new instance. All instances are `activated` and `validated` before being returned by this method. If validation fails or an exception occurs activating or validating an idle instance, the failing instance is `destroyed` and another instance is retrieved from the pool, validated and activated. This process continues until either the pool is empty or an instance passes validation. If the pool is empty on activation or it does not contain any valid instances, the factory's `makeObject` method is used to create a new instance. If the created instance either raises an exception on activation or fails validation, `NoSuchElementException` is thrown. Exceptions thrown by `MakeObject` are propagated to the caller; but other than `ThreadDeath` or `VirtualMachineError`, exceptions generated by activation, validation or destroy methods are swallowed silently. Returns:T a valid, activated object instance Annotations @SuppressWarnings:null @Override Exceptions Exception: if an exception occurs creating a new instance NoSuchElementException: if a valid object cannot be provided IllegalStateException: if invoked on a `closed` pool

public synchronized T borrowObject() throws Exception

Implements abstract org.apache.commons.pool2.BaseObjectPool.borrowObject.

Implements org.apache.commons.pool2.ObjectPool.borrowObject.

Borrows an object from the pool. If there are no idle instances available in the pool, the configured factory's PooledObjectFactory#makeObject() method is invoked to create a new instance.

All instances are activated and validated before being returned by this method. If validation fails or an exception occurs activating or validating an idle instance, the failing instance is destroyed and another instance is retrieved from the pool, validated and activated. This process continues until either the pool is empty or an instance passes validation. If the pool is empty on activation or it does not contain any valid instances, the factory's makeObject method is used to create a new instance. If the created instance either raises an exception on activation or fails validation, NoSuchElementException is thrown. Exceptions thrown by MakeObject are propagated to the caller; but other than ThreadDeath or VirtualMachineError, exceptions generated by activation, validation or destroy methods are swallowed silently.

Returns:T

a valid, activated object instance

Annotations

@SuppressWarnings:null
@Override

Exceptions

Exception:: if an exception occurs creating a new instance
NoSuchElementException:: if a valid object cannot be provided
IllegalStateException:: if invoked on a closed pool

clear	back to summary
public synchronized void clear() Overrides org.apache.commons.pool2.BaseObjectPool.clear. Implements org.apache.commons.pool2.ObjectPool.clear. Clears any objects sitting idle in the pool. Annotations @Override

clear

back to summary

public synchronized void clear()

Overrides org.apache.commons.pool2.BaseObjectPool.clear.

Implements org.apache.commons.pool2.ObjectPool.clear.

Clears any objects sitting idle in the pool.

Annotations

@Override

close back to summary

close	back to summary
public void close() Overrides org.apache.commons.pool2.BaseObjectPool.close. Implements org.apache.commons.pool2.ObjectPool.close. Closes this pool, and frees any resources associated with it. Invokes `clear()` to destroy and remove instances in the pool. Calling `addObject` or `borrowObject` after invoking this method on a pool will cause them to throw an `IllegalStateException`. Annotations @Override

public void close()

Overrides org.apache.commons.pool2.BaseObjectPool.close.

Implements org.apache.commons.pool2.ObjectPool.close.

Closes this pool, and frees any resources associated with it. Invokes clear() to destroy and remove instances in the pool.

Calling addObject or borrowObject after invoking this method on a pool will cause them to throw an IllegalStateException.

Annotations

@Override

destroy back to summary

destroy	back to summary
private void destroy(final PooledSoftReference<T> toDestroy) throws Exception Destroys a `PooledSoftReference` and removes it from the idle and all references pools. Parameters toDestroy:PooledSoftReference<T> PooledSoftReference to destroy Exceptions Exception: If an error occurs while trying to destroy the object

private void destroy(final PooledSoftReference<T> toDestroy) throws Exception

Destroys a PooledSoftReference and removes it from the idle and all references pools.

Parameters

toDestroy:PooledSoftReference<T>: PooledSoftReference to destroy

Exceptions

Exception:: If an error occurs while trying to destroy the object

findReference	back to summary
private PooledSoftReference<T> findReference(final T obj) Finds the PooledSoftReference in allReferences that points to obj. Parameters obj:T returning object Returns:PooledSoftReference<T> PooledSoftReference wrapping a soft reference to obj

findReference

back to summary

private PooledSoftReference<T> findReference(final T obj)

Finds the PooledSoftReference in allReferences that points to obj.

Parameters

obj:T: returning object

Returns:PooledSoftReference<T>

PooledSoftReference wrapping a soft reference to obj

getFactory back to summary

getFactory	back to summary
public synchronized PooledObjectFactory<T> getFactory() Gets the `PooledObjectFactory` used by this pool to create and manage object instances. Returns:PooledObjectFactory<T> the factory

public synchronized PooledObjectFactory<T> getFactory()

Gets the PooledObjectFactory used by this pool to create and manage object instances.

Returns:PooledObjectFactory<T>: the factory

getNumActive	back to summary
public synchronized int getNumActive() Overrides org.apache.commons.pool2.BaseObjectPool.getNumActive. Implements org.apache.commons.pool2.ObjectPool.getNumActive. Gets the number of instances currently borrowed from this pool. Returns:int the number of instances currently borrowed from this pool Annotations @Override

getNumActive

back to summary

public synchronized int getNumActive()

Overrides org.apache.commons.pool2.BaseObjectPool.getNumActive.

Implements org.apache.commons.pool2.ObjectPool.getNumActive.

Gets the number of instances currently borrowed from this pool.

Returns:int

the number of instances currently borrowed from this pool

Annotations

@Override

getNumIdle	back to summary
public synchronized int getNumIdle() Overrides org.apache.commons.pool2.BaseObjectPool.getNumIdle. Implements org.apache.commons.pool2.ObjectPool.getNumIdle. Gets an approximation not less than the of the number of idle instances in the pool. Returns:int estimated number of idle instances in the pool Annotations @Override

getNumIdle

back to summary

public synchronized int getNumIdle()

Overrides org.apache.commons.pool2.BaseObjectPool.getNumIdle.

Implements org.apache.commons.pool2.ObjectPool.getNumIdle.

Gets an approximation not less than the of the number of idle instances in the pool.

Returns:int

estimated number of idle instances in the pool

Annotations

@Override

invalidateObject back to summary

invalidateObject	back to summary
public synchronized void invalidateObject(final T obj) throws Exception Implements abstract org.apache.commons.pool2.BaseObjectPool.invalidateObject. Implements org.apache.commons.pool2.ObjectPool.invalidateObject. Doc from org.apache.commons.pool2.ObjectPool.invalidateObject. Invalidates an object from the pool. By contract, `obj` must have been obtained using `borrowObject` or a related method as defined in an implementation or sub-interface. This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid. Parameters obj:T a `borrowed` instance to be disposed. Annotations @Override Exceptions Exception: if the instance cannot be invalidated

public synchronized void invalidateObject(final T obj) throws Exception

Implements abstract org.apache.commons.pool2.BaseObjectPool.invalidateObject.

Implements org.apache.commons.pool2.ObjectPool.invalidateObject.

Doc from org.apache.commons.pool2.ObjectPool.invalidateObject.

Invalidates an object from the pool.

By contract, obj must have been obtained using borrowObject or a related method as defined in an implementation or sub-interface.

This method should be used when an object that has been borrowed is determined (due to an exception or other problem) to be invalid.

Parameters

obj:T: a borrowed instance to be disposed.

Annotations

@Override

Exceptions

Exception:: if the instance cannot be invalidated

pruneClearedReferences	back to summary
private void pruneClearedReferences() If any idle objects were garbage collected, remove their `Reference` wrappers from the idle object pool.

removeClearedReferences	back to summary
private void removeClearedReferences(final Iterator<PooledSoftReference<T>> iterator) Clears cleared references from iterator's collection Parameters iterator:Iterator<PooledSoftReference<T>> iterator over idle/allReferences

removeClearedReferences

back to summary

private void removeClearedReferences(final Iterator<PooledSoftReference<T>> iterator)

Clears cleared references from iterator's collection

Parameters

iterator:Iterator<PooledSoftReference<T>>: iterator over idle/allReferences

returnObject back to summary

returnObject	back to summary
public synchronized void returnObject(final T obj) throws Exception Implements abstract org.apache.commons.pool2.BaseObjectPool.returnObject. Implements org.apache.commons.pool2.ObjectPool.returnObject. Returns an instance to the pool after successful validation and passivation. The returning instance is destroyed if any of the following are true: the pool is closed `validation` fails `passivation` throws an exception Exceptions passivating or destroying instances are silently swallowed. Exceptions validating instances are propagated to the client. Parameters obj:T instance to return to the pool Annotations @Override Exceptions Exception: Doc from org.apache.commons.pool2.ObjectPool.returnObject. if an instance cannot be returned to the pool IllegalArgumentException: if obj is not currently part of this pool

public synchronized void returnObject(final T obj) throws Exception

Implements abstract org.apache.commons.pool2.BaseObjectPool.returnObject.

Implements org.apache.commons.pool2.ObjectPool.returnObject.

Returns an instance to the pool after successful validation and passivation. The returning instance is destroyed if any of the following are true:

the pool is closed
validation fails
passivation throws an exception

Exceptions passivating or destroying instances are silently swallowed. Exceptions validating instances are propagated to the client.

Parameters

obj:T: instance to return to the pool

Annotations

@Override

Exceptions

Exception:

Doc from org.apache.commons.pool2.ObjectPool.returnObject.

if an instance cannot be returned to the pool

IllegalArgumentException:

if obj is not currently part of this pool

toStringAppendFields back to summary

toStringAppendFields	back to summary
protected void toStringAppendFields(final StringBuilder builder) Overrides org.apache.commons.pool2.BaseObjectPool.toStringAppendFields. Doc from org.apache.commons.pool2.BaseObject.toStringAppendFields. Used by sub-classes to include the fields defined by the sub-class in the `toString()` output. Parameters builder:StringBuilder Field names and values are appended to this object Annotations @Override

protected void toStringAppendFields(final StringBuilder builder)

Overrides org.apache.commons.pool2.BaseObjectPool.toStringAppendFields.

Doc from org.apache.commons.pool2.BaseObject.toStringAppendFields.

Used by sub-classes to include the fields defined by the sub-class in the toString() output.

Parameters

builder:StringBuilder: Field names and values are appended to this object

Annotations

@Override

public Class SoftReferenceObjectPool<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail