Source code

; Wed, 20 Dec 2017 17:04:04 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1022499 [31/40] - in /websites/production/commons/content/proper/commons-pool/api-2.5.0: ./ org/ org/apache/ org/apache/commons/ org/apache/commons/pool2/ org/apache/commons/pool2/class-use/ org/apache/commons/pool2/impl/ org/apache/common... Date: Wed, 20 Dec 2017 17:04:02 -0000 To: notifications@commons.apache.org From: ggregory@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20171220170404.1D30B3A0CEE@svn01-us-west.apache.org> archived-at: Wed, 20 Dec 2017 17:04:12 -0000 Added: websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObject.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObject.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObject.html Wed Dec 20 17:04:00 2017 @@ -0,0 +1,290 @@ + + + +Source code + + + +

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}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + \ No newline at end of file Added: websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObjectFactory.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObjectFactory.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObjectFactory.html Wed Dec 20 17:04:00 2017 @@ -0,0 +1,209 @@ + + + +Source code + + + +

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
+019/**
+020 * An interface defining life-cycle methods for instances to be served by an
+021 * {@link ObjectPool}.
+022 * <p>
+023 * By contract, when an {@link ObjectPool} delegates to a
+024 * {@link PooledObjectFactory},
+025 * <ol>
+026 *  <li>
+027 *   {@link #makeObject} is called whenever a new instance is needed.
+028 *  </li>
+029 *  <li>
+030 *   {@link #activateObject} is invoked on every instance that has been
+031 *   {@link #passivateObject passivated} before it is
+032 *   {@link ObjectPool#borrowObject borrowed} from the pool.
+033 *  </li>
+034 *  <li>
+035 *   {@link #validateObject} may be invoked on {@link #activateObject activated}
+036 *   instances to make sure they can be {@link ObjectPool#borrowObject borrowed}
+037 *   from the pool. {@link #validateObject} may also be used to
+038 *   test an instance being {@link ObjectPool#returnObject returned} to the pool
+039 *   before it is {@link #passivateObject passivated}. It will only be invoked
+040 *   on an activated instance.
+041 *  </li>
+042 *  <li>
+043 *   {@link #passivateObject} is invoked on every instance when it is returned
+044 *   to the pool.
+045 *  </li>
+046 *  <li>
+047 *   {@link #destroyObject} is invoked on every instance when it is being
+048 *   "dropped" from the pool (whether due to the response from
+049 *   {@link #validateObject}, or for reasons specific to the pool
+050 *   implementation.) There is no guarantee that the instance being destroyed
+051 *   will be considered active, passive or in a generally consistent state.
+052 *  </li>
+053 * </ol>
+054 * {@link PooledObjectFactory} must be thread-safe. The only promise
+055 * an {@link ObjectPool} makes is that the same instance of an object will not
+056 * be passed to more than one method of a <code>PoolableObjectFactory</code>
+057 * at a time.
+058 * <p>
+059 * While clients of a {@link KeyedObjectPool} borrow and return instances of
+060 * the underlying value type {@code V}, the factory methods act on instances of
+061 * {@link PooledObject PooledObject&lt;V&gt;}.  These are the object wrappers that
+062 * pools use to track and maintain state information about the objects that
+063 * they manage.
+064 *
+065 * @param <T> Type of element managed in this factory.
+066 *
+067 * @see ObjectPool
+068 *
+069 * @since 2.0
+070 */
+071public interface PooledObjectFactory<T> {
+072  /**
+073   * Create an instance that can be served by the pool and wrap it in a
+074   * {@link PooledObject} to be managed by the pool.
+075   *
+076   * @return a {@code PooledObject} wrapping an instance that can be served by the pool
+077   *
+078   * @throws Exception if there is a problem creating a new instance,
+079   *    this will be propagated to the code requesting an object.
+080   */
+081  PooledObject<T> makeObject() throws Exception;
+082
+083  /**
+084   * Destroys an instance no longer needed by the pool.
+085   * <p>
+086   * It is important for implementations of this method to be aware that there
+087   * is no guarantee about what state <code>obj</code> will be in and the
+088   * implementation should be prepared to handle unexpected errors.
+089   * <p>
+090   * Also, an implementation must take in to consideration that instances lost
+091   * to the garbage collector may never be destroyed.
+092   * </p>
+093   *
+094   * @param p a {@code PooledObject} wrapping the instance to be destroyed
+095   *
+096   * @throws Exception should be avoided as it may be swallowed by
+097   *    the pool implementation.
+098   *
+099   * @see #validateObject
+100   * @see ObjectPool#invalidateObject
+101   */
+102  void destroyObject(PooledObject<T> p) throws Exception;
+103
+104  /**
+105   * Ensures that the instance is safe to be returned by the pool.
+106   *
+107   * @param p a {@code PooledObject} wrapping the instance to be validated
+108   *
+109   * @return <code>false</code> if <code>obj</code> is not valid and should
+110   *         be dropped from the pool, <code>true</code> otherwise.
+111   */
+112  boolean validateObject(PooledObject<T> p);
+113
+114  /**
+115   * Reinitialize an instance to be returned by the pool.
+116   *
+117   * @param p a {@code PooledObject} wrapping the instance to be activated
+118   *
+119   * @throws Exception if there is a problem activating <code>obj</code>,
+120   *    this exception may be swallowed by the pool.
+121   *
+122   * @see #destroyObject
+123   */
+124  void activateObject(PooledObject<T> p) throws Exception;
+125
+126  /**
+127   * Uninitialize an instance to be returned to the idle object pool.
+128   *
+129   * @param p a {@code PooledObject} wrapping the instance to be passivated
+130   *
+131   * @throws Exception if there is a problem passivating <code>obj</code>,
+132   *    this exception may be swallowed by the pool.
+133   *
+134   * @see #destroyObject
+135   */
+136  void passivateObject(PooledObject<T> p) throws Exception;
+137}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + \ No newline at end of file Added: websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObjectState.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObjectState.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/PooledObjectState.html Wed Dec 20 17:04:00 2017 @@ -0,0 +1,158 @@ + + + +Source code + + + +

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
+019/**
+020 * Provides the possible states that a {@link PooledObject} may be in.
+021 *
+022 * @since 2.0
+023 */
+024public enum PooledObjectState {
+025    /**
+026     * In the queue, not in use.
+027     */
+028    IDLE,
+029
+030    /**
+031     * In use.
+032     */
+033    ALLOCATED,
+034
+035    /**
+036     * In the queue, currently being tested for possible eviction.
+037     */
+038    EVICTION,
+039
+040    /**
+041     * Not in the queue, currently being tested for possible eviction. An
+042     * attempt to borrow the object was made while being tested which removed it
+043     * from the queue. It should be returned to the head of the queue once
+044     * eviction testing completes.
+045     * TODO: Consider allocating object and ignoring the result of the eviction
+046     *       test.
+047     */
+048    EVICTION_RETURN_TO_HEAD,
+049
+050    /**
+051     * In the queue, currently being validated.
+052     */
+053    VALIDATION,
+054
+055    /**
+056     * Not in queue, currently being validated. The object was borrowed while
+057     * being validated and since testOnBorrow was configured, it was removed
+058     * from the queue and pre-allocated. It should be allocated once validation
+059     * completes.
+060     */
+061    VALIDATION_PREALLOCATED,
+062
+063    /**
+064     * Not in queue, currently being validated. An attempt to borrow the object
+065     * was made while previously being tested for eviction which removed it from
+066     * the queue. It should be returned to the head of the queue once validation
+067     * completes.
+068     */
+069    VALIDATION_RETURN_TO_HEAD,
+070
+071    /**
+072     * Failed maintenance (e.g. eviction test or validation) and will be / has
+073     * been destroyed
+074     */
+075    INVALID,
+076
+077    /**
+078     * Deemed abandoned, to be invalidated.
+079     */
+080    ABANDONED,
+081
+082    /**
+083     * Returning to the pool.
+084     */
+085    RETURNING
+086}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + \ No newline at end of file Added: websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/SwallowedExceptionListener.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/SwallowedExceptionListener.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/SwallowedExceptionListener.html Wed Dec 20 17:04:00 2017 @@ -0,0 +1,108 @@ + + + +Source code + + + +

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
+019/**
+020 * Pools that unavoidably swallow exceptions may be configured with an instance
+021 * of this listener so the user may receive notification of when this happens.
+022 * The listener should not throw an exception when called but pools calling
+023 * listeners should protect themselves against exceptions anyway.
+024 *
+025 * @since 2.0
+026 */
+027public interface SwallowedExceptionListener {
+028
+029    /**
+030     * This method is called every time the implementation unavoidably swallows
+031     * an exception.
+032     *
+033     * @param e The exception that was swallowed
+034     */
+035    void onSwallowException(Exception e);
+036}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + \ No newline at end of file Added: websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/TrackedUse.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/TrackedUse.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/TrackedUse.html Wed Dec 20 17:04:00 2017 @@ -0,0 +1,108 @@ + + + +Source code + + + +

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
+019/**
+020 * This interface allows pooled objects to make information available about when
+021 * and how they were used available to the object pool. The object pool may, but
+022 * is not required, to use this information to make more informed decisions when
+023 * determining the state of a pooled object - for instance whether or not the
+024 * object has been abandoned.
+025 *
+026 * @since 2.0
+027 */
+028public interface TrackedUse {
+029
+030    /**
+031     * Get the last time this object was used in ms.
+032     *
+033     * @return long time in ms
+034     */
+035    long getLastUsed();
+036}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + \ No newline at end of file Added: websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/UsageTracking.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/UsageTracking.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/UsageTracking.html Wed Dec 20 17:04:00 2017 @@ -0,0 +1,111 @@ + + + +Source code + + + +

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
+019/**
+020 * This interface may be implemented by an object pool to enable clients
+021 * (primarily those clients that wrap pools to provide pools with extended
+022 * features) to provide additional information to the pool relating to object
+023 * using allowing more informed decisions and reporting to be made regarding
+024 * abandoned objects.
+025 *
+026 * @param <T>   The type of object provided by the pool.
+027 *
+028 * @since 2.0
+029 */
+030public interface UsageTracking<T> {
+031
+032    /**
+033     * This method is called every time a pooled object is used to enable the pool to
+034     * better track borrowed objects.
+035     *
+036     * @param pooledObject  The object that is being used
+037     */
+038    void use(T pooledObject);
+039}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + \ No newline at end of file Added: websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/impl/AbandonedConfig.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/impl/AbandonedConfig.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.5.0/src-html/org/apache/commons/pool2/impl/AbandonedConfig.html Wed Dec 20 17:04:00 2017 @@ -0,0 +1,361 @@ + + + +Source code + + + +

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 */
+017
+018package org.apache.commons.pool2.impl;
+019
+020import org.apache.commons.pool2.TrackedUse;
+021import org.apache.commons.pool2.UsageTracking;
+022
+023import java.io.PrintWriter;
+024
+025/**
+026 * Configuration settings for abandoned object removal.
+027 *
+028 * @since 2.0
+029 */
+030public class AbandonedConfig {
+031
+032    /**
+033     * Whether or not borrowObject performs abandoned object removal.
+034     */
+035    private boolean removeAbandonedOnBorrow = false;
+036
+037    /**
+038     * <p>Flag to remove abandoned objects if they exceed the
+039     * removeAbandonedTimeout when borrowObject is invoked.</p>
+040     *
+041     * <p>The default value is false.</p>
+042     *
+043     * <p>If set to true, abandoned objects are removed by borrowObject if
+044     * there are fewer than 2 idle objects available in the pool and
+045     * <code>getNumActive() &gt; getMaxTotal() - 3</code></p>
+046     *
+047     * @return true if abandoned objects are to be removed by borrowObject
+048     */
+049    public boolean getRemoveAbandonedOnBorrow() {
+050        return this.removeAbandonedOnBorrow;
+051    }
+052
+053    /**
+054     * <p>Flag to remove abandoned objects if they exceed the
+055     * removeAbandonedTimeout when borrowObject is invoked.</p>
+056     *
+057     * @param removeAbandonedOnBorrow true means abandoned objects will be
+058     *   removed by borrowObject
+059     * @see #getRemoveAbandonedOnBorrow()
+060     */
+061    public void setRemoveAbandonedOnBorrow(final boolean removeAbandonedOnBorrow) {
+062        this.removeAbandonedOnBorrow = removeAbandonedOnBorrow;
+063    }
+064
+065    /**
+066     * Whether or not pool maintenance (evictor) performs abandoned object
+067     * removal.
+068     */
+069    private boolean removeAbandonedOnMaintenance = false;
+070
+071    /**
+072     * <p>Flag to remove abandoned objects if they exceed the
+073     * removeAbandonedTimeout when pool maintenance (the "evictor")
+074     * runs.</p>
+075     *
+076     * <p>The default value is false.</p>
+077     *
+078     * <p>If set to true, abandoned objects are removed by the pool
+079     * maintenance thread when it runs.  This setting has no effect
+080     * unless maintenance is enabled by setting
+081     *{@link GenericObjectPool#getTimeBetweenEvictionRunsMillis() timeBetweenEvictionRunsMillis}
+082     * to a positive number.</p>
+083     *
+084     * @return true if abandoned objects are to be removed by the evictor
+085     */
+086    public boolean getRemoveAbandonedOnMaintenance() {
+087        return this.removeAbandonedOnMaintenance;
+088    }
+089
+090    /**
+091     * <p>Flag to remove abandoned objects if they exceed the
+092     * removeAbandonedTimeout when pool maintenance runs.</p>
+093     *
+094     * @param removeAbandonedOnMaintenance true means abandoned objects will be
+095     *   removed by pool maintenance
+096     * @see #getRemoveAbandonedOnMaintenance
+097     */
+098    public void setRemoveAbandonedOnMaintenance(final boolean removeAbandonedOnMaintenance) {
+099        this.removeAbandonedOnMaintenance = removeAbandonedOnMaintenance;
+100    }
+101
+102    /**
+103     * Timeout in seconds before an abandoned object can be removed.
+104     */
+105    private int removeAbandonedTimeout = 300;
+106
+107    /**
+108     * <p>Timeout in seconds before an abandoned object can be removed.</p>
+109     *
+110     * <p>The time of most recent use of an object is the maximum (latest) of
+111     * {@link TrackedUse#getLastUsed()} (if this class of the object implements
+112     * TrackedUse) and the time when the object was borrowed from the pool.</p>
+113     *
+114     * <p>The default value is 300 seconds.</p>
+115     *
+116     * @return the abandoned object timeout in seconds
+117     */
+118    public int getRemoveAbandonedTimeout() {
+119        return this.removeAbandonedTimeout;
+120    }
+121
+122    /**
+123     * <p>Sets the timeout in seconds before an abandoned object can be
+124     * removed</p>
+125     *
+126     * <p>Setting this property has no effect if
+127     * {@link #getRemoveAbandonedOnBorrow() removeAbandonedOnBorrow} and
+128     * {@link #getRemoveAbandonedOnMaintenance() removeAbandonedOnMaintenance}
+129     * are both false.</p>
+130     *
+131     * @param removeAbandonedTimeout new abandoned timeout in seconds
+132     * @see #getRemoveAbandonedTimeout()
+133     */
+134    public void setRemoveAbandonedTimeout(final int removeAbandonedTimeout) {
+135        this.removeAbandonedTimeout = removeAbandonedTimeout;
+136    }
+137
+138    /**
+139     * Determines whether or not to log stack traces for application code
+140     * which abandoned an object.
+141     */
+142    private boolean logAbandoned = false;
+143
+144    /**
+145     * Flag to log stack traces for application code which abandoned
+146     * an object.
+147     *
+148     * Defaults to false.
+149     * Logging of abandoned objects adds overhead for every object created
+150     * because a stack trace has to be generated.
+151     *
+152     * @return boolean true if stack trace logging is turned on for abandoned
+153     * objects
+154     *
+155     */
+156    public boolean getLogAbandoned() {
+157        return this.logAbandoned;
+158    }
+159
+160    /**
+161     * Sets the flag to log stack traces for application code which abandoned
+162     * an object.
+163     *
+164     * @param logAbandoned true turns on abandoned stack trace logging
+165     * @see #getLogAbandoned()
+166     *
+167     */
+168    public void setLogAbandoned(final boolean logAbandoned) {
+169        this.logAbandoned = logAbandoned;
+170    }
+171
+172    /**
+173     * Determines whether or not to log full stack traces when logAbandoned is true.
+174     * If disabled, then a faster method for logging stack traces with only class data
+175     * may be used if possible.
+176     *
+177     * @since 2.5
+178     */
+179    private boolean requireFullStackTrace = true;
+180
+181    /**
+182     * Indicates if full stack traces are required when {@link #getLogAbandoned() logAbandoned}
+183     * is true. Defaults to true. Logging of abandoned objects requiring a full stack trace will
+184     * generate an entire stack trace to generate for every object created. If this is disabled,
+185     * a faster but less informative stack walking mechanism may be used if available.
+186     *
+187     * @return true if full stack traces are required for logging abandoned connections, or false
+188     * if abbreviated stack traces are acceptable
+189     * @see CallStack
+190     * @since 2.5
+191     */
+192    public boolean getRequireFullStackTrace() {
+193        return requireFullStackTrace;
+194    }
+195
+196    /**
+197     * Sets the flag to require full stack traces for logging abandoned connections when enabled.
+198     *
+199     * @param requireFullStackTrace indicates whether or not full stack traces are required in
+200     *                              abandoned connection logs
+201     * @see CallStack
+202     * @see #getRequireFullStackTrace()
+203     * @since 2.5
+204     */
+205    public void setRequireFullStackTrace(boolean requireFullStackTrace) {
+206        this.requireFullStackTrace = requireFullStackTrace;
+207    }
+208
+209    /**
+210     * PrintWriter to use to log information on abandoned objects.
+211     * Use of default system encoding is deliberate.
+212     */
+213    private PrintWriter logWriter = new PrintWriter(System.out);
+214
+215    /**
+216     * Returns the log writer being used by this configuration to log
+217     * information on abandoned objects. If not set, a PrintWriter based on
+218     * System.out with the system default encoding is used.
+219     *
+220     * @return log writer in use
+221     */
+222    public PrintWriter getLogWriter() {
+223        return logWriter;
+224    }
+225
+226    /**
+227     * Sets the log writer to be used by this configuration to log
+228     * information on abandoned objects.
+229     *
+230     * @param logWriter The new log writer
+231     */
+232    public void setLogWriter(final PrintWriter logWriter) {
+233        this.logWriter = logWriter;
+234    }
+235
+236    /**
+237     * If the pool implements {@link UsageTracking}, should the pool record a
+238     * stack trace every time a method is called on a pooled object and retain
+239     * the most recent stack trace to aid debugging of abandoned objects?
+240     */
+241    private boolean useUsageTracking = false;
+242
+243    /**
+244     * If the pool implements {@link UsageTracking}, should the pool record a
+245     * stack trace every time a method is called on a pooled object and retain
+246     * the most recent stack trace to aid debugging of abandoned objects?
+247     *
+248     * @return <code>true</code> if usage tracking is enabled
+249     */
+250    public boolean getUseUsageTracking() {
+251        return useUsageTracking;
+252    }
+253
+254    /**
+255     * If the pool implements {@link UsageTracking}, configure whether the pool
+256     * should record a stack trace every time a method is called on a pooled
+257     * object and retain the most recent stack trace to aid debugging of
+258     * abandoned objects.
+259     *
+260     * @param   useUsageTracking    A value of <code>true</code> will enable
+261     *                              the recording of a stack trace on every use
+262     *                              of a pooled object
+263     */
+264    public void setUseUsageTracking(final boolean useUsageTracking) {
+265        this.useUsageTracking = useUsageTracking;
+266    }
+267
+268    /**
+269     * @since 2.4.3
+270     */
+271    @Override
+272    public String toString() {
+273        final StringBuilder builder = new StringBuilder();
+274        builder.append("AbandonedConfig [removeAbandonedOnBorrow=");
+275        builder.append(removeAbandonedOnBorrow);
+276        builder.append(", removeAbandonedOnMaintenance=");
+277        builder.append(removeAbandonedOnMaintenance);
+278        builder.append(", removeAbandonedTimeout=");
+279        builder.append(removeAbandonedTimeout);
+280        builder.append(", logAbandoned=");
+281        builder.append(logAbandoned);
+282        builder.append(", logWriter=");
+283        builder.append(logWriter);
+284        builder.append(", useUsageTracking=");
+285        builder.append(useUsageTracking);
+286        builder.append("]");
+287        return builder.toString();
+288    }
+289}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + \ No newline at end of file