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