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