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 module hunt.pool.PooledObjectFactory; 18 19 import hunt.pool.PooledObject; 20 21 /** 22 * An interface defining life-cycle methods for instances to be served by an 23 * {@link ObjectPool}. 24 * <p> 25 * By contract, when an {@link ObjectPool} delegates to a 26 * {@link PooledObjectFactory}, 27 * </p> 28 * <ol> 29 * <li> 30 * {@link #makeObject} is called whenever a new instance is needed. 31 * </li> 32 * <li> 33 * {@link #activateObject} is invoked on every instance that has been 34 * {@link #passivateObject passivated} before it is 35 * {@link ObjectPool#borrowObject borrowed} from the pool. 36 * </li> 37 * <li> 38 * {@link #validateObject} may be invoked on {@link #activateObject activated} 39 * instances to make sure they can be {@link ObjectPool#borrowObject borrowed} 40 * from the pool. {@link #validateObject} may also be used to 41 * test an instance being {@link ObjectPool#returnObject returned} to the pool 42 * before it is {@link #passivateObject passivated}. It will only be invoked 43 * on an activated instance. 44 * </li> 45 * <li> 46 * {@link #passivateObject} is invoked on every instance when it is returned 47 * to the pool. 48 * </li> 49 * <li> 50 * {@link #destroyObject} is invoked on every instance when it is being 51 * "dropped" from the pool (whether due to the response from 52 * {@link #validateObject}, or for reasons specific to the pool 53 * implementation.) There is no guarantee that the instance being destroyed 54 * will be considered active, passive or in a generally consistent state. 55 * </li> 56 * </ol> 57 * {@link PooledObjectFactory} must be thread-safe. The only promise 58 * an {@link ObjectPool} makes is that the same instance of an object will not 59 * be passed to more than one method of a <code>PoolableObjectFactory</code> 60 * at a time. 61 * <p> 62 * While clients of a {@link KeyedObjectPool} borrow and return instances of 63 * the underlying value type {@code V}, the factory methods act on instances of 64 * {@link PooledObject PooledObject<V>}. These are the object wrappers that 65 * pools use to track and maintain state information about the objects that 66 * they manage. 67 * </p> 68 * 69 * @param <T> Type of element managed in this factory. 70 * 71 * @see ObjectPool 72 * 73 */ 74 interface PooledObjectFactory(T) { 75 76 /** 77 * Creates an instance that can be served by the pool and wrap it in a 78 * {@link PooledObject} to be managed by the pool. 79 * 80 * @return a {@code PooledObject} wrapping an instance that can be served by the pool 81 * 82 * @throws Exception if there is a problem creating a new instance, 83 * this will be propagated to the code requesting an object. 84 */ 85 IPooledObject makeObject(); 86 87 /** 88 * Destroys an instance no longer needed by the pool. 89 * <p> 90 * It is important for implementations of this method to be aware that there 91 * is no guarantee about what state <code>obj</code> will be in and the 92 * implementation should be prepared to handle unexpected errors. 93 * </p> 94 * <p> 95 * Also, an implementation must take in to consideration that instances lost 96 * to the garbage collector may never be destroyed. 97 * </p> 98 * 99 * @param p a {@code PooledObject} wrapping the instance to be destroyed 100 * 101 * @throws Exception should be avoided as it may be swallowed by 102 * the pool implementation. 103 * 104 * @see #validateObject 105 * @see ObjectPool#invalidateObject 106 */ 107 void destroyObject(IPooledObject p); 108 109 /** 110 * Ensures that the instance is safe to be returned by the pool. 111 * 112 * @param p a {@code PooledObject} wrapping the instance to be validated 113 * 114 * @return <code>false</code> if <code>obj</code> is not valid and should 115 * be dropped from the pool, <code>true</code> otherwise. 116 */ 117 bool validateObject(IPooledObject p); 118 119 /** 120 * Reinitializes an instance to be returned by the pool. 121 * 122 * @param p a {@code PooledObject} wrapping the instance to be activated 123 * 124 * @throws Exception if there is a problem activating <code>obj</code>, 125 * this exception may be swallowed by the pool. 126 * 127 * @see #destroyObject 128 */ 129 void activateObject(IPooledObject p); 130 131 /** 132 * Uninitializes an instance to be returned to the idle object pool. 133 * 134 * @param p a {@code PooledObject} wrapping the instance to be passivated 135 * 136 * @throws Exception if there is a problem passivating <code>obj</code>, 137 * this exception may be swallowed by the pool. 138 * 139 * @see #destroyObject 140 */ 141 void passivateObject(IPooledObject p); 142 }