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 used in an
22 * {@link ObjectPool ObjectPool}.
23 * <p>
24 * By contract, when an {@link ObjectPool ObjectPool}
25 * delegates to a <tt>PoolableObjectFactory</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 ObjectPool
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 PoolableObjectFactory {
63 /***
64 * Creates an instance that can be returned by the pool.
65 * @return an instance that can be returned by the pool.
66 */
67 Object makeObject() throws Exception;
68
69 /***
70 * Destroys an instance no longer needed by the pool.
71 * @param obj the instance to be destroyed
72 */
73 void destroyObject(Object obj) throws Exception;
74
75 /***
76 * Ensures that the instance is safe to be returned by the pool.
77 * Returns <tt>false</tt> if this object should be destroyed.
78 * @param obj the instance to be validated
79 * @return <tt>false</tt> if this <i>obj</i> is not valid and should
80 * be dropped from the pool, <tt>true</tt> otherwise.
81 */
82 boolean validateObject(Object obj);
83
84 /***
85 * Reinitialize an instance to be returned by the pool.
86 * @param obj the instance to be activated
87 */
88 void activateObject(Object obj) throws Exception;
89
90 /***
91 * Uninitialize an instance to be returned to the pool.
92 * @param obj the instance to be passivated
93 */
94 void passivateObject(Object obj) throws Exception;
95 }