This is an automated email from the ASF dual-hosted git repository. rmaucher pushed a commit to branch 11.0.x in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit d13f88a02423fd2a488429335116fe3527f3dc9c Author: opencode <[email protected]> AuthorDate: Sun Nov 1 19:40:33 2026 +0100 Clarify the query report hooks' and threshold's documentation The success-path hooks reportQuery() and reportSlowQuery() carried the failure hook's "the query that was executed and failed" wording, their @param name sentences linked isExecute() without a verb, and reportSlowQuery()'s summary said the execution "was exceeded". Correct all three so the hooks document what they are invoked for. StatementProxy described its delegate as "the underlying statement or connection": createStatement() only ever wraps a statement, or a further interceptor's proxy of one, never a connection; the query field holds the SQL the statement was prepared with, which can be null, not the SQL currently executed. Update both field and constructor docs. The elapsedMillis() javadoc stated the clock-skew harm of wall-clock durations in the present tense, though durations come from the monotonic clock and cannot go negative; state it as the counterfactual rationale for that choice that it is. Document on the SlowQueryReport threshold attribute what a negative value does: every execution is recorded as measured and none is reported, so nothing is logged or notified as slow. The copy in webapps/docs is a build artifact of the module's doc file and was updated in the working tree to match. --- modules/jdbc-pool/doc/jdbc-pool.xml | 2 ++ .../jdbc/pool/interceptor/AbstractQueryReport.java | 30 ++++++++++++---------- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/modules/jdbc-pool/doc/jdbc-pool.xml b/modules/jdbc-pool/doc/jdbc-pool.xml index 5ddde5ed27..6670aadd46 100644 --- a/modules/jdbc-pool/doc/jdbc-pool.xml +++ b/modules/jdbc-pool/doc/jdbc-pool.xml @@ -764,6 +764,8 @@ <attributes> <attribute name="threshold" required="false"> <p>(int as String) The number of milliseconds a query has to exceed before issuing a log alert. + A negative value (conventionally <code>-1</code>) records every execution as measured and + reports none as slow, so nothing is ever logged or notified as a slow query. The default value is <code>1000</code> milliseconds. </p> </attribute> diff --git a/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java b/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java index e0e06e15d6..740d2d1363 100644 --- a/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java +++ b/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java @@ -99,7 +99,7 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce * * @param query the query that was executed and failed * @param args the arguments to the execution - * @param name the name of the method used to execute + * @param name the name of the method used to execute, as recognised by * {@link AbstractCreateStatementInterceptor#isExecute(Method, boolean)} * @param start the wall clock time the query execution started * @param delta the time the execution took before it failed, measured with the monotonic clock @@ -118,9 +118,9 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce * {@link AbstractCreateStatementInterceptor#isExecute(Method, boolean)}, succeeded and was within the timing * threshold * - * @param query the query that was executed and failed + * @param query the query that was executed * @param args the arguments to the execution - * @param name the name of the method used to execute + * @param name the name of the method used to execute, as recognised by * {@link AbstractCreateStatementInterceptor#isExecute(Method, boolean)} * @param start the wall clock time the query execution started * @param delta the time the execution took, measured with the monotonic clock @@ -134,12 +134,12 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce /** * Invoked when a query execution, a call to an execute method as recognised by - * {@link AbstractCreateStatementInterceptor#isExecute(Method, boolean)}, succeeded and was exceeded the timing + * {@link AbstractCreateStatementInterceptor#isExecute(Method, boolean)}, succeeded and exceeded the timing * threshold * - * @param query the query that was executed and failed + * @param query the query that was executed * @param args the arguments to the execution - * @param name the name of the method used to execute + * @param name the name of the method used to execute, as recognised by * {@link AbstractCreateStatementInterceptor#isExecute(Method, boolean)} * @param start the wall clock time the query execution started * @param delta the time the execution took, measured with the monotonic clock @@ -224,9 +224,11 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce * Measures the milliseconds elapsed since the {@link System#nanoTime()} * reading taken at {@code startNanos}, rounded to the nearest millisecond. * <p> - * An interval is measured with the monotonic clock. The wall clock is not monotonic, so an NTP correction, a manual - * set, or resuming a suspended VM between two of its readings makes their difference negative, and a negative - * duration is never over the slow query threshold while the statistics book it as if it were real. + * An interval is measured with the monotonic clock. Had it been measured + * with the wall clock instead, an NTP correction, a manual set, or + * resuming a suspended VM between the two readings could have made the + * difference negative, and a negative duration is never over the slow + * query threshold while the statistics book it as if it were real. * </p> * * @param startNanos the {@link System#nanoTime()} reading the measurement began with @@ -249,20 +251,20 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce */ protected volatile boolean closed = false; /** - * The underlying statement or connection being proxied, nulled once a close has been forwarded. It is read by - * threads other than the one that nulls it, so, like {@link #closed}, volatile. + * The statement being proxied, or a further interceptor's proxy of it, nulled once a close has been forwarded. + * It is read by threads other than the one that nulls it, so, like {@link #closed}, volatile. */ protected volatile Object delegate; /** - * The SQL query being executed. + * The SQL the statement was prepared with, or {@code null} when it was created without one. */ protected final String query; /** * Constructs a new {@code StatementProxy}. * - * @param parent The underlying statement or connection - * @param query The SQL query being executed + * @param parent The statement being proxied, or a further interceptor's proxy of it + * @param query The SQL the statement was prepared with, or {@code null} when it was created without one */ public StatementProxy(Object parent, String query) { this.delegate = parent; --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
