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     * Obtain 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     * Obtain 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     * Obtain 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     * Obtain 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     * Obtain 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     * Obtain 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     * Return 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     * {@inheritDoc}
101     */
102    @Override
103    int compareTo(PooledObject<T> other);
104
105    @Override
106    boolean equals(Object obj);
107
108    @Override
109    int hashCode();
110
111    /**
112     * Provides a String form of the wrapper for debug purposes. The format is
113     * not fixed and may change at any time.
114     * <p>
115     * {@inheritDoc}
116     */
117    @Override
118    String toString();
119
120    /**
121     * Attempt to place the pooled object in the
122     * {@link PooledObjectState#EVICTION} state.
123     *
124     * @return <code>true</code> if the object was placed in the
125     *         {@link PooledObjectState#EVICTION} state otherwise
126     *         <code>false</code>
127     */
128    boolean startEvictionTest();
129
130    /**
131     * Called to inform the object that the eviction test has ended.
132     *
133     * @param idleQueue The queue of idle objects to which the object should be
134     *                  returned
135     *
136     * @return  Currently not used
137     */
138    boolean endEvictionTest(Deque<PooledObject<T>> idleQueue);
139
140    /**
141     * Allocates the object.
142     *
143     * @return {@code true} if the original state was {@link PooledObjectState#IDLE IDLE}
144     */
145    boolean allocate();
146
147    /**
148     * Deallocates the object and sets it {@link PooledObjectState#IDLE IDLE}
149     * if it is currently {@link PooledObjectState#ALLOCATED ALLOCATED}.
150     *
151     * @return {@code true} if the state was {@link PooledObjectState#ALLOCATED ALLOCATED}
152     */
153    boolean deallocate();
154
155    /**
156     * Sets the state to {@link PooledObjectState#INVALID INVALID}
157     */
158    void invalidate();
159
160    /**
161     * Is abandoned object tracking being used? If this is true the
162     * implementation will need to record the stack trace of the last caller to
163     * borrow this object.
164     *
165     * @param   logAbandoned    The new configuration setting for abandoned
166     *                          object tracking
167     */
168    void setLogAbandoned(boolean logAbandoned);
169
170// TODO: uncomment in 3.0 (API compatibility)
171//    /**
172//     * Configures the stack trace generation strategy based on whether or not fully
173//     * detailed stack traces are required. When set to false, abandoned logs may
174//     * only include caller class information rather than method names, line numbers,
175//     * and other normal metadata available in a full stack trace.
176//     *
177//     * @param requireFullStackTrace the new configuration setting for abandoned object
178//     *                              logging
179//     */
180//    void setRequireFullStackTrace(boolean requireFullStackTrace);
181
182    /**
183     * Record the current stack trace as the last time the object was used.
184     */
185    void use();
186
187    /**
188     * Prints the stack trace of the code that borrowed this pooled object and
189     * the stack trace of the last code to use this object (if available) to
190     * the supplied writer.
191     *
192     * @param   writer  The destination for the debug output
193     */
194    void printStackTrace(PrintWriter writer);
195
196    /**
197     * Returns the state of this object.
198     * @return state
199     */
200    PooledObjectState getState();
201
202    /**
203     * Marks the pooled object as abandoned.
204     */
205    void markAbandoned();
206
207    /**
208     * Marks the object as returning to the pool.
209     */
210    void markReturning();
211
212    // TODO: Uncomment this for version 3 (can't add it to 2.x as it will break
213    //       API compatibility)
214    ///**
215    // * Get the number of times this object has been borrowed.
216    // */
217    //long getBorrowedCount();
218}