    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017
    018    package org.apache.commons.pool;
    019
    020    /**
    021     * An interface defining life-cycle methods for
    022     * instances to be served by a {@link KeyedObjectPool}.
    023     * <p>
    024     * By contract, when an {@link KeyedObjectPool}
    025     * delegates to a {@link KeyedPoolableObjectFactory},
    026     * <ol>
    027     *  <li>
    028     *   {@link #makeObject makeObject}
    029     *   is called whenever a new instance is needed.
    030     *  </li>
    031     *  <li>
    032     *   {@link #activateObject activateObject}
    033     *   is invoked on every instance that has been
    034     *   {@link #passivateObject passivated} before it is
    035     *   {@link KeyedObjectPool#borrowObject borrowed} from the pool.
    036     *  </li>
    037     *  <li>
    038     *   {@link #validateObject validateObject}
    039     *   is invoked on {@link #activateObject activated} instances to make sure
    040     *   they can be {@link KeyedObjectPool#borrowObject borrowed} from the pool.
    041     *   <code>validateObject</code> <strong>may</strong> also be used to test an
    042     *   instance being {@link KeyedObjectPool#returnObject returned} to the pool
    043     *   before it is {@link #passivateObject passivated}. It will only be invoked
    044     *   on an activated instance.
    045     *  </li>
    046     *  <li>
    047     *   {@link #passivateObject passivateObject}
    048     *   is invoked on every instance when it is returned to the pool.
    049     *  </li>
    050     *  <li>
    051     *   {@link #destroyObject destroyObject}
    052     *   is invoked on every instance when it is being "dropped" from the
    053     *   pool (whether due to the response from <code>validateObject</code>,
    054     *   or for reasons specific to the pool implementation.) There is no
    055     *   guarantee that the instance being destroyed will
    056     *   be considered active, passive or in a generally consistent state.
    057     *  </li>
    058     * </ol>
    059     * </p>
    060     * <p>
    061     * {@link KeyedPoolableObjectFactory} must be thread-safe. The only promise
    062     * an {@link KeyedObjectPool} makes is that the same instance of an object will not
    063     * be passed to more than one method of a <code>KeyedPoolableObjectFactory</code>
    064     * at a time.
    065     * </p>
    066     *
    067     * @see KeyedObjectPool
    068     *
    069     * @author Rodney Waldhoff
    070     * @author Sandy McArthur
    071     * @version $Revision: 791676 $ $Date: 2009-07-06 19:29:56 -0700 (Mon, 06 Jul 2009) $
    072     * @since Pool 1.0
    073     */
    074    public interface KeyedPoolableObjectFactory {
    075        /**
    076         * Create an instance that can be served by the pool.
    077         *
    078         * @param key the key used when constructing the object
    079         * @return an instance that can be served by the pool.
    080         * @throws Exception if there is a problem creating a new instance,
    081         *    this will be propagated to the code requesting an object.
    082         */
    083        Object makeObject(Object key) throws Exception;
    084
    085        /**
    086         * Destroy an instance no longer needed by the pool.
    087         * <p>
    088         * It is important for implementations of this method to be aware
    089         * that there is no guarantee about what state <code>obj</code>
    090         * will be in and the implementation should be prepared to handle
    091         * unexpected errors.
    092         * </p>
    093         * <p>
    094         * Also, an implementation must take in to consideration that
    095         * instances lost to the garbage collector may never be destroyed.
    096         * </p>
    097         *
    098         * @param key the key used when selecting the instance
    099         * @param obj the instance to be destroyed
    100         * @throws Exception should be avoided as it may be swallowed by
    101         *    the pool implementation.
    102         * @see #validateObject
    103         * @see KeyedObjectPool#invalidateObject
    104         */
    105        void destroyObject(Object key, Object obj) throws Exception;
    106
    107        /**
    108         * Ensures that the instance is safe to be returned by the pool.
    109         * Returns <code>false</code> if <code>obj</code> should be destroyed.
    110         *
    111         * @param key the key used when selecting the object
    112         * @param obj the instance to be validated
    113         * @return <code>false</code> if <code>obj</code> is not valid and should
    114         *         be dropped from the pool, <code>true</code> otherwise.
    115         */
    116        boolean validateObject(Object key, Object obj);
    117
    118        /**
    119         * Reinitialize an instance to be returned by the pool.
    120         *
    121         * @param key the key used when selecting the object
    122         * @param obj the instance to be activated
    123         * @throws Exception if there is a problem activating <code>obj</code>,
    124         *    this exception may be swallowed by the pool.
    125         * @see #destroyObject
    126         */
    127        void activateObject(Object key, Object obj) throws Exception;
    128
    129        /**
    130         * Uninitialize an instance to be returned to the idle object pool.
    131         *
    132         * @param key the key used when selecting the object
    133         * @param obj the instance to be passivated
    134         * @throws Exception if there is a problem passivating <code>obj</code>,
    135         *    this exception may be swallowed by the pool.
    136         * @see #destroyObject
    137         */
    138        void passivateObject(Object key, Object obj) throws Exception;
    139    }