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}