1
2
3
4
5
6
7
8
9
10
11
12
13
14
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: 155430 $ $Date: 2005-02-26 08:13:28 -0500 (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 makeObject(Object key) throws Exception;
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 key, Object obj) throws Exception;
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 key, Object 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 key, Object obj) throws Exception;
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 key, Object obj) throws Exception;
100 }