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 java.io.PrintWriter;
021
022import org.apache.commons.pool2.TrackedUse;
023import org.apache.commons.pool2.UsageTracking;
024
025/**
026 * Configuration settings for abandoned object removal.
027 *
028 * @version $Revision:$
029 *
030 * @since 2.0
031 */
032public class AbandonedConfig {
033
034    /**
035     * Whether or not borrowObject performs abandoned object removal.
036     */
037    private boolean removeAbandonedOnBorrow = false;
038
039    /**
040     * <p>Flag to remove abandoned objects if they exceed the
041     * removeAbandonedTimeout when borrowObject is invoked.</p>
042     *
043     * <p>The default value is false.</p>
044     *
045     * <p>If set to true, abandoned objects are removed by borrowObject if
046     * there are fewer than 2 idle objects available in the pool and
047     * <code>getNumActive() &gt; getMaxTotal() - 3</code></p>
048     *
049     * @return true if abandoned objects are to be removed by borrowObject
050     */
051    public boolean getRemoveAbandonedOnBorrow() {
052        return this.removeAbandonedOnBorrow;
053    }
054
055    /**
056     * <p>Flag to remove abandoned objects if they exceed the
057     * removeAbandonedTimeout when borrowObject is invoked.</p>
058     *
059     * @param removeAbandonedOnBorrow true means abandoned objects will be
060     *   removed by borrowObject
061     * @see #getRemoveAbandonedOnBorrow()
062     */
063    public void setRemoveAbandonedOnBorrow(boolean removeAbandonedOnBorrow) {
064        this.removeAbandonedOnBorrow = removeAbandonedOnBorrow;
065    }
066
067    /**
068     * Whether or not pool maintenance (evictor) performs abandoned object
069     * removal.
070     */
071    private boolean removeAbandonedOnMaintenance = false;
072
073    /**
074     * <p>Flag to remove abandoned objects if they exceed the
075     * removeAbandonedTimeout when pool maintenance (the "evictor")
076     * runs.</p>
077     *
078     * <p>The default value is false.</p>
079     *
080     * <p>If set to true, abandoned objects are removed by the pool
081     * maintenance thread when it runs.  This setting has no effect
082     * unless maintenance is enabled by setting
083     *{@link GenericObjectPool#getTimeBetweenEvictionRunsMillis() timeBetweenEvictionRunsMillis}
084     * to a positive number.</p>
085     *
086     * @return true if abandoned objects are to be removed by the evictor
087     */
088    public boolean getRemoveAbandonedOnMaintenance() {
089        return this.removeAbandonedOnMaintenance;
090    }
091
092    /**
093     * <p>Flag to remove abandoned objects if they exceed the
094     * removeAbandonedTimeout when pool maintenance runs.</p>
095     *
096     * @param removeAbandonedOnMaintenance true means abandoned objects will be
097     *   removed by pool maintenance
098     * @see #getRemoveAbandonedOnMaintenance
099     */
100    public void setRemoveAbandonedOnMaintenance(boolean removeAbandonedOnMaintenance) {
101        this.removeAbandonedOnMaintenance = removeAbandonedOnMaintenance;
102    }
103
104    /**
105     * Timeout in seconds before an abandoned object can be removed.
106     */
107    private int removeAbandonedTimeout = 300;
108
109    /**
110     * <p>Timeout in seconds before an abandoned object can be removed.</p>
111     *
112     * <p>The time of most recent use of an object is the maximum (latest) of
113     * {@link TrackedUse#getLastUsed()} (if this class of the object implements
114     * TrackedUse) and the time when the object was borrowed from the pool.</p>
115     *
116     * <p>The default value is 300 seconds.</p>
117     *
118     * @return the abandoned object timeout in seconds
119     */
120    public int getRemoveAbandonedTimeout() {
121        return this.removeAbandonedTimeout;
122    }
123
124    /**
125     * <p>Sets the timeout in seconds before an abandoned object can be
126     * removed</p>
127     *
128     * <p>Setting this property has no effect if
129     * {@link #getRemoveAbandonedOnBorrow() removeAbandonedOnBorrow} and
130     * {@link #getRemoveAbandonedOnMaintenance() removeAbandonedOnMaintenance}
131     * are both false.</p>
132     *
133     * @param removeAbandonedTimeout new abandoned timeout in seconds
134     * @see #getRemoveAbandonedTimeout()
135     */
136    public void setRemoveAbandonedTimeout(int removeAbandonedTimeout) {
137        this.removeAbandonedTimeout = removeAbandonedTimeout;
138    }
139
140    /**
141     * Determines whether or not to log stack traces for application code
142     * which abandoned an object.
143     */
144    private boolean logAbandoned = false;
145
146    /**
147     * Flag to log stack traces for application code which abandoned
148     * an object.
149     *
150     * Defaults to false.
151     * Logging of abandoned objects adds overhead for every object created
152     * because a stack trace has to be generated.
153     *
154     * @return boolean true if stack trace logging is turned on for abandoned
155     * objects
156     *
157     */
158    public boolean getLogAbandoned() {
159        return this.logAbandoned;
160    }
161
162    /**
163     * Sets the flag to log stack traces for application code which abandoned
164     * an object.
165     *
166     * @param logAbandoned true turns on abandoned stack trace logging
167     * @see #getLogAbandoned()
168     *
169     */
170    public void setLogAbandoned(boolean logAbandoned) {
171        this.logAbandoned = logAbandoned;
172    }
173
174    /**
175     * PrintWriter to use to log information on abandoned objects.
176     * Use of default system encoding is deliberate.
177     */
178    private PrintWriter logWriter = new PrintWriter(System.out);
179
180    /**
181     * Returns the log writer being used by this configuration to log
182     * information on abandoned objects. If not set, a PrintWriter based on
183     * System.out with the system default encoding is used.
184     *
185     * @return log writer in use
186     */
187    public PrintWriter getLogWriter() {
188        return logWriter;
189    }
190
191    /**
192     * Sets the log writer to be used by this configuration to log
193     * information on abandoned objects.
194     *
195     * @param logWriter The new log writer
196     */
197    public void setLogWriter(PrintWriter logWriter) {
198        this.logWriter = logWriter;
199    }
200
201    /**
202     * If the pool implements {@link UsageTracking}, should the pool record a
203     * stack trace every time a method is called on a pooled object and retain
204     * the most recent stack trace to aid debugging of abandoned objects?
205     */
206    private boolean useUsageTracking = false;
207
208    /**
209     * If the pool implements {@link UsageTracking}, should the pool record a
210     * stack trace every time a method is called on a pooled object and retain
211     * the most recent stack trace to aid debugging of abandoned objects?
212     *
213     * @return <code>true</code> if usage tracking is enabled
214     */
215    public boolean getUseUsageTracking() {
216        return useUsageTracking;
217    }
218
219    /**
220     * If the pool implements {@link UsageTracking}, configure whether the pool
221     * should record a stack trace every time a method is called on a pooled
222     * object and retain the most recent stack trace to aid debugging of
223     * abandoned objects.
224     *
225     * @param   useUsageTracking    A value of <code>true</code> will enable
226     *                              the recording of a stack trace on every use
227     *                              of a pooled object
228     */
229    public void setUseUsageTracking(boolean useUsageTracking) {
230        this.useUsageTracking = useUsageTracking;
231    }
232}