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.util.Deque; 022 023/** 024 * Defines the wrapper that is used to track the additional information, such as 025 * state, for the pooled objects. 026 * <p> 027 * Implementations of this class are required to be thread-safe. 028 * </p> 029 * 030 * @param <T> the type of object in the pool 031 * 032 * @since 2.0 033 */ 034public interface PooledObject<T> extends Comparable<PooledObject<T>> { 035 036 /** 037 * Allocates the object. 038 * 039 * @return {@code true} if the original state was {@link PooledObjectState#IDLE IDLE} 040 */ 041 boolean allocate(); 042 043 /** 044 * Orders instances based on idle time - i.e. the length of time since the 045 * instance was returned to the pool. Used by the GKOP idle object evictor. 046 *<p> 047 * Note: This class has a natural ordering that is inconsistent with 048 * equals if distinct objects have the same identity hash code. 049 * </p> 050 * <p> 051 * {@inheritDoc} 052 * </p> 053 */ 054 @Override 055 int compareTo(PooledObject<T> other); 056 057 /** 058 * Deallocates the object and sets it {@link PooledObjectState#IDLE IDLE} 059 * if it is currently {@link PooledObjectState#ALLOCATED ALLOCATED}. 060 * 061 * @return {@code true} if the state was {@link PooledObjectState#ALLOCATED ALLOCATED} 062 */ 063 boolean deallocate(); 064 065 /** 066 * Called to inform the object that the eviction test has ended. 067 * 068 * @param idleQueue The queue of idle objects to which the object should be 069 * returned 070 * 071 * @return Currently not used 072 */ 073 boolean endEvictionTest(Deque<PooledObject<T>> idleQueue); 074 075 @Override 076 boolean equals(Object obj); 077 078 /** 079 * Gets the amount of time this object last spent in the 080 * active state (it may still be active in which case subsequent calls will 081 * return an increased value). 082 * 083 * @return The duration last spent in the active state 084 * @since 2.12.0 085 */ 086 default Duration getActiveTime() { 087 return Duration.ofMillis(getActiveTimeMillis()); 088 } 089 090 /** 091 * Gets the amount of time in milliseconds this object last spent in the 092 * active state (it may still be active in which case subsequent calls will 093 * return an increased value). 094 * 095 * @return The time in milliseconds last spent in the active state 096 */ 097 long getActiveTimeMillis(); 098 099 /** 100 * Gets the number of times this object has been borrowed. 101 * 102 * @return -1 by default for old implementations prior to release 2.7.0. 103 * @since 2.7.0 104 */ 105 default long getBorrowedCount() { 106 return -1; 107 } 108 109 /** 110 * Gets the time (using the same basis as 111 * {@link System#currentTimeMillis()}) that this object was created. 112 * 113 * @return The creation time for the wrapped object 114 */ 115 long getCreateTime(); 116 117 /** 118 * Gets the amount of time that this object last spend in the 119 * idle state (it may still be idle in which case subsequent calls will 120 * return an increased value). 121 * 122 * @return The amount of time in last spent in the idle state. 123 * @since 2.10.0 124 */ 125 default Duration getIdleTime() { 126 return Duration.ofMillis(getIdleTimeMillis()); 127 } 128 129 /** 130 * Gets the amount of time in milliseconds that this object last spend in the 131 * idle state (it may still be idle in which case subsequent calls will 132 * return an increased value). 133 * 134 * @return The time in milliseconds last spent in the idle state 135 */ 136 long getIdleTimeMillis(); 137 138 /** 139 * Gets the time the wrapped object was last borrowed. 140 * 141 * @return The time the object was last borrowed 142 */ 143 long getLastBorrowTime(); 144 145 /** 146 * Gets the time the wrapped object was last returned. 147 * 148 * @return The time the object was last returned 149 */ 150 long getLastReturnTime(); 151 152 /** 153 * Gets an estimate of the last time this object was used. If the class 154 * of the pooled object implements {@link TrackedUse}, what is returned is 155 * the maximum of {@link TrackedUse#getLastUsed()} and 156 * {@link #getLastBorrowTime()}; otherwise this method gives the same 157 * value as {@link #getLastBorrowTime()}. 158 * 159 * @return the last time this object was used 160 */ 161 long getLastUsedTime(); 162 163 /** 164 * Gets the underlying object that is wrapped by this instance of 165 * {@link PooledObject}. 166 * 167 * @return The wrapped object 168 */ 169 T getObject(); 170 171 /** 172 * Gets the state of this object. 173 * @return state 174 */ 175 PooledObjectState getState(); 176 177 @Override 178 int hashCode(); 179 180 /** 181 * Sets the state to {@link PooledObjectState#INVALID INVALID} 182 */ 183 void invalidate(); 184 185 /** 186 * Marks the pooled object as abandoned. 187 */ 188 void markAbandoned(); 189 190 /** 191 * Marks the object as returning to the pool. 192 */ 193 void markReturning(); 194 195 /** 196 * Prints the stack trace of the code that borrowed this pooled object and 197 * the stack trace of the last code to use this object (if available) to 198 * the supplied writer. 199 * 200 * @param writer The destination for the debug output 201 */ 202 void printStackTrace(PrintWriter writer); 203 204 /** 205 * Is abandoned object tracking being used? If this is true the 206 * implementation will need to record the stack trace of the last caller to 207 * borrow this object. 208 * 209 * @param logAbandoned The new configuration setting for abandoned 210 * object tracking 211 */ 212 void setLogAbandoned(boolean logAbandoned); 213 214 /** 215 * Configures the stack trace generation strategy based on whether or not fully detailed stack traces are required. 216 * When set to false, abandoned logs may only include caller class information rather than method names, line 217 * numbers, and other normal metadata available in a full stack trace. 218 * 219 * @param requireFullStackTrace the new configuration setting for abandoned object logging 220 * @since 2.7.0 221 */ 222 default void setRequireFullStackTrace(final boolean requireFullStackTrace) { 223 // noop 224 } 225 226 /** 227 * Attempts to place the pooled object in the 228 * {@link PooledObjectState#EVICTION} state. 229 * 230 * @return {@code true} if the object was placed in the 231 * {@link PooledObjectState#EVICTION} state otherwise 232 * {@code false} 233 */ 234 boolean startEvictionTest(); 235 236 /** 237 * Provides a String form of the wrapper for debug purposes. The format is 238 * not fixed and may change at any time. 239 * <p> 240 * {@inheritDoc} 241 */ 242 @Override 243 String toString(); 244 245 /** 246 * Record the current stack trace as the last time the object was used. 247 */ 248 void use(); 249 250}