PoolableObjectFactory


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 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$ $Date: 2005-02-26 05:13:28 -0800 (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  }
96
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags