    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}