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