View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.pool2;
18  
19  import java.io.PrintWriter;
20  import java.time.Duration;
21  import java.time.Instant;
22  import java.util.Deque;
23  
24  /**
25   * Defines the wrapper that is used to track the additional information, such as
26   * state, for the pooled objects.
27   * <p>
28   * Implementations of this class are required to be thread-safe.
29   * </p>
30   *
31   * @param <T> the type of object in the pool.
32   * @since 2.0
33   */
34  public interface PooledObject<T> extends Comparable<PooledObject<T>> {
35  
36      /**
37       * Tests whether the given PooledObject is null <em>or</em> contains a null.
38       *
39       * @param pooledObject the PooledObject to test.
40       * @return whether the given PooledObject is null <em>or</em> contains a null.
41       * @since 2.12.0
42       */
43      static boolean isNull(final PooledObject<?> pooledObject) {
44          return pooledObject == null || pooledObject.getObject() == null;
45      }
46  
47      /**
48       * Allocates the object.
49       *
50       * @return {@code true} if the original state was {@link PooledObjectState#IDLE IDLE}
51       */
52      boolean allocate();
53  
54      /**
55       * Orders instances based on idle time - i.e. the length of time since the
56       * instance was returned to the pool. Used by the GKOP idle object evictor.
57       * <p>
58       * Note: This class has a natural ordering that is inconsistent with
59       *       equals if distinct objects have the same identity hash code.
60       * </p>
61       * <p>
62       * {@inheritDoc}
63       * </p>
64       */
65      @Override
66      int compareTo(PooledObject<T> other);
67  
68      /**
69       * Deallocates the object and sets it {@link PooledObjectState#IDLE IDLE}
70       * if it is currently {@link PooledObjectState#ALLOCATED ALLOCATED}.
71       *
72       * @return {@code true} if the state was {@link PooledObjectState#ALLOCATED ALLOCATED}.
73       */
74      boolean deallocate();
75  
76      /**
77       * Notifies the object that the eviction test has ended.
78       *
79       * @param idleQueue The queue of idle objects to which the object should be
80       *                  returned.
81       * @return  Currently not used.
82       */
83      boolean endEvictionTest(Deque<PooledObject<T>> idleQueue);
84  
85      @Override
86      boolean equals(Object obj);
87  
88      /**
89       * Gets the amount of time this object last spent in the active state (it may still be active in which case
90       * subsequent calls will return an increased value).
91       *
92       * @return The duration last spent in the active state.
93       * @since 2.11.0
94       */
95      default Duration getActiveDuration() {
96          // Take copies to avoid threading issues
97          final Instant lastReturnInstant = getLastReturnInstant();
98          final Instant lastBorrowInstant = getLastBorrowInstant();
99          // @formatter:off
100         return lastReturnInstant.isAfter(lastBorrowInstant) ?
101                 Duration.between(lastBorrowInstant, lastReturnInstant) :
102                 Duration.between(lastBorrowInstant, Instant.now());
103         // @formatter:on
104     }
105 
106     /**
107      * Gets the amount of time this object last spent in the active state (it may still be active in which case
108      * subsequent calls will return an increased value).
109      *
110      * @return The duration last spent in the active state.
111      * @since 2.10.0
112      * @deprecated Use {@link #getActiveDuration()}.
113      */
114     @Deprecated
115     default Duration getActiveTime() {
116         return getActiveDuration();
117     }
118 
119     /**
120      * Gets the amount of time in milliseconds this object last spent in the
121      * active state (it may still be active in which case subsequent calls will
122      * return an increased value).
123      *
124      * @return The time in milliseconds last spent in the active state.
125      * @deprecated Use {@link #getActiveTime()} which offers the best precision.
126      */
127     @Deprecated
128     long getActiveTimeMillis();
129 
130     /**
131      * Gets the number of times this object has been borrowed.
132      *
133      * @return -1 by default for implementations prior to release 2.7.0.
134      * @since 2.7.0
135      */
136     default long getBorrowedCount() {
137         return -1;
138     }
139 
140     /**
141      * Gets the time (using the same basis as {@link Instant#now()}) that this object was created.
142      *
143      * @return The creation time for the wrapped object.
144      * @since 2.11.0
145      */
146     default Instant getCreateInstant() {
147         return Instant.ofEpochMilli(getCreateTime());
148     }
149 
150     /**
151      * Gets the time (using the same basis as
152      * {@link java.time.Clock#instant()}) that this object was created.
153      *
154      * @return The creation time for the wrapped object.
155      * @deprecated Use {@link #getCreateInstant()} which offers the best precision.
156      */
157     @Deprecated
158     long getCreateTime();
159 
160     /**
161      * Gets the duration since this object was created (using {@link Instant#now()}).
162      *
163      * @return The duration since this object was created.
164      * @since 2.12.0
165      */
166     default Duration getFullDuration() {
167         return Duration.between(getCreateInstant(), Instant.now());
168     }
169 
170     /**
171      * Gets the amount of time that this object last spend in the
172      * idle state (it may still be idle in which case subsequent calls will
173      * return an increased value).
174      *
175      * @return The amount of time in last spent in the idle state.
176      * @since 2.11.0
177      */
178     default Duration getIdleDuration() {
179         return Duration.ofMillis(getIdleTimeMillis());
180     }
181 
182     /**
183      * Gets the amount of time that this object last spend in the
184      * idle state (it may still be idle in which case subsequent calls will
185      * return an increased value).
186      *
187      * @return The amount of time in last spent in the idle state.
188      * @since 2.10.0
189      * @deprecated Use {@link #getIdleDuration()}.
190      */
191     @Deprecated
192     default Duration getIdleTime() {
193         return Duration.ofMillis(getIdleTimeMillis());
194     }
195 
196     /**
197      * Gets the amount of time in milliseconds that this object last spend in the
198      * idle state (it may still be idle in which case subsequent calls will
199      * return an increased value).
200      *
201      * @return The time in milliseconds last spent in the idle state.
202      * @deprecated Use {@link #getIdleTime()} which offers the best precision.
203      */
204     @Deprecated
205     long getIdleTimeMillis();
206 
207     /**
208      * Gets the time the wrapped object was last borrowed.
209      *
210      * @return The time the object was last borrowed.
211      * @since 2.11.0
212      */
213     default Instant getLastBorrowInstant() {
214         return Instant.ofEpochMilli(getLastBorrowTime());
215     }
216 
217     /**
218      * Gets the time the wrapped object was last borrowed.
219      *
220      * @return The time the object was last borrowed.
221      * @deprecated Use {@link #getLastBorrowInstant()} which offers the best precision.
222      */
223     @Deprecated
224     long getLastBorrowTime();
225 
226     /**
227      * Gets the time the wrapped object was last borrowed.
228      *
229      * @return The time the object was last borrowed.
230      * @since 2.11.0
231      */
232     default Instant getLastReturnInstant() {
233         return Instant.ofEpochMilli(getLastReturnTime());
234     }
235 
236     /**
237      * Gets the time the wrapped object was last returned.
238      *
239      * @return The time the object was last returned.
240      * @deprecated Use {@link #getLastReturnInstant()} which offers the best precision.
241      */
242     @Deprecated
243     long getLastReturnTime();
244 
245     /**
246      * Gets an estimate of the last time this object was used. If the class of the pooled object implements
247      * {@link TrackedUse}, what is returned is the maximum of {@link TrackedUse#getLastUsedInstant()} and
248      * {@link #getLastBorrowTime()}; otherwise this method gives the same value as {@link #getLastBorrowTime()}.
249      *
250      * @return the last time this object was used
251      * @since 2.11.0
252      */
253     default Instant getLastUsedInstant() {
254         return Instant.ofEpochMilli(getLastUsedTime());
255     }
256 
257     /**
258      * Gets an estimate of the last time this object was used.  If the class
259      * of the pooled object implements {@link TrackedUse}, what is returned is
260      * the maximum of {@link TrackedUse#getLastUsedInstant()} and
261      * {@link #getLastBorrowTime()}; otherwise this method gives the same
262      * value as {@link #getLastBorrowTime()}.
263      *
264      * @return the last time this object was used.
265      * @deprecated Use {@link #getLastUsedInstant()} which offers the best precision.
266      */
267     @Deprecated
268     long getLastUsedTime();
269 
270     /**
271      * Gets the underlying object that is wrapped by this instance of
272      * {@link PooledObject}.
273      *
274      * @return The wrapped object.
275      */
276     T getObject();
277 
278     /**
279      * Gets the state of this object.
280      *
281      * @return state
282      */
283     PooledObjectState getState();
284 
285     @Override
286     int hashCode();
287 
288     /**
289      * Sets the state to {@link PooledObjectState#INVALID INVALID}.
290      */
291     void invalidate();
292 
293     /**
294      * Marks the pooled object as abandoned.
295      */
296     void markAbandoned();
297 
298     /**
299      * Marks the object as returning to the pool.
300      */
301     void markReturning();
302 
303     /**
304      * Prints the stack trace of the code that borrowed this pooled object and
305      * the stack trace of the last code to use this object (if available) to
306      * the supplied writer.
307      *
308      * @param   writer  The destination for the debug output.
309      */
310     void printStackTrace(PrintWriter writer);
311 
312     /**
313      * Sets whether to use abandoned object tracking. If this is true the
314      * implementation will need to record the stack trace of the last caller to
315      * borrow this object.
316      *
317      * @param   logAbandoned    The new configuration setting for abandoned
318      *                          object tracking.
319      */
320     void setLogAbandoned(boolean logAbandoned);
321 
322     /**
323      * Sets the stack trace generation strategy based on whether or not fully detailed stack traces are required.
324      * When set to false, abandoned logs may only include caller class information rather than method names, line
325      * numbers, and other normal metadata available in a full stack trace.
326      *
327      * @param requireFullStackTrace the new configuration setting for abandoned object logging.
328      * @since 2.7.0
329      */
330     default void setRequireFullStackTrace(final boolean requireFullStackTrace) {
331         // noop
332     }
333 
334     /**
335      * Attempts to place the pooled object in the
336      * {@link PooledObjectState#EVICTION} state.
337      *
338      * @return {@code true} if the object was placed in the
339      *         {@link PooledObjectState#EVICTION} state otherwise
340      *         {@code false}.
341      */
342     boolean startEvictionTest();
343 
344     /**
345      * Gets a String form of the wrapper for debug purposes. The format is
346      * not fixed and may change at any time.
347      *
348      * {@inheritDoc}
349      */
350     @Override
351     String toString();
352 
353     /**
354      * Records the current stack trace as the last time the object was used.
355      */
356     void use();
357 
358 }