01: /*
02: * Copyright 1999-2004 The Apache Software Foundation.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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 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: }
|