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: 791676 $ $Date: 2009-07-06 22:29:56 -0400 (Mon, 06 Jul 2009) $
72   * @since Pool 1.0
73   */
74  public interface KeyedPoolableObjectFactory {
75      /**
76       * Create an instance that can be served by the pool.
77       *
78       * @param key the key used when constructing the object
79       * @return an instance that can be served by the pool.
80       * @throws Exception if there is a problem creating a new instance,
81       *    this will be propagated to the code requesting an object.
82       */
83      Object makeObject(Object key) throws Exception;
84  
85      /**
86       * Destroy an instance no longer needed by the pool.
87       * <p>
88       * It is important for implementations of this method to be aware
89       * that there is no guarantee about what state <code>obj</code>
90       * will be in and the implementation should be prepared to handle
91       * unexpected errors.
92       * </p>
93       * <p>
94       * Also, an implementation must take in to consideration that
95       * instances lost to the garbage collector may never be destroyed.
96       * </p>
97       *
98       * @param key the key used when selecting the instance
99       * @param obj the instance to be destroyed
100      * @throws Exception should be avoided as it may be swallowed by
101      *    the pool implementation.
102      * @see #validateObject
103      * @see KeyedObjectPool#invalidateObject
104      */
105     void destroyObject(Object key, Object obj) throws Exception;
106 
107     /**
108      * Ensures that the instance is safe to be returned by the pool.
109      * Returns <code>false</code> if <code>obj</code> should be destroyed.
110      *
111      * @param key the key used when selecting the object
112      * @param obj the instance to be validated
113      * @return <code>false</code> if <code>obj</code> is not valid and should
114      *         be dropped from the pool, <code>true</code> otherwise.
115      */
116     boolean validateObject(Object key, Object obj);
117 
118     /**
119      * Reinitialize an instance to be returned by the pool.
120      *
121      * @param key the key used when selecting the object
122      * @param obj the instance to be activated
123      * @throws Exception if there is a problem activating <code>obj</code>,
124      *    this exception may be swallowed by the pool.
125      * @see #destroyObject
126      */
127     void activateObject(Object key, Object obj) throws Exception;
128 
129     /**
130      * Uninitialize an instance to be returned to the idle object pool.
131      *
132      * @param key the key used when selecting the object
133      * @param obj the instance to be passivated
134      * @throws Exception if there is a problem passivating <code>obj</code>,
135      *    this exception may be swallowed by the pool.
136      * @see #destroyObject
137      */
138     void passivateObject(Object key, Object obj) throws Exception;
139 }