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