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}