BaseObjectPool (Apache Tomcat 11.0.21 API Documentation)
Description: declaration: package: org.apache.tomcat.dbcp.pool2, class: BaseObjectPool

# Class BaseObjectPool<T>

java.lang.Object
org.apache.tomcat.dbcp.pool2.BaseObject
org.apache.tomcat.dbcp.pool2.BaseObjectPool<T>

Type Parameters:
  `T` - Type of element pooled in this pool.

All Implemented Interfaces:
  `Closeable, AutoCloseable, ObjectPool<T>`

Direct Known Subclasses:
  `SoftReferenceObjectPool`

public abstract class BaseObjectPool<T> extends BaseObject implements ObjectPool<T>
A simple base implementation of `ObjectPool`. Optional operations are implemented to either do nothing, return a value indicating it is unsupported or throw `UnsupportedOperationException`.

This class is intended to be thread-safe.

Since:
  2.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BaseObjectPool()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addObject()`
  Not supported in this base implementation.
  `protected final void`
  `assertOpen()`
  Throws an `IllegalStateException` when this pool has been closed.
  `abstract T`
  `borrowObject()`
  Borrows an instance from this pool.
  `void`
  `clear()`
  Not supported in this base implementation.
  `void`
  `close()`
  Closes this pool, and free any resources associated with it.
  `int`
  `getNumActive()`
  Not supported in this base implementation.
  `int`
  `getNumIdle()`
  Not supported in this base implementation.
  `abstract void`
  `invalidateObject(T obj)`
  Invalidates an object from the pool.
  `final boolean`
  `isClosed()`
  Has this pool instance been closed.
  `abstract void`
  `returnObject(T obj)`
  Returns an instance to the pool.
  `protected void`
  `toStringAppendFields(StringBuilder builder)`
  Used by sub-classes to include the fields defined by the sub-class in the `BaseObject.toString()` output.

  ### Methods inherited from class BaseObject

  `toString`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface ObjectPool

  `addObjects, invalidateObject`

- ## Constructor Details

  - ### BaseObjectPool

    public BaseObjectPool()
    Constructs a new instance.

- ## Method Details

  - ### addObject

    public void addObject() throws Exception
    Not supported in this base implementation. Subclasses should override this behavior.
    Specified by:
      `addObject` in interface `ObjectPool<T>`
    Throws:
      `UnsupportedOperationException` - if the pool does not implement this method
      `Exception` - when `PooledObjectFactory.makeObject()` fails.

  - ### assertOpen

    protected final void assertOpen() throws IllegalStateException
    Throws an `IllegalStateException` when this pool has been closed.
    Throws:
      `IllegalStateException` - when this pool has been closed.
    See Also:
      - `isClosed()`

  - ### borrowObject

    public abstract T borrowObject() throws Exception
    Description copied from interface: `ObjectPool`
    Borrows an instance from this pool.

    Instances returned from this method will have been either newly created with `PooledObjectFactory.makeObject()` or will be a previously idle object and have been activated with `PooledObjectFactory.activateObject(PooledObject)` and then validated with `PooledObjectFactory.validateObject(PooledObject)`.

    By contract, clients must return the borrowed instance using `ObjectPool.returnObject(T)`, `ObjectPool.invalidateObject(T)`, or a related method as defined in an implementation or sub-interface.

    The behavior of this method when the pool has been exhausted is not strictly specified (although it may be specified by implementations).

    Specified by:
      `borrowObject` in interface `ObjectPool<T>`
    Returns:
      an instance from this pool.
    Throws:
      `Exception` - when `PooledObjectFactory.makeObject()` throws an exception.

  - ### clear

    public void clear() throws Exception
    Not supported in this base implementation.
    Specified by:
      `clear` in interface `ObjectPool<T>`
    Throws:
      `UnsupportedOperationException` - if the pool does not implement this method
      `Exception` - if the pool cannot be cleared

  - ### close

    public void close()
    Closes this pool, and free any resources associated with it.

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

    Implementations should silently fail if not all resources can be freed.

    This affects the behavior of `isClosed` and `assertOpen`.

    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Specified by:
      `close` in interface `ObjectPool<T>`

  - ### getNumActive

    public int getNumActive()
    Not supported in this base implementation.
    Specified by:
      `getNumActive` in interface `ObjectPool<T>`
    Returns:
      a negative value.

  - ### getNumIdle

    public int getNumIdle()
    Not supported in this base implementation.
    Specified by:
      `getNumIdle` in interface `ObjectPool<T>`
    Returns:
      a negative value.

  - ### invalidateObject

    public abstract void invalidateObject(T obj) throws Exception
    Description copied from interface: `ObjectPool`
    Invalidates an object from the pool.

    By contract, `obj` must have been obtained using `ObjectPool.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.

    Specified by:
      `invalidateObject` in interface `ObjectPool<T>`
    Parameters:
      `obj` - a `borrowed` instance to be disposed.
    Throws:
      `Exception` - if the instance cannot be invalidated

  - ### isClosed

    public final boolean isClosed()
    Has this pool instance been closed.
    Returns:
      `true` when this pool has been closed.

  - ### returnObject

    public abstract void returnObject(T obj) throws Exception
    Description copied from interface: `ObjectPool`
    Returns an instance to the pool. By contract, `obj` must have been obtained using `ObjectPool.borrowObject()` or a related method as defined in an implementation or sub-interface.
    Specified by:
      `returnObject` in interface `ObjectPool<T>`
    Parameters:
      `obj` - a `borrowed` instance to be returned.
    Throws:
      `Exception` - if an instance cannot be returned to the pool

  - ### toStringAppendFields

    protected void toStringAppendFields(StringBuilder builder)
    Description copied from class: `BaseObject`
    Used by sub-classes to include the fields defined by the sub-class in the `BaseObject.toString()` output.
    Overrides:
      `toStringAppendFields` in class `BaseObject`
    Parameters:
      `builder` - Field names and values are appended to this object