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