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 * @version $Revision: $
031 *
032 * @since 2.0
033 */
034public interface PooledObject<T> extends Comparable<PooledObject<T>> {
035
036    /**
037     * Obtain the underlying object that is wrapped by this instance of
038     * {@link PooledObject}.
039     *
040     * @return The wrapped object
041     */
042    T getObject();
043
044    /**
045     * Obtain the time (using the same basis as
046     * {@link System#currentTimeMillis()}) that this object was created.
047     *
048     * @return The creation time for the wrapped object
049     */
050    long getCreateTime();
051
052    /**
053     * Obtain the time in milliseconds that this object last spent in the the
054     * active state (it may still be active in which case subsequent calls will
055     * return an increased value).
056     *
057     * @return The time in milliseconds last spent in the active state
058     */
059    long getActiveTimeMillis();
060
061    /**
062     * Obtain the time in milliseconds that this object last spend in the the
063     * idle state (it may still be idle in which case subsequent calls will
064     * return an increased value).
065     *
066     * @return The time in milliseconds last spent in the idle state
067     */
068    long getIdleTimeMillis();
069
070    /**
071     * Obtain the time the wrapped object was last borrowed.
072     *
073     * @return The time the object was last borrowed
074     */
075    long getLastBorrowTime();
076
077    /**
078     * Obtain the time the wrapped object was last returned.
079     *
080     * @return The time the object was last returned
081     */
082    long getLastReturnTime();
083
084    /**
085     * Return an estimate of the last time this object was used.  If the class
086     * of the pooled object implements {@link TrackedUse}, what is returned is
087     * the maximum of {@link TrackedUse#getLastUsed()} and
088     * {@link #getLastBorrowTime()}; otherwise this method gives the same
089     * value as {@link #getLastBorrowTime()}.
090     *
091     * @return the last time this object was used
092     */
093    long getLastUsedTime();
094
095    /**
096     * Orders instances based on idle time - i.e. the length of time since the
097     * instance was returned to the pool. Used by the GKOP idle object evictor.
098     *<p>
099     * Note: This class has a natural ordering that is inconsistent with
100     *       equals if distinct objects have the same identity hash code.
101     * <p>
102     * {@inheritDoc}
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     * Attempt 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 if 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    /**
173     * Record the current stack trace as the last time the object was used.
174     */
175    void use();
176
177    /**
178     * Prints the stack trace of the code that borrowed this pooled object and
179     * the stack trace of the last code to use this object (if available) to
180     * the supplied writer.
181     *
182     * @param   writer  The destination for the debug output
183     */
184    void printStackTrace(PrintWriter writer);
185
186    /**
187     * Returns the state of this object.
188     * @return state
189     */
190    PooledObjectState getState();
191
192    /**
193     * Marks the pooled object as abandoned.
194     */
195    void markAbandoned();
196
197    /**
198     * Marks the object as returning to the pool.
199     */
200    void markReturning();
201
202    // TODO: Uncomment this for version 3 (can't add it to 2.x as it will break
203    //       API compatibility)
204    ///**
205    // * Get the number of times this object has been borrowed.
206    // */
207    //long getBorrowedCount();
208}