View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.pool;
19  
20  /***
21   * An interface defining life-cycle methods for
22   * instances to be served by a {@link KeyedObjectPool}.
23   * <p>
24   * By contract, when an {@link KeyedObjectPool}
25   * delegates to a {@link KeyedPoolableObjectFactory},
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 that has been
34   *   {@link #passivateObject passivated} before it is
35   *   {@link KeyedObjectPool#borrowObject borrowed} from the pool.
36   *  </li>
37   *  <li>
38   *   {@link #validateObject validateObject}
39   *   is invoked on {@link #activateObject activated} instances to make sure
40   *   they can be {@link KeyedObjectPool#borrowObject borrowed} from the pool.
41   *   <code>validateObject</code> <strong>may</strong> also be used to test an
42   *   instance being {@link KeyedObjectPool#returnObject returned} to the pool
43   *   before it is {@link #passivateObject passivated}. It will only be invoked
44   *   on an activated instance.
45   *  </li>
46   *  <li>
47   *   {@link #passivateObject passivateObject}
48   *   is invoked on every instance when it is returned to the pool.
49   *  </li>
50   *  <li>
51   *   {@link #destroyObject destroyObject}
52   *   is invoked on every instance when it is being "dropped" from the
53   *   pool (whether due to the response from <code>validateObject</code>,
54   *   or for reasons specific to the pool implementation.) There is no
55   *   guarantee that the instance being destroyed will
56   *   be considered active, passive or in a generally consistent state.
57   *  </li>
58   * </ol>
59   * </p>
60   * <p>
61   * {@link KeyedPoolableObjectFactory} must be thread-safe. The only promise
62   * an {@link KeyedObjectPool} makes is that the same instance of an object will not
63   * be passed to more than one method of a <code>KeyedPoolableObjectFactory</code>
64   * at a time.
65   * </p>
66   *
67   * @see KeyedObjectPool
68   * 
69   * @author Rodney Waldhoff
70   * @author Sandy McArthur
71   * @version $Revision: 480413 $ $Date: 2006-11-28 22:16:05 -0700 (Tue, 28 Nov 2006) $
72   * @since Pool 1.0
73   */
74  public interface KeyedPoolableObjectFactory {
75      /***
76       * Create an instance that can be served by the pool.
77       * Instances returned from this method should be in the
78       * same state as if they had been
79       * {@link #activateObject activated}. They will not be
80       * activated before being served by the pool.
81       *
82       * @param key the key used when constructing the object
83       * @return an instance that can be served by the pool.
84       * @throws Exception if there is a problem creating a new instance,
85       *    this will be propagated to the code requesting an object.
86       */
87      Object makeObject(Object key) throws Exception;
88  
89      /***
90       * Destroy an instance no longer needed by the pool.
91       * <p>
92       * It is important for implementations of this method to be aware
93       * that there is no guarantee about what state <code>obj</code>
94       * will be in and the implementation should be prepared to handle
95       * unexpected errors.
96       * </p>
97       * <p>
98       * Also, an implementation must take in to consideration that
99       * instances lost to the garbage collector may never be destroyed.
100      * </p>
101      *
102      * @param key the key used when selecting the instance
103      * @param obj the instance to be destroyed
104      * @throws Exception should be avoided as it may be swallowed by
105      *    the pool implementation.
106      * @see #validateObject
107      * @see KeyedObjectPool#invalidateObject
108      */
109     void destroyObject(Object key, Object obj) throws Exception;
110 
111     /***
112      * Ensures that the instance is safe to be returned by the pool.
113      * Returns <code>false</code> if <code>obj</code> should be destroyed.
114      *
115      * @param key the key used when selecting the object
116      * @param obj the instance to be validated
117      * @return <code>false</code> if <code>obj</code> is not valid and should
118      *         be dropped from the pool, <code>true</code> otherwise.
119      */
120     boolean validateObject(Object key, Object obj);
121 
122     /***
123      * Reinitialize an instance to be returned by the pool.
124      *
125      * @param key the key used when selecting the object
126      * @param obj the instance to be activated
127      * @throws Exception if there is a problem activating <code>obj</code>,
128      *    this exception may be swallowed by the pool.
129      * @see #destroyObject
130      */
131     void activateObject(Object key, Object obj) throws Exception;
132 
133     /***
134      * Uninitialize an instance to be returned to the idle object pool.
135      *
136      * @param key the key used when selecting the object
137      * @param obj the instance to be passivated
138      * @throws Exception if there is a problem passivating <code>obj</code>,
139      *    this exception may be swallowed by the pool.
140      * @see #destroyObject
141      */
142     void passivateObject(Object key, Object obj) throws Exception;
143 }