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
018package 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: 892236 $ $Date: 2013-12-31 04:43:12 +0000 (Tue, 31 Dec 2013) $
075 * @since Pool 1.0
076 */
077public 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}