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.time.Instant;
022import java.util.Deque;
023
024/**
025 * Defines the wrapper that is used to track the additional information, such as
026 * state, for the pooled objects.
027 * <p>
028 * Implementations of this class are required to be thread-safe.
029 * </p>
030 *
031 * @param <T> the type of object in the pool
032 *
033 * @since 2.0
034 */
035public interface PooledObject<T> extends Comparable<PooledObject<T>> {
036
037    /**
038     * Allocates the object.
039     *
040     * @return {@code true} if the original state was {@link PooledObjectState#IDLE IDLE}
041     */
042    boolean allocate();
043
044    /**
045     * Orders instances based on idle time - i.e. the length of time since the
046     * instance was returned to the pool. Used by the GKOP idle object evictor.
047     *<p>
048     * Note: This class has a natural ordering that is inconsistent with
049     *       equals if distinct objects have the same identity hash code.
050     * </p>
051     * <p>
052     * {@inheritDoc}
053     * </p>
054     */
055    @Override
056    int compareTo(PooledObject<T> other);
057
058    /**
059     * Deallocates the object and sets it {@link PooledObjectState#IDLE IDLE}
060     * if it is currently {@link PooledObjectState#ALLOCATED ALLOCATED}.
061     *
062     * @return {@code true} if the state was {@link PooledObjectState#ALLOCATED ALLOCATED}.
063     */
064    boolean deallocate();
065
066    /**
067     * Notifies the object that the eviction test has ended.
068     *
069     * @param idleQueue The queue of idle objects to which the object should be
070     *                  returned.
071     *
072     * @return  Currently not used.
073     */
074    boolean endEvictionTest(Deque<PooledObject<T>> idleQueue);
075
076    @Override
077    boolean equals(Object obj);
078
079    /**
080     * Gets the amount of time this object last spent in the active state (it may still be active in which case
081     * subsequent calls will return an increased value).
082     *
083     * @return The duration last spent in the active state.
084     * @since 2.11.0
085     */
086    default Duration getActiveDuration() {
087        final Instant lastReturnInstant = getLastReturnInstant();
088        final Instant lastBorrowInstant = getLastBorrowInstant();
089        // @formatter:off
090        return lastReturnInstant.isAfter(lastBorrowInstant) ?
091                Duration.between(lastBorrowInstant, lastReturnInstant) :
092                Duration.between(Instant.now(), lastBorrowInstant);
093        // @formatter:on
094    }
095
096    /**
097     * Gets the amount of time this object last spent in the active state (it may still be active in which case
098     * subsequent calls will return an increased value).
099     *
100     * @return The duration last spent in the active state.
101     * @since 2.10.0
102     * @deprecated Use {@link #getActiveDuration()}.
103     */
104    @Deprecated
105    default Duration getActiveTime() {
106        return getActiveDuration();
107    }
108
109    /**
110     * Gets the amount of time in milliseconds this object last spent in the
111     * active state (it may still be active in which case subsequent calls will
112     * return an increased value).
113     *
114     * @return The time in milliseconds last spent in the active state.
115     * @deprecated Use {@link #getActiveTime()} which offers the best precision.
116     */
117    @Deprecated
118    long getActiveTimeMillis();
119
120    /**
121     * Gets the number of times this object has been borrowed.
122     *
123     * @return -1 by default for implementations prior to release 2.7.0.
124     * @since 2.7.0
125     */
126    default long getBorrowedCount() {
127        return -1;
128    }
129
130    /**
131     * Gets the time (using the same basis as {@link Instant#now()}) that this object was created.
132     *
133     * @return The creation time for the wrapped object.
134     * @since 2.11.0
135     */
136    default Instant getCreateInstant() {
137        return Instant.ofEpochMilli(getCreateTime());
138    }
139
140    /**
141     * Gets the time (using the same basis as
142     * {@link System#currentTimeMillis()}) that this object was created.
143     *
144     * @return The creation time for the wrapped object.
145     * @deprecated Use {@link #getCreateInstant()} which offers the best precision.
146     */
147    @Deprecated
148    long getCreateTime();
149
150    /**
151     * Gets the amount of time that this object last spend in the
152     * idle state (it may still be idle in which case subsequent calls will
153     * return an increased value).
154     *
155     * @return The amount of time in last spent in the idle state.
156     * @since 2.11.0
157     */
158    default Duration getIdleDuration() {
159        return Duration.ofMillis(getIdleTimeMillis());
160    }
161
162    /**
163     * Gets the amount of time that this object last spend in the
164     * idle state (it may still be idle in which case subsequent calls will
165     * return an increased value).
166     *
167     * @return The amount of time in last spent in the idle state.
168     * @since 2.10.0
169     * @deprecated Use {@link #getIdleDuration()}.
170     */
171    @Deprecated
172    default Duration getIdleTime() {
173        return Duration.ofMillis(getIdleTimeMillis());
174    }
175
176    /**
177     * Gets the amount of time in milliseconds that this object last spend in the
178     * idle state (it may still be idle in which case subsequent calls will
179     * return an increased value).
180     *
181     * @return The time in milliseconds last spent in the idle state.
182     * @deprecated Use {@link #getIdleTime()} which offers the best precision.
183     */
184    @Deprecated
185    long getIdleTimeMillis();
186
187    /**
188     * Gets the time the wrapped object was last borrowed.
189     *
190     * @return The time the object was last borrowed.
191     * @since 2.11.0
192     */
193    default Instant getLastBorrowInstant() {
194        return Instant.ofEpochMilli(getLastBorrowTime());
195    }
196
197    /**
198     * Gets the time the wrapped object was last borrowed.
199     *
200     * @return The time the object was last borrowed.
201     * @deprecated Use {@link #getLastBorrowInstant()} which offers the best precision.
202     */
203    @Deprecated
204    long getLastBorrowTime();
205
206    /**
207     * Gets the time the wrapped object was last borrowed.
208     *
209     * @return The time the object was last borrowed.
210     * @since 2.11.0
211     */
212    default Instant getLastReturnInstant() {
213        return Instant.ofEpochMilli(getLastReturnTime());
214    }
215
216    /**
217     * Gets the time the wrapped object was last returned.
218     *
219     * @return The time the object was last returned.
220     * @deprecated Use {@link #getLastReturnInstant()} which offers the best precision.
221     */
222    @Deprecated
223    long getLastReturnTime();
224
225    /**
226     * Gets an estimate of the last time this object was used. If the class of the pooled object implements
227     * {@link TrackedUse}, what is returned is the maximum of {@link TrackedUse#getLastUsedInstant()} and
228     * {@link #getLastBorrowTime()}; otherwise this method gives the same value as {@link #getLastBorrowTime()}.
229     *
230     * @return the last time this object was used
231     * @since 2.11.0
232     */
233    default Instant getLastUsedInstant() {
234        return Instant.ofEpochMilli(getLastUsedTime());
235    }
236
237    /**
238     * Gets an estimate of the last time this object was used.  If the class
239     * of the pooled object implements {@link TrackedUse}, what is returned is
240     * the maximum of {@link TrackedUse#getLastUsedInstant()} and
241     * {@link #getLastBorrowTime()}; otherwise this method gives the same
242     * value as {@link #getLastBorrowTime()}.
243     *
244     * @return the last time this object was used.
245     * @deprecated Use {@link #getLastUsedInstant()} which offers the best precision.
246     */
247    @Deprecated
248    long getLastUsedTime();
249
250    /**
251     * Gets the underlying object that is wrapped by this instance of
252     * {@link PooledObject}.
253     *
254     * @return The wrapped object.
255     */
256    T getObject();
257
258    /**
259     * Gets the state of this object.
260     * @return state
261     */
262    PooledObjectState getState();
263
264    @Override
265    int hashCode();
266
267    /**
268     * Sets the state to {@link PooledObjectState#INVALID INVALID}.
269     */
270    void invalidate();
271
272    /**
273     * Marks the pooled object as abandoned.
274     */
275    void markAbandoned();
276
277    /**
278     * Marks the object as returning to the pool.
279     */
280    void markReturning();
281
282    /**
283     * Prints the stack trace of the code that borrowed this pooled object and
284     * the stack trace of the last code to use this object (if available) to
285     * the supplied writer.
286     *
287     * @param   writer  The destination for the debug output.
288     */
289    void printStackTrace(PrintWriter writer);
290
291    /**
292     * Sets whether to use abandoned object tracking. If this is true the
293     * implementation will need to record the stack trace of the last caller to
294     * borrow this object.
295     *
296     * @param   logAbandoned    The new configuration setting for abandoned
297     *                          object tracking.
298     */
299    void setLogAbandoned(boolean logAbandoned);
300
301    /**
302     * Sets the stack trace generation strategy based on whether or not fully detailed stack traces are required.
303     * When set to false, abandoned logs may only include caller class information rather than method names, line
304     * numbers, and other normal metadata available in a full stack trace.
305     *
306     * @param requireFullStackTrace the new configuration setting for abandoned object logging.
307     * @since 2.7.0
308     */
309    default void setRequireFullStackTrace(final boolean requireFullStackTrace) {
310        // noop
311    }
312
313    /**
314     * Attempts to place the pooled object in the
315     * {@link PooledObjectState#EVICTION} state.
316     *
317     * @return {@code true} if the object was placed in the
318     *         {@link PooledObjectState#EVICTION} state otherwise
319     *         {@code false}.
320     */
321    boolean startEvictionTest();
322
323    /**
324     * Gets a String form of the wrapper for debug purposes. The format is
325     * not fixed and may change at any time.
326     *
327     * {@inheritDoc}
328     */
329    @Override
330    String toString();
331
332    /**
333     * Records the current stack trace as the last time the object was used.
334     */
335    void use();
336
337}