001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.pool2; 018 019import java.io.PrintWriter; 020import java.time.Duration; 021import java.time.Instant; 022import java.util.Deque; 023 024/** 025 * Defines the wrapper that is used to track the additional information, such as 026 * state, for the pooled objects. 027 * <p> 028 * Implementations of this class are required to be thread-safe. 029 * </p> 030 * 031 * @param <T> the type of object in the pool 032 * 033 * @since 2.0 034 */ 035public interface PooledObject<T> extends Comparable<PooledObject<T>> { 036 037 /** 038 * Allocates the object. 039 * 040 * @return {@code true} if the original state was {@link PooledObjectState#IDLE IDLE} 041 */ 042 boolean allocate(); 043 044 /** 045 * Orders instances based on idle time - i.e. the length of time since the 046 * instance was returned to the pool. Used by the GKOP idle object evictor. 047 *<p> 048 * Note: This class has a natural ordering that is inconsistent with 049 * equals if distinct objects have the same identity hash code. 050 * </p> 051 * <p> 052 * {@inheritDoc} 053 * </p> 054 */ 055 @Override 056 int compareTo(PooledObject<T> other); 057 058 /** 059 * Deallocates the object and sets it {@link PooledObjectState#IDLE IDLE} 060 * if it is currently {@link PooledObjectState#ALLOCATED ALLOCATED}. 061 * 062 * @return {@code true} if the state was {@link PooledObjectState#ALLOCATED ALLOCATED}. 063 */ 064 boolean deallocate(); 065 066 /** 067 * Notifies the object that the eviction test has ended. 068 * 069 * @param idleQueue The queue of idle objects to which the object should be 070 * returned. 071 * 072 * @return Currently not used. 073 */ 074 boolean endEvictionTest(Deque<PooledObject<T>> idleQueue); 075 076 @Override 077 boolean equals(Object obj); 078 079 /** 080 * Gets the amount of time this object last spent in the active state (it may still be active in which case 081 * subsequent calls will return an increased value). 082 * 083 * @return The duration last spent in the active state. 084 * @since 2.11.0 085 */ 086 default Duration getActiveDuration() { 087 // Take copies to avoid threading issues 088 final Instant lastReturnInstant = getLastReturnInstant(); 089 final Instant lastBorrowInstant = getLastBorrowInstant(); 090 // @formatter:off 091 return lastReturnInstant.isAfter(lastBorrowInstant) ? 092 Duration.between(lastBorrowInstant, lastReturnInstant) : 093 Duration.between(lastBorrowInstant, Instant.now()); 094 // @formatter:on 095 } 096 097 /** 098 * Gets the amount of time this object last spent in the active state (it may still be active in which case 099 * subsequent calls will return an increased value). 100 * 101 * @return The duration last spent in the active state. 102 * @since 2.10.0 103 * @deprecated Use {@link #getActiveDuration()}. 104 */ 105 @Deprecated 106 default Duration getActiveTime() { 107 return getActiveDuration(); 108 } 109 110 /** 111 * Gets the amount of time in milliseconds this object last spent in the 112 * active state (it may still be active in which case subsequent calls will 113 * return an increased value). 114 * 115 * @return The time in milliseconds last spent in the active state. 116 * @deprecated Use {@link #getActiveTime()} which offers the best precision. 117 */ 118 @Deprecated 119 long getActiveTimeMillis(); 120 121 /** 122 * Gets the number of times this object has been borrowed. 123 * 124 * @return -1 by default for implementations prior to release 2.7.0. 125 * @since 2.7.0 126 */ 127 default long getBorrowedCount() { 128 return -1; 129 } 130 131 /** 132 * Gets the time (using the same basis as {@link Instant#now()}) that this object was created. 133 * 134 * @return The creation time for the wrapped object. 135 * @since 2.11.0 136 */ 137 default Instant getCreateInstant() { 138 return Instant.ofEpochMilli(getCreateTime()); 139 } 140 141 /** 142 * Gets the time (using the same basis as 143 * {@link System#currentTimeMillis()}) that this object was created. 144 * 145 * @return The creation time for the wrapped object. 146 * @deprecated Use {@link #getCreateInstant()} which offers the best precision. 147 */ 148 @Deprecated 149 long getCreateTime(); 150 151 /** 152 * Gets the amount of time that this object last spend in the 153 * idle state (it may still be idle in which case subsequent calls will 154 * return an increased value). 155 * 156 * @return The amount of time in last spent in the idle state. 157 * @since 2.11.0 158 */ 159 default Duration getIdleDuration() { 160 return Duration.ofMillis(getIdleTimeMillis()); 161 } 162 163 /** 164 * Gets the amount of time that this object last spend in the 165 * idle state (it may still be idle in which case subsequent calls will 166 * return an increased value). 167 * 168 * @return The amount of time in last spent in the idle state. 169 * @since 2.10.0 170 * @deprecated Use {@link #getIdleDuration()}. 171 */ 172 @Deprecated 173 default Duration getIdleTime() { 174 return Duration.ofMillis(getIdleTimeMillis()); 175 } 176 177 /** 178 * Gets the amount of time in milliseconds that this object last spend in the 179 * idle state (it may still be idle in which case subsequent calls will 180 * return an increased value). 181 * 182 * @return The time in milliseconds last spent in the idle state. 183 * @deprecated Use {@link #getIdleTime()} which offers the best precision. 184 */ 185 @Deprecated 186 long getIdleTimeMillis(); 187 188 /** 189 * Gets the time the wrapped object was last borrowed. 190 * 191 * @return The time the object was last borrowed. 192 * @since 2.11.0 193 */ 194 default Instant getLastBorrowInstant() { 195 return Instant.ofEpochMilli(getLastBorrowTime()); 196 } 197 198 /** 199 * Gets the time the wrapped object was last borrowed. 200 * 201 * @return The time the object was last borrowed. 202 * @deprecated Use {@link #getLastBorrowInstant()} which offers the best precision. 203 */ 204 @Deprecated 205 long getLastBorrowTime(); 206 207 /** 208 * Gets the time the wrapped object was last borrowed. 209 * 210 * @return The time the object was last borrowed. 211 * @since 2.11.0 212 */ 213 default Instant getLastReturnInstant() { 214 return Instant.ofEpochMilli(getLastReturnTime()); 215 } 216 217 /** 218 * Gets the time the wrapped object was last returned. 219 * 220 * @return The time the object was last returned. 221 * @deprecated Use {@link #getLastReturnInstant()} which offers the best precision. 222 */ 223 @Deprecated 224 long getLastReturnTime(); 225 226 /** 227 * Gets an estimate of the last time this object was used. If the class of the pooled object implements 228 * {@link TrackedUse}, what is returned is the maximum of {@link TrackedUse#getLastUsedInstant()} and 229 * {@link #getLastBorrowTime()}; otherwise this method gives the same value as {@link #getLastBorrowTime()}. 230 * 231 * @return the last time this object was used 232 * @since 2.11.0 233 */ 234 default Instant getLastUsedInstant() { 235 return Instant.ofEpochMilli(getLastUsedTime()); 236 } 237 238 /** 239 * Gets an estimate of the last time this object was used. If the class 240 * of the pooled object implements {@link TrackedUse}, what is returned is 241 * the maximum of {@link TrackedUse#getLastUsedInstant()} and 242 * {@link #getLastBorrowTime()}; otherwise this method gives the same 243 * value as {@link #getLastBorrowTime()}. 244 * 245 * @return the last time this object was used. 246 * @deprecated Use {@link #getLastUsedInstant()} which offers the best precision. 247 */ 248 @Deprecated 249 long getLastUsedTime(); 250 251 /** 252 * Gets the underlying object that is wrapped by this instance of 253 * {@link PooledObject}. 254 * 255 * @return The wrapped object. 256 */ 257 T getObject(); 258 259 /** 260 * Gets the state of this object. 261 * @return state 262 */ 263 PooledObjectState getState(); 264 265 @Override 266 int hashCode(); 267 268 /** 269 * Sets the state to {@link PooledObjectState#INVALID INVALID}. 270 */ 271 void invalidate(); 272 273 /** 274 * Marks the pooled object as abandoned. 275 */ 276 void markAbandoned(); 277 278 /** 279 * Marks the object as returning to the pool. 280 */ 281 void markReturning(); 282 283 /** 284 * Prints the stack trace of the code that borrowed this pooled object and 285 * the stack trace of the last code to use this object (if available) to 286 * the supplied writer. 287 * 288 * @param writer The destination for the debug output. 289 */ 290 void printStackTrace(PrintWriter writer); 291 292 /** 293 * Sets whether to use abandoned object tracking. If this is true the 294 * implementation will need to record the stack trace of the last caller to 295 * borrow this object. 296 * 297 * @param logAbandoned The new configuration setting for abandoned 298 * object tracking. 299 */ 300 void setLogAbandoned(boolean logAbandoned); 301 302 /** 303 * Sets the stack trace generation strategy based on whether or not fully detailed stack traces are required. 304 * When set to false, abandoned logs may only include caller class information rather than method names, line 305 * numbers, and other normal metadata available in a full stack trace. 306 * 307 * @param requireFullStackTrace the new configuration setting for abandoned object logging. 308 * @since 2.7.0 309 */ 310 default void setRequireFullStackTrace(final boolean requireFullStackTrace) { 311 // noop 312 } 313 314 /** 315 * Attempts to place the pooled object in the 316 * {@link PooledObjectState#EVICTION} state. 317 * 318 * @return {@code true} if the object was placed in the 319 * {@link PooledObjectState#EVICTION} state otherwise 320 * {@code false}. 321 */ 322 boolean startEvictionTest(); 323 324 /** 325 * Gets a String form of the wrapper for debug purposes. The format is 326 * not fixed and may change at any time. 327 * 328 * {@inheritDoc} 329 */ 330 @Override 331 String toString(); 332 333 /** 334 * Records the current stack trace as the last time the object was used. 335 */ 336 void use(); 337 338}