ObjectPool.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.pool2;

  19. import java.io.Closeable;
  20. import java.util.NoSuchElementException;

  22. /**
  23.  * A pooling simple interface.
  24.  * <p>
  25.  * Example of use:
  26.  * </p>
  27.  * <pre style="border:solid thin; padding: 1ex;"
  28.  * > Object obj = <code style="color:#00C">null</code>;
  29.  *
  30.  * <code style="color:#00C">try</code> {
  31.  *     obj = pool.borrowObject();
  32.  *     <code style="color:#00C">try</code> {
  33.  *         <code style="color:#0C0">//...use the object...</code>
  34.  *     } <code style="color:#00C">catch</code> (Exception e) {
  35.  *         <code style="color:#0C0">// invalidate the object</code>
  36.  *         pool.invalidateObject(obj);
  37.  *         <code style="color:#0C0">// do not return the object to the pool twice</code>
  38.  *         obj = <code style="color:#00C">null</code>;
  39.  *     } <code style="color:#00C">finally</code> {
  40.  *         <code style="color:#0C0">// make sure the object is returned to the pool</code>
  41.  *         <code style="color:#00C">if</code> (<code style="color:#00C">null</code> != obj) {
  42.  *             pool.returnObject(obj);
  43.  *        }
  44.  *     }
  45.  * } <code style="color:#00C">catch</code>(Exception e) {
  46.  *       <code style="color:#0C0">// failed to borrow an object</code>
  47.  * }</pre>
  48.  * <p>
  49.  * See {@link BaseObjectPool} for a simple base implementation.
  50.  * </p>
  51.  *
  52.  * @param <T> Type of element pooled in this pool.
  53.  *
  54.  *
  55.  * @see PooledObjectFactory
  56.  * @see KeyedObjectPool
  57.  * @see BaseObjectPool
  58.  * @since 2.0
  59.  */
  60. public interface ObjectPool<T> extends Closeable {

  62.     /**
  63.      * Creates an object using the {@link PooledObjectFactory factory} or other
  64.      * implementation dependent mechanism, passivate it, and then place it in
  65.      * the idle object pool. {@code addObject} is useful for "pre-loading"
  66.      * a pool with idle objects. (Optional operation).
  67.      *
  68.      * @throws Exception
  69.      *              when {@link PooledObjectFactory#makeObject} fails.
  70.      * @throws IllegalStateException
  71.      *              after {@link #close} has been called on this pool.
  72.      * @throws UnsupportedOperationException
  73.      *              when this pool cannot add new idle objects.
  74.      */
  75.     void addObject() throws Exception;

  77.     /**
  78.      * Calls {@link ObjectPool#addObject()} {@code count}
  79.      * number of times.
  80.      *
  81.      * @param count
  82.      *            the number of idle objects to add.
  83.      * @throws Exception See {@link ObjectPool#addObject()}.
  84.      * @since 2.8.0
  85.      */
  86.     default void addObjects(final int count) throws Exception {
  87.         for (int i = 0; i < count; i++) {
  88.             addObject();
  89.         }
  90.     }

  92.     /**
  93.      * Borrows an instance from this pool.
  94.      * <p>
  95.      * Instances returned from this method will have been either newly created
  96.      * with {@link PooledObjectFactory#makeObject} or will be a previously
  97.      * idle object and have been activated with
  98.      * {@link PooledObjectFactory#activateObject} and then validated with
  99.      * {@link PooledObjectFactory#validateObject}.
  100.      * </p>
  101.      * <p>
  102.      * By contract, clients <strong>must</strong> return the borrowed instance
  103.      * using {@link #returnObject}, {@link #invalidateObject}, or a related
  104.      * method as defined in an implementation or sub-interface.
  105.      * </p>
  106.      * <p>
  107.      * The behavior of this method when the pool has been exhausted
  108.      * is not strictly specified (although it may be specified by
  109.      * implementations).
  110.      * </p>
  111.      *
  112.      * @return an instance from this pool.
  113.      * @throws IllegalStateException
  114.      *              after {@link #close close} has been called on this pool.
  115.      * @throws Exception
  116.      *              when {@link PooledObjectFactory#makeObject} throws an
  117.      *              exception.
  118.      * @throws NoSuchElementException
  119.      *              when the pool is exhausted and cannot or will not return
  120.      *              another instance.
  121.      */
  122.     T borrowObject() throws Exception;

  124.     /**
  125.      * Clears any objects sitting idle in the pool, releasing any associated
  126.      * resources (optional operation). Idle objects cleared must be
  127.      * {@link PooledObjectFactory#destroyObject(PooledObject)}.
  128.      *
  129.      * @throws UnsupportedOperationException
  130.      *              if this implementation does not support the operation
  131.      *
  132.      * @throws Exception if the pool cannot be cleared
  133.      */
  134.     void clear() throws Exception;

  136.     /**
  137.      * Closes this pool, and free any resources associated with it.
  138.      * <p>
  139.      * Calling {@link #addObject} or {@link #borrowObject} after invoking this
  140.      * method on a pool will cause them to throw an {@link IllegalStateException}.
  141.      * </p>
  142.      * <p>
  143.      * Implementations should silently fail if not all resources can be freed.
  144.      * </p>
  145.      */
  146.     @Override
  147.     void close();

  149.     /**
  150.      * Gets the number of instances currently borrowed from this pool. Returns
  151.      * a negative value if this information is not available.
  152.      * @return the number of instances currently borrowed from this pool.
  153.      */
  154.     int getNumActive();

  156.     /**
  157.      * Gets the number of instances currently idle in this pool. This may be
  158.      * considered an approximation of the number of objects that can be
  159.      * {@link #borrowObject borrowed} without creating any new instances.
  160.      * Returns a negative value if this information is not available.
  161.      * @return the number of instances currently idle in this pool.
  162.      */
  163.     int getNumIdle();

  165.     /**
  166.      * Invalidates an object from the pool.
  167.      * <p>
  168.      * By contract, {@code obj} <strong>must</strong> have been obtained
  169.      * using {@link #borrowObject} or a related method as defined in an
  170.      * implementation or sub-interface.
  171.      * </p>
  172.      * <p>
  173.      * This method should be used when an object that has been borrowed is
  174.      * determined (due to an exception or other problem) to be invalid.
  175.      * </p>
  176.      *
  177.      * @param obj a {@link #borrowObject borrowed} instance to be disposed.
  178.      * @throws Exception if the instance cannot be invalidated
  179.      */
  180.     void invalidateObject(T obj) throws Exception;

  182.     /**
  183.      * Invalidates an object from the pool, using the provided
  184.      * {@link DestroyMode}
  185.      * <p>
  186.      * By contract, {@code obj} <strong>must</strong> have been obtained
  187.      * using {@link #borrowObject} or a related method as defined in an
  188.      * implementation or sub-interface.
  189.      * </p>
  190.      * <p>
  191.      * This method should be used when an object that has been borrowed is
  192.      * determined (due to an exception or other problem) to be invalid.
  193.      * </p>
  194.      *
  195.      * @param obj a {@link #borrowObject borrowed} instance to be disposed.
  196.      * @param destroyMode destroy activation context provided to the factory
  197.      * @throws Exception if the instance cannot be invalidated
  198.      * @since 2.9.0
  199.      */
  200.     default void invalidateObject(final T obj, final DestroyMode destroyMode) throws Exception {
  201.         invalidateObject(obj);
  202.     }

  204.     /**
  205.      * Returns an instance to the pool. By contract, {@code obj}
  206.      * <strong>must</strong> have been obtained using {@link #borrowObject()} or
  207.      * a related method as defined in an implementation or sub-interface.
  208.      *
  209.      * @param obj a {@link #borrowObject borrowed} instance to be returned.
  210.      * @throws IllegalStateException
  211.      *              if an attempt is made to return an object to the pool that
  212.      *              is in any state other than allocated (i.e. borrowed).
  213.      *              Attempting to return an object more than once or attempting
  214.      *              to return an object that was never borrowed from the pool
  215.      *              will trigger this exception.
  216.      *
  217.      * @throws Exception if an instance cannot be returned to the pool
  218.      */
  219.     void returnObject(T obj) throws Exception;

  221. }
Created with JaCoCo 0.8.12.202403310830