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 final Instant lastReturnInstant = getLastReturnInstant(); 088 final Instant lastBorrowInstant = getLastBorrowInstant(); 089 // @formatter:off 090 return lastReturnInstant.isAfter(lastBorrowInstant) ? 091 Duration.between(lastBorrowInstant, lastReturnInstant) : 092 Duration.between(Instant.now(), lastBorrowInstant); 093 // @formatter:on 094 } 095 096 /** 097 * Gets the amount of time this object last spent in the active state (it may still be active in which case 098 * subsequent calls will return an increased value). 099 * 100 * @return The duration last spent in the active state. 101 * @since 2.10.0 102 * @deprecated Use {@link #getActiveDuration()}. 103 */ 104 @Deprecated 105 default Duration getActiveTime() { 106 return getActiveDuration(); 107 } 108 109 /** 110 * Gets the amount of time in milliseconds this object last spent in the 111 * active state (it may still be active in which case subsequent calls will 112 * return an increased value). 113 * 114 * @return The time in milliseconds last spent in the active state. 115 * @deprecated Use {@link #getActiveTime()} which offers the best precision. 116 */ 117 @Deprecated 118 long getActiveTimeMillis(); 119 120 /** 121 * Gets the number of times this object has been borrowed. 122 * 123 * @return -1 by default for implementations prior to release 2.7.0. 124 * @since 2.7.0 125 */ 126 default long getBorrowedCount() { 127 return -1; 128 } 129 130 /** 131 * Gets the time (using the same basis as {@link Instant#now()}) that this object was created. 132 * 133 * @return The creation time for the wrapped object. 134 * @since 2.11.0 135 */ 136 default Instant getCreateInstant() { 137 return Instant.ofEpochMilli(getCreateTime()); 138 } 139 140 /** 141 * Gets the time (using the same basis as 142 * {@link System#currentTimeMillis()}) that this object was created. 143 * 144 * @return The creation time for the wrapped object. 145 * @deprecated Use {@link #getCreateInstant()} which offers the best precision. 146 */ 147 @Deprecated 148 long getCreateTime(); 149 150 /** 151 * Gets the amount of time that this object last spend in the 152 * idle state (it may still be idle in which case subsequent calls will 153 * return an increased value). 154 * 155 * @return The amount of time in last spent in the idle state. 156 * @since 2.11.0 157 */ 158 default Duration getIdleDuration() { 159 return Duration.ofMillis(getIdleTimeMillis()); 160 } 161 162 /** 163 * Gets the amount of time that this object last spend in the 164 * idle state (it may still be idle in which case subsequent calls will 165 * return an increased value). 166 * 167 * @return The amount of time in last spent in the idle state. 168 * @since 2.10.0 169 * @deprecated Use {@link #getIdleDuration()}. 170 */ 171 @Deprecated 172 default Duration getIdleTime() { 173 return Duration.ofMillis(getIdleTimeMillis()); 174 } 175 176 /** 177 * Gets the amount of time in milliseconds that this object last spend in the 178 * idle state (it may still be idle in which case subsequent calls will 179 * return an increased value). 180 * 181 * @return The time in milliseconds last spent in the idle state. 182 * @deprecated Use {@link #getIdleTime()} which offers the best precision. 183 */ 184 @Deprecated 185 long getIdleTimeMillis(); 186 187 /** 188 * Gets the time the wrapped object was last borrowed. 189 * 190 * @return The time the object was last borrowed. 191 * @since 2.11.0 192 */ 193 default Instant getLastBorrowInstant() { 194 return Instant.ofEpochMilli(getLastBorrowTime()); 195 } 196 197 /** 198 * Gets the time the wrapped object was last borrowed. 199 * 200 * @return The time the object was last borrowed. 201 * @deprecated Use {@link #getLastBorrowInstant()} which offers the best precision. 202 */ 203 @Deprecated 204 long getLastBorrowTime(); 205 206 /** 207 * Gets the time the wrapped object was last borrowed. 208 * 209 * @return The time the object was last borrowed. 210 * @since 2.11.0 211 */ 212 default Instant getLastReturnInstant() { 213 return Instant.ofEpochMilli(getLastReturnTime()); 214 } 215 216 /** 217 * Gets the time the wrapped object was last returned. 218 * 219 * @return The time the object was last returned. 220 * @deprecated Use {@link #getLastReturnInstant()} which offers the best precision. 221 */ 222 @Deprecated 223 long getLastReturnTime(); 224 225 /** 226 * Gets an estimate of the last time this object was used. If the class of the pooled object implements 227 * {@link TrackedUse}, what is returned is the maximum of {@link TrackedUse#getLastUsedInstant()} and 228 * {@link #getLastBorrowTime()}; otherwise this method gives the same value as {@link #getLastBorrowTime()}. 229 * 230 * @return the last time this object was used 231 * @since 2.11.0 232 */ 233 default Instant getLastUsedInstant() { 234 return Instant.ofEpochMilli(getLastUsedTime()); 235 } 236 237 /** 238 * Gets an estimate of the last time this object was used. If the class 239 * of the pooled object implements {@link TrackedUse}, what is returned is 240 * the maximum of {@link TrackedUse#getLastUsedInstant()} and 241 * {@link #getLastBorrowTime()}; otherwise this method gives the same 242 * value as {@link #getLastBorrowTime()}. 243 * 244 * @return the last time this object was used. 245 * @deprecated Use {@link #getLastUsedInstant()} which offers the best precision. 246 */ 247 @Deprecated 248 long getLastUsedTime(); 249 250 /** 251 * Gets the underlying object that is wrapped by this instance of 252 * {@link PooledObject}. 253 * 254 * @return The wrapped object. 255 */ 256 T getObject(); 257 258 /** 259 * Gets the state of this object. 260 * @return state 261 */ 262 PooledObjectState getState(); 263 264 @Override 265 int hashCode(); 266 267 /** 268 * Sets the state to {@link PooledObjectState#INVALID INVALID}. 269 */ 270 void invalidate(); 271 272 /** 273 * Marks the pooled object as abandoned. 274 */ 275 void markAbandoned(); 276 277 /** 278 * Marks the object as returning to the pool. 279 */ 280 void markReturning(); 281 282 /** 283 * Prints the stack trace of the code that borrowed this pooled object and 284 * the stack trace of the last code to use this object (if available) to 285 * the supplied writer. 286 * 287 * @param writer The destination for the debug output. 288 */ 289 void printStackTrace(PrintWriter writer); 290 291 /** 292 * Sets whether to use abandoned object tracking. If this is true the 293 * implementation will need to record the stack trace of the last caller to 294 * borrow this object. 295 * 296 * @param logAbandoned The new configuration setting for abandoned 297 * object tracking. 298 */ 299 void setLogAbandoned(boolean logAbandoned); 300 301 /** 302 * Sets the stack trace generation strategy based on whether or not fully detailed stack traces are required. 303 * When set to false, abandoned logs may only include caller class information rather than method names, line 304 * numbers, and other normal metadata available in a full stack trace. 305 * 306 * @param requireFullStackTrace the new configuration setting for abandoned object logging. 307 * @since 2.7.0 308 */ 309 default void setRequireFullStackTrace(final boolean requireFullStackTrace) { 310 // noop 311 } 312 313 /** 314 * Attempts to place the pooled object in the 315 * {@link PooledObjectState#EVICTION} state. 316 * 317 * @return {@code true} if the object was placed in the 318 * {@link PooledObjectState#EVICTION} state otherwise 319 * {@code false}. 320 */ 321 boolean startEvictionTest(); 322 323 /** 324 * Gets a String form of the wrapper for debug purposes. The format is 325 * not fixed and may change at any time. 326 * 327 * {@inheritDoc} 328 */ 329 @Override 330 String toString(); 331 332 /** 333 * Records the current stack trace as the last time the object was used. 334 */ 335 void use(); 336 337}