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 * @version $Revision: $ 031 * 032 * @since 2.0 033 */ 034public interface PooledObject<T> extends Comparable<PooledObject<T>> { 035 036 /** 037 * Obtain the underlying object that is wrapped by this instance of 038 * {@link PooledObject}. 039 * 040 * @return The wrapped object 041 */ 042 T getObject(); 043 044 /** 045 * Obtain the time (using the same basis as 046 * {@link System#currentTimeMillis()}) that this object was created. 047 * 048 * @return The creation time for the wrapped object 049 */ 050 long getCreateTime(); 051 052 /** 053 * Obtain the time in milliseconds that this object last spent in the the 054 * active state (it may still be active in which case subsequent calls will 055 * return an increased value). 056 * 057 * @return The time in milliseconds last spent in the active state 058 */ 059 long getActiveTimeMillis(); 060 061 /** 062 * Obtain the time in milliseconds that this object last spend in the the 063 * idle state (it may still be idle in which case subsequent calls will 064 * return an increased value). 065 * 066 * @return The time in milliseconds last spent in the idle state 067 */ 068 long getIdleTimeMillis(); 069 070 /** 071 * Obtain the time the wrapped object was last borrowed. 072 * 073 * @return The time the object was last borrowed 074 */ 075 long getLastBorrowTime(); 076 077 /** 078 * Obtain the time the wrapped object was last returned. 079 * 080 * @return The time the object was last returned 081 */ 082 long getLastReturnTime(); 083 084 /** 085 * Return an estimate of the last time this object was used. If the class 086 * of the pooled object implements {@link TrackedUse}, what is returned is 087 * the maximum of {@link TrackedUse#getLastUsed()} and 088 * {@link #getLastBorrowTime()}; otherwise this method gives the same 089 * value as {@link #getLastBorrowTime()}. 090 * 091 * @return the last time this object was used 092 */ 093 long getLastUsedTime(); 094 095 /** 096 * Orders instances based on idle time - i.e. the length of time since the 097 * instance was returned to the pool. Used by the GKOP idle object evictor. 098 *<p> 099 * Note: This class has a natural ordering that is inconsistent with 100 * equals if distinct objects have the same identity hash code. 101 * <p> 102 * {@inheritDoc} 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 * Attempt 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 /** 173 * Record the current stack trace as the last time the object was used. 174 */ 175 void use(); 176 177 /** 178 * Prints the stack trace of the code that borrowed this pooled object and 179 * the stack trace of the last code to use this object (if available) to 180 * the supplied writer. 181 * 182 * @param writer The destination for the debug output 183 */ 184 void printStackTrace(PrintWriter writer); 185 186 /** 187 * Returns the state of this object. 188 * @return state 189 */ 190 PooledObjectState getState(); 191 192 /** 193 * Marks the pooled object as abandoned. 194 */ 195 void markAbandoned(); 196 197 /** 198 * Marks the object as returning to the pool. 199 */ 200 void markReturning(); 201 202 // TODO: Uncomment this for version 3 (can't add it to 2.x as it will break 203 // API compatibility) 204 ///** 205 // * Get the number of times this object has been borrowed. 206 // */ 207 //long getBorrowedCount(); 208}