View Javadoc

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: 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 }