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 package org.apache.commons.pool2; 18 19 import java.io.PrintWriter; 20 import java.time.Duration; 21 import java.time.Instant; 22 import java.util.Deque; 23 24 /** 25 * Defines the wrapper that is used to track the additional information, such as 26 * state, for the pooled objects. 27 * <p> 28 * Implementations of this class are required to be thread-safe. 29 * </p> 30 * 31 * @param <T> the type of object in the pool. 32 * @since 2.0 33 */ 34 public interface PooledObject<T> extends Comparable<PooledObject<T>> { 35 36 /** 37 * Tests whether the given PooledObject is null <em>or</em> contains a null. 38 * 39 * @param pooledObject the PooledObject to test. 40 * @return whether the given PooledObject is null <em>or</em> contains a null. 41 * @since 2.12.0 42 */ 43 static boolean isNull(final PooledObject<?> pooledObject) { 44 return pooledObject == null || pooledObject.getObject() == null; 45 } 46 47 /** 48 * Allocates the object. 49 * 50 * @return {@code true} if the original state was {@link PooledObjectState#IDLE IDLE} 51 */ 52 boolean allocate(); 53 54 /** 55 * Orders instances based on idle time - i.e. the length of time since the 56 * instance was returned to the pool. Used by the GKOP idle object evictor. 57 * <p> 58 * Note: This class has a natural ordering that is inconsistent with 59 * equals if distinct objects have the same identity hash code. 60 * </p> 61 * <p> 62 * {@inheritDoc} 63 * </p> 64 */ 65 @Override 66 int compareTo(PooledObject<T> other); 67 68 /** 69 * Deallocates the object and sets it {@link PooledObjectState#IDLE IDLE} 70 * if it is currently {@link PooledObjectState#ALLOCATED ALLOCATED}. 71 * 72 * @return {@code true} if the state was {@link PooledObjectState#ALLOCATED ALLOCATED}. 73 */ 74 boolean deallocate(); 75 76 /** 77 * Notifies the object that the eviction test has ended. 78 * 79 * @param idleQueue The queue of idle objects to which the object should be 80 * returned. 81 * @return Currently not used. 82 */ 83 boolean endEvictionTest(Deque<PooledObject<T>> idleQueue); 84 85 @Override 86 boolean equals(Object obj); 87 88 /** 89 * Gets the amount of time this object last spent in the active state (it may still be active in which case 90 * subsequent calls will return an increased value). 91 * 92 * @return The duration last spent in the active state. 93 * @since 2.11.0 94 */ 95 default Duration getActiveDuration() { 96 // Take copies to avoid threading issues 97 final Instant lastReturnInstant = getLastReturnInstant(); 98 final Instant lastBorrowInstant = getLastBorrowInstant(); 99 // @formatter:off 100 return lastReturnInstant.isAfter(lastBorrowInstant) ? 101 Duration.between(lastBorrowInstant, lastReturnInstant) : 102 Duration.between(lastBorrowInstant, Instant.now()); 103 // @formatter:on 104 } 105 106 /** 107 * Gets the amount of time this object last spent in the active state (it may still be active in which case 108 * subsequent calls will return an increased value). 109 * 110 * @return The duration last spent in the active state. 111 * @since 2.10.0 112 * @deprecated Use {@link #getActiveDuration()}. 113 */ 114 @Deprecated 115 default Duration getActiveTime() { 116 return getActiveDuration(); 117 } 118 119 /** 120 * Gets the amount of time in milliseconds this object last spent in the 121 * active state (it may still be active in which case subsequent calls will 122 * return an increased value). 123 * 124 * @return The time in milliseconds last spent in the active state. 125 * @deprecated Use {@link #getActiveTime()} which offers the best precision. 126 */ 127 @Deprecated 128 long getActiveTimeMillis(); 129 130 /** 131 * Gets the number of times this object has been borrowed. 132 * 133 * @return -1 by default for implementations prior to release 2.7.0. 134 * @since 2.7.0 135 */ 136 default long getBorrowedCount() { 137 return -1; 138 } 139 140 /** 141 * Gets the time (using the same basis as {@link Instant#now()}) that this object was created. 142 * 143 * @return The creation time for the wrapped object. 144 * @since 2.11.0 145 */ 146 default Instant getCreateInstant() { 147 return Instant.ofEpochMilli(getCreateTime()); 148 } 149 150 /** 151 * Gets the time (using the same basis as 152 * {@link java.time.Clock#instant()}) that this object was created. 153 * 154 * @return The creation time for the wrapped object. 155 * @deprecated Use {@link #getCreateInstant()} which offers the best precision. 156 */ 157 @Deprecated 158 long getCreateTime(); 159 160 /** 161 * Gets the duration since this object was created (using {@link Instant#now()}). 162 * 163 * @return The duration since this object was created. 164 * @since 2.12.0 165 */ 166 default Duration getFullDuration() { 167 return Duration.between(getCreateInstant(), Instant.now()); 168 } 169 170 /** 171 * Gets the amount of time that this object last spend in the 172 * idle state (it may still be idle in which case subsequent calls will 173 * return an increased value). 174 * 175 * @return The amount of time in last spent in the idle state. 176 * @since 2.11.0 177 */ 178 default Duration getIdleDuration() { 179 return Duration.ofMillis(getIdleTimeMillis()); 180 } 181 182 /** 183 * Gets the amount of time that this object last spend in the 184 * idle state (it may still be idle in which case subsequent calls will 185 * return an increased value). 186 * 187 * @return The amount of time in last spent in the idle state. 188 * @since 2.10.0 189 * @deprecated Use {@link #getIdleDuration()}. 190 */ 191 @Deprecated 192 default Duration getIdleTime() { 193 return Duration.ofMillis(getIdleTimeMillis()); 194 } 195 196 /** 197 * Gets the amount of time in milliseconds that this object last spend in the 198 * idle state (it may still be idle in which case subsequent calls will 199 * return an increased value). 200 * 201 * @return The time in milliseconds last spent in the idle state. 202 * @deprecated Use {@link #getIdleTime()} which offers the best precision. 203 */ 204 @Deprecated 205 long getIdleTimeMillis(); 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 getLastBorrowInstant() { 214 return Instant.ofEpochMilli(getLastBorrowTime()); 215 } 216 217 /** 218 * Gets the time the wrapped object was last borrowed. 219 * 220 * @return The time the object was last borrowed. 221 * @deprecated Use {@link #getLastBorrowInstant()} which offers the best precision. 222 */ 223 @Deprecated 224 long getLastBorrowTime(); 225 226 /** 227 * Gets the time the wrapped object was last borrowed. 228 * 229 * @return The time the object was last borrowed. 230 * @since 2.11.0 231 */ 232 default Instant getLastReturnInstant() { 233 return Instant.ofEpochMilli(getLastReturnTime()); 234 } 235 236 /** 237 * Gets the time the wrapped object was last returned. 238 * 239 * @return The time the object was last returned. 240 * @deprecated Use {@link #getLastReturnInstant()} which offers the best precision. 241 */ 242 @Deprecated 243 long getLastReturnTime(); 244 245 /** 246 * Gets an estimate of the last time this object was used. If the class of the pooled object implements 247 * {@link TrackedUse}, what is returned is the maximum of {@link TrackedUse#getLastUsedInstant()} and 248 * {@link #getLastBorrowTime()}; otherwise this method gives the same value as {@link #getLastBorrowTime()}. 249 * 250 * @return the last time this object was used 251 * @since 2.11.0 252 */ 253 default Instant getLastUsedInstant() { 254 return Instant.ofEpochMilli(getLastUsedTime()); 255 } 256 257 /** 258 * Gets an estimate of the last time this object was used. If the class 259 * of the pooled object implements {@link TrackedUse}, what is returned is 260 * the maximum of {@link TrackedUse#getLastUsedInstant()} and 261 * {@link #getLastBorrowTime()}; otherwise this method gives the same 262 * value as {@link #getLastBorrowTime()}. 263 * 264 * @return the last time this object was used. 265 * @deprecated Use {@link #getLastUsedInstant()} which offers the best precision. 266 */ 267 @Deprecated 268 long getLastUsedTime(); 269 270 /** 271 * Gets the underlying object that is wrapped by this instance of 272 * {@link PooledObject}. 273 * 274 * @return The wrapped object. 275 */ 276 T getObject(); 277 278 /** 279 * Gets the state of this object. 280 * 281 * @return state 282 */ 283 PooledObjectState getState(); 284 285 @Override 286 int hashCode(); 287 288 /** 289 * Sets the state to {@link PooledObjectState#INVALID INVALID}. 290 */ 291 void invalidate(); 292 293 /** 294 * Marks the pooled object as abandoned. 295 */ 296 void markAbandoned(); 297 298 /** 299 * Marks the object as returning to the pool. 300 */ 301 void markReturning(); 302 303 /** 304 * Prints the stack trace of the code that borrowed this pooled object and 305 * the stack trace of the last code to use this object (if available) to 306 * the supplied writer. 307 * 308 * @param writer The destination for the debug output. 309 */ 310 void printStackTrace(PrintWriter writer); 311 312 /** 313 * Sets whether to use abandoned object tracking. If this is true the 314 * implementation will need to record the stack trace of the last caller to 315 * borrow this object. 316 * 317 * @param logAbandoned The new configuration setting for abandoned 318 * object tracking. 319 */ 320 void setLogAbandoned(boolean logAbandoned); 321 322 /** 323 * Sets the stack trace generation strategy based on whether or not fully detailed stack traces are required. 324 * When set to false, abandoned logs may only include caller class information rather than method names, line 325 * numbers, and other normal metadata available in a full stack trace. 326 * 327 * @param requireFullStackTrace the new configuration setting for abandoned object logging. 328 * @since 2.7.0 329 */ 330 default void setRequireFullStackTrace(final boolean requireFullStackTrace) { 331 // noop 332 } 333 334 /** 335 * Attempts to place the pooled object in the 336 * {@link PooledObjectState#EVICTION} state. 337 * 338 * @return {@code true} if the object was placed in the 339 * {@link PooledObjectState#EVICTION} state otherwise 340 * {@code false}. 341 */ 342 boolean startEvictionTest(); 343 344 /** 345 * Gets a String form of the wrapper for debug purposes. The format is 346 * not fixed and may change at any time. 347 * 348 * {@inheritDoc} 349 */ 350 @Override 351 String toString(); 352 353 /** 354 * Records the current stack trace as the last time the object was used. 355 */ 356 void use(); 357 358 }