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