KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > pool > KeyedPoolableObjectFactory


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.apache.commons.pool;
18
19 /**
20  * An interface defining life-cycle methods for
21  * instances to be served by a
22  * {@link KeyedObjectPool KeyedObjectPool}.
23  * <p>
24  * By contract, when an {@link KeyedObjectPool KeyedObjectPool}
25  * delegates to a <tt>KeyedPoolableObjectFactory</tt>,
26  * <ol>
27  * <li>
28  * {@link #makeObject makeObject}
29  * is called whenever a new instance is needed.
30  * </li>
31  * <li>
32  * {@link #activateObject activateObject}
33  * is invoked on every instance before it is returned from the
34  * pool.
35  * </li>
36  * <li>
37  * {@link #passivateObject passivateObject}
38  * is invoked on every instance when it is returned to the
39  * pool.
40  * </li>
41  * <li>
42  * {@link #destroyObject destroyObject}
43  * is invoked on every instance when it is being "dropped" from the
44  * pool (whether due to the response from
45  * {@link #validateObject validateObject}, or
46  * for reasons specific to the pool implementation.)
47  * </li>
48  * <li>
49  * {@link #validateObject validateObject}
50  * is invoked in an implementation-specific fashion to determine if an instance
51  * is still valid to be returned by the pool.
52  * It will only be invoked on an {@link #activateObject "activated"}
53  * instance.
54  * </li>
55  * </ol>
56  *
57  * @see KeyedObjectPool
58  *
59  * @author Rodney Waldhoff
60  * @version $Revision$ $Date: 2005-02-26 05:13:28 -0800 (Sat, 26 Feb 2005) $
61  */
62 public interface KeyedPoolableObjectFactory {
63     /**
64      * Create an instance that can be served by the pool.
65      * @param key the key used when constructing the object
66      * @return an instance that can be served by the pool.
67      */
68     Object JavaDoc makeObject(Object JavaDoc key) throws Exception JavaDoc;
69
70     /**
71      * Destroy an instance no longer needed by the pool.
72      * @param key the key used when selecting the instance
73      * @param obj the instance to be destroyed
74      */
75     void destroyObject(Object JavaDoc key, Object JavaDoc obj) throws Exception JavaDoc;
76
77     /**
78      * Ensures that the instance is safe to be returned by the pool.
79      * Returns <tt>false</tt> if this instance should be destroyed.
80      * @param key the key used when selecting the object
81      * @param obj the instance to be validated
82      * @return <tt>false</tt> if this <i>obj</i> is not valid and should
83      * be dropped from the pool, <tt>true</tt> otherwise.
84      */
85     boolean validateObject(Object JavaDoc key, Object JavaDoc obj);
86
87     /**
88      * Reinitialize an instance to be returned by the pool.
89      * @param key the key used when selecting the object
90      * @param obj the instance to be activated
91      */
92     void activateObject(Object JavaDoc key, Object JavaDoc obj) throws Exception JavaDoc;
93
94     /**
95      * Uninitialize an instance to be returned to the pool.
96      * @param key the key used when selecting the object
97      * @param obj the instance to be passivated
98      */
99     void passivateObject(Object JavaDoc key, Object JavaDoc obj) throws Exception JavaDoc;
100 }
101
Popular Tags