001: /*
002: * Copyright 1999-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.commons.pool;
018:
019: /**
020: * An interface defining life-cycle methods for
021: * instances to be served by a
022: * {@link KeyedObjectPool KeyedObjectPool}.
023: * <p>
024: * By contract, when an {@link KeyedObjectPool KeyedObjectPool}
025: * delegates to a <tt>KeyedPoolableObjectFactory</tt>,
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 before it is returned from the
034: * pool.
035: * </li>
036: * <li>
037: * {@link #passivateObject passivateObject}
038: * is invoked on every instance when it is returned to the
039: * pool.
040: * </li>
041: * <li>
042: * {@link #destroyObject destroyObject}
043: * is invoked on every instance when it is being "dropped" from the
044: * pool (whether due to the response from
045: * {@link #validateObject validateObject}, or
046: * for reasons specific to the pool implementation.)
047: * </li>
048: * <li>
049: * {@link #validateObject validateObject}
050: * is invoked in an implementation-specific fashion to determine if an instance
051: * is still valid to be returned by the pool.
052: * It will only be invoked on an {@link #activateObject "activated"}
053: * instance.
054: * </li>
055: * </ol>
056: *
057: * @see KeyedObjectPool
058: *
059: * @author Rodney Waldhoff
060: * @version $Revision: 155430 $ $Date: 2005-02-26 08:13:28 -0500 (Sat, 26 Feb 2005) $
061: */
062: public interface KeyedPoolableObjectFactory {
063: /**
064: * Create an instance that can be served by the pool.
065: * @param key the key used when constructing the object
066: * @return an instance that can be served by the pool.
067: */
068: Object makeObject(Object key) throws Exception;
069:
070: /**
071: * Destroy an instance no longer needed by the pool.
072: * @param key the key used when selecting the instance
073: * @param obj the instance to be destroyed
074: */
075: void destroyObject(Object key, Object obj) throws Exception;
076:
077: /**
078: * Ensures that the instance is safe to be returned by the pool.
079: * Returns <tt>false</tt> if this instance should be destroyed.
080: * @param key the key used when selecting the object
081: * @param obj the instance to be validated
082: * @return <tt>false</tt> if this <i>obj</i> is not valid and should
083: * be dropped from the pool, <tt>true</tt> otherwise.
084: */
085: boolean validateObject(Object key, Object obj);
086:
087: /**
088: * Reinitialize an instance to be returned by the pool.
089: * @param key the key used when selecting the object
090: * @param obj the instance to be activated
091: */
092: void activateObject(Object key, Object obj) throws Exception;
093:
094: /**
095: * Uninitialize an instance to be returned to the pool.
096: * @param key the key used when selecting the object
097: * @param obj the instance to be passivated
098: */
099: void passivateObject(Object key, Object obj) throws Exception;
100: }
|