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        // Take copies to avoid threading issues
088        final Instant lastReturnInstant = getLastReturnInstant();
089        final Instant lastBorrowInstant = getLastBorrowInstant();
090        // @formatter:off
091        return lastReturnInstant.isAfter(lastBorrowInstant) ?
092                Duration.between(lastBorrowInstant, lastReturnInstant) :
093                Duration.between(lastBorrowInstant, Instant.now());
094        // @formatter:on
095    }
096
097    /**
098     * Gets the amount of time this object last spent in the active state (it may still be active in which case
099     * subsequent calls will return an increased value).
100     *
101     * @return The duration last spent in the active state.
102     * @since 2.10.0
103     * @deprecated Use {@link #getActiveDuration()}.
104     */
105    @Deprecated
106    default Duration getActiveTime() {
107        return getActiveDuration();
108    }
109
110    /**
111     * Gets the amount of time in milliseconds this object last spent in the
112     * active state (it may still be active in which case subsequent calls will
113     * return an increased value).
114     *
115     * @return The time in milliseconds last spent in the active state.
116     * @deprecated Use {@link #getActiveTime()} which offers the best precision.
117     */
118    @Deprecated
119    long getActiveTimeMillis();
120
121    /**
122     * Gets the number of times this object has been borrowed.
123     *
124     * @return -1 by default for implementations prior to release 2.7.0.
125     * @since 2.7.0
126     */
127    default long getBorrowedCount() {
128        return -1;
129    }
130
131    /**
132     * Gets the time (using the same basis as {@link Instant#now()}) that this object was created.
133     *
134     * @return The creation time for the wrapped object.
135     * @since 2.11.0
136     */
137    default Instant getCreateInstant() {
138        return Instant.ofEpochMilli(getCreateTime());
139    }
140
141    /**
142     * Gets the time (using the same basis as
143     * {@link System#currentTimeMillis()}) that this object was created.
144     *
145     * @return The creation time for the wrapped object.
146     * @deprecated Use {@link #getCreateInstant()} which offers the best precision.
147     */
148    @Deprecated
149    long getCreateTime();
150
151    /**
152     * Gets the amount of time that this object last spend in the
153     * idle state (it may still be idle in which case subsequent calls will
154     * return an increased value).
155     *
156     * @return The amount of time in last spent in the idle state.
157     * @since 2.11.0
158     */
159    default Duration getIdleDuration() {
160        return Duration.ofMillis(getIdleTimeMillis());
161    }
162
163    /**
164     * Gets the amount of time that this object last spend in the
165     * idle state (it may still be idle in which case subsequent calls will
166     * return an increased value).
167     *
168     * @return The amount of time in last spent in the idle state.
169     * @since 2.10.0
170     * @deprecated Use {@link #getIdleDuration()}.
171     */
172    @Deprecated
173    default Duration getIdleTime() {
174        return Duration.ofMillis(getIdleTimeMillis());
175    }
176
177    /**
178     * Gets the amount of time in milliseconds that this object last spend in the
179     * idle state (it may still be idle in which case subsequent calls will
180     * return an increased value).
181     *
182     * @return The time in milliseconds last spent in the idle state.
183     * @deprecated Use {@link #getIdleTime()} which offers the best precision.
184     */
185    @Deprecated
186    long getIdleTimeMillis();
187
188    /**
189     * Gets the time the wrapped object was last borrowed.
190     *
191     * @return The time the object was last borrowed.
192     * @since 2.11.0
193     */
194    default Instant getLastBorrowInstant() {
195        return Instant.ofEpochMilli(getLastBorrowTime());
196    }
197
198    /**
199     * Gets the time the wrapped object was last borrowed.
200     *
201     * @return The time the object was last borrowed.
202     * @deprecated Use {@link #getLastBorrowInstant()} which offers the best precision.
203     */
204    @Deprecated
205    long getLastBorrowTime();
206
207    /**
208     * Gets the time the wrapped object was last borrowed.
209     *
210     * @return The time the object was last borrowed.
211     * @since 2.11.0
212     */
213    default Instant getLastReturnInstant() {
214        return Instant.ofEpochMilli(getLastReturnTime());
215    }
216
217    /**
218     * Gets the time the wrapped object was last returned.
219     *
220     * @return The time the object was last returned.
221     * @deprecated Use {@link #getLastReturnInstant()} which offers the best precision.
222     */
223    @Deprecated
224    long getLastReturnTime();
225
226    /**
227     * Gets an estimate of the last time this object was used. If the class of the pooled object implements
228     * {@link TrackedUse}, what is returned is the maximum of {@link TrackedUse#getLastUsedInstant()} and
229     * {@link #getLastBorrowTime()}; otherwise this method gives the same value as {@link #getLastBorrowTime()}.
230     *
231     * @return the last time this object was used
232     * @since 2.11.0
233     */
234    default Instant getLastUsedInstant() {
235        return Instant.ofEpochMilli(getLastUsedTime());
236    }
237
238    /**
239     * Gets an estimate of the last time this object was used.  If the class
240     * of the pooled object implements {@link TrackedUse}, what is returned is
241     * the maximum of {@link TrackedUse#getLastUsedInstant()} and
242     * {@link #getLastBorrowTime()}; otherwise this method gives the same
243     * value as {@link #getLastBorrowTime()}.
244     *
245     * @return the last time this object was used.
246     * @deprecated Use {@link #getLastUsedInstant()} which offers the best precision.
247     */
248    @Deprecated
249    long getLastUsedTime();
250
251    /**
252     * Gets the underlying object that is wrapped by this instance of
253     * {@link PooledObject}.
254     *
255     * @return The wrapped object.
256     */
257    T getObject();
258
259    /**
260     * Gets the state of this object.
261     * @return state
262     */
263    PooledObjectState getState();
264
265    @Override
266    int hashCode();
267
268    /**
269     * Sets the state to {@link PooledObjectState#INVALID INVALID}.
270     */
271    void invalidate();
272
273    /**
274     * Marks the pooled object as abandoned.
275     */
276    void markAbandoned();
277
278    /**
279     * Marks the object as returning to the pool.
280     */
281    void markReturning();
282
283    /**
284     * Prints the stack trace of the code that borrowed this pooled object and
285     * the stack trace of the last code to use this object (if available) to
286     * the supplied writer.
287     *
288     * @param   writer  The destination for the debug output.
289     */
290    void printStackTrace(PrintWriter writer);
291
292    /**
293     * Sets whether to use abandoned object tracking. If this is true the
294     * implementation will need to record the stack trace of the last caller to
295     * borrow this object.
296     *
297     * @param   logAbandoned    The new configuration setting for abandoned
298     *                          object tracking.
299     */
300    void setLogAbandoned(boolean logAbandoned);
301
302    /**
303     * Sets the stack trace generation strategy based on whether or not fully detailed stack traces are required.
304     * When set to false, abandoned logs may only include caller class information rather than method names, line
305     * numbers, and other normal metadata available in a full stack trace.
306     *
307     * @param requireFullStackTrace the new configuration setting for abandoned object logging.
308     * @since 2.7.0
309     */
310    default void setRequireFullStackTrace(final boolean requireFullStackTrace) {
311        // noop
312    }
313
314    /**
315     * Attempts to place the pooled object in the
316     * {@link PooledObjectState#EVICTION} state.
317     *
318     * @return {@code true} if the object was placed in the
319     *         {@link PooledObjectState#EVICTION} state otherwise
320     *         {@code false}.
321     */
322    boolean startEvictionTest();
323
324    /**
325     * Gets a String form of the wrapper for debug purposes. The format is
326     * not fixed and may change at any time.
327     *
328     * {@inheritDoc}
329     */
330    @Override
331    String toString();
332
333    /**
334     * Records the current stack trace as the last time the object was used.
335     */
336    void use();
337
338}