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     * @param <K> the type of keys in this pool
068     * @param <V> the type of objects held in this pool
069     * 
070     * @see KeyedObjectPool
071     *
072     * @author Rodney Waldhoff
073     * @author Sandy McArthur
074     * @version $Revision: 1222388 $ $Date: 2011-12-22 13:28:27 -0500 (Thu, 22 Dec 2011) $
075     * @since Pool 1.0
076     */
077    public interface KeyedPoolableObjectFactory<K, V> {
078        /**
079         * Create an instance that can be served by the pool.
080         *
081         * @param key the key used when constructing the object
082         * @return an instance that can be served by the pool.
083         * @throws Exception if there is a problem creating a new instance,
084         *    this will be propagated to the code requesting an object.
085         */
086        V makeObject(K key) throws Exception;
087    
088        /**
089         * Destroy an instance no longer needed by the pool.
090         * <p>
091         * It is important for implementations of this method to be aware
092         * that there is no guarantee about what state <code>obj</code>
093         * will be in and the implementation should be prepared to handle
094         * unexpected errors.
095         * </p>
096         * <p>
097         * Also, an implementation must take in to consideration that
098         * instances lost to the garbage collector may never be destroyed.
099         * </p>
100         *
101         * @param key the key used when selecting the instance
102         * @param obj the instance to be destroyed
103         * @throws Exception should be avoided as it may be swallowed by
104         *    the pool implementation.
105         * @see #validateObject
106         * @see KeyedObjectPool#invalidateObject
107         */
108        void destroyObject(K key, V obj) throws Exception;
109    
110        /**
111         * Ensures that the instance is safe to be returned by the pool.
112         * Returns <code>false</code> if <code>obj</code> should be destroyed.
113         *
114         * @param key the key used when selecting the object
115         * @param obj the instance to be validated
116         * @return <code>false</code> if <code>obj</code> is not valid and should
117         *         be dropped from the pool, <code>true</code> otherwise.
118         */
119        boolean validateObject(K key, V obj);
120    
121        /**
122         * Reinitialize an instance to be returned by the pool.
123         *
124         * @param key the key used when selecting the object
125         * @param obj the instance to be activated
126         * @throws Exception if there is a problem activating <code>obj</code>,
127         *    this exception may be swallowed by the pool.
128         * @see #destroyObject
129         */
130        void activateObject(K key, V obj) throws Exception;
131    
132        /**
133         * Uninitialize an instance to be returned to the idle object pool.
134         *
135         * @param key the key used when selecting the object
136         * @param obj the instance to be passivated
137         * @throws Exception if there is a problem passivating <code>obj</code>,
138         *    this exception may be swallowed by the pool.
139         * @see #destroyObject
140         */
141        void passivateObject(K key, V obj) throws Exception;
142    }