This is an automated email from the ASF dual-hosted git repository. rmaucher pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit cf9d9ab24d5a76657ccf1ba0840a4021e2051078 Author: opencode <[email protected]> AuthorDate: Wed Oct 28 14:40:47 2026 +0100 Correct the PoolConfiguration contract for isPoolSweeperEnabled() The javadoc of the interface method documented a derivation formula that no longer matched the shipped implementation: it omitted the suspectTimeout, minEvictableIdleTimeMillis and maxAge triggers, it included a validationQuery non-null condition for testWhileIdle that the code does not have, and it OR-ed the testWhileIdle clause without the timeBetweenEvictionRunsMillis gate that gates every real trigger. It also implied the sweeper was off by default, while the shipped derivation is true with the stock defaults, so the background cleaner and its side effects - the implicit per-connection lock and the idle pool being kept beyond maxIdle - are active out of the box. Third-party PoolConfiguration implementations written against the documented formula therefore silently lose idle eviction, maxAge reconnects and suspect detection whenever only one of the undocumented triggers drives the maintenance. Replace the documented snippet with the current derivation, matching PoolProperties.isPoolSweeperEnabled() verbatim, state that the sweeper is enabled with the shipped defaults, and spell out what the cleaner does and what the flag changes for the rest of the pool. --- .../apache/tomcat/jdbc/pool/PoolConfiguration.java | 23 ++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java b/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java index a7358d5863..065442aa8f 100644 --- a/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java +++ b/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java @@ -672,13 +672,28 @@ public interface PoolConfiguration { /** * Returns true if the pool sweeper is enabled for the connection pool. - * The pool sweeper is enabled if any settings that require async intervention in the pool are turned on + * The pool sweeper is enabled if any settings that require async intervention in the pool are turned on. + * Implementations are expected to run the background maintenance whenever * <code> - * boolean result = getTimeBetweenEvictionRunsMillis()>0; - * result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0); - * result = result || (isTestWhileIdle() && getValidationQuery()!=null); + * boolean timer = getTimeBetweenEvictionRunsMillis()>0; + * boolean result = timer && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0); + * result = result || (timer && getSuspectTimeout()>0); + * result = result || (timer && isTestWhileIdle()); + * result = result || (timer && getMinEvictableIdleTimeMillis()>0); + * result = result || (timer && getMaxAge()>0); * return result; * </code> + * so enabling the maintenance when any one of these triggers is turned on satisfies the contract. + * With the defaults shipped by {@link PoolProperties} the sweeper is enabled. + * When it runs, the background cleaner thread checks for abandoned connections when + * {@link #isRemoveAbandoned()} is set, marks and reports connections that exceeded + * {@link #getSuspectTimeout()}, evicts idle connections towards + * {@link #getMinIdle()}, validates idle connections when {@link #isTestWhileIdle()} is set and + * reconnects idle connections that exceeded {@link #getMaxAge()}. + * While the sweeper is enabled, the pool also takes the per-connection lock when borrowing and + * returning connections (the same lock {@link #getUseLock()} forces on) and returned connections + * are kept beyond {@link #getMaxIdle()}, letting the idle pool grow towards + * {@link #getMaxActive()} as the cleaner trims it. * * @return true if a background thread is or will be enabled for this pool */ --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
