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: 892236 $ $Date: 2013-12-31 04:43:12 +0000 (Tue, 31 Dec 2013) $
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    }