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