This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-dbcp.git
The following commit(s) were added to refs/heads/master by this push:
new c1e2e5ad Fix Javadoc warnings (Java 17+)
c1e2e5ad is described below
commit c1e2e5ad5b42a2df457d8ac967fdba9484aa5752
Author: Gary D. Gregory <garydgreg...@gmail.com>
AuthorDate: Sat Feb 1 11:06:30 2025 -0500
Fix Javadoc warnings (Java 17+)
---
.../apache/commons/dbcp2/DelegatingConnection.java | 5 ++
.../commons/dbcp2/DelegatingPreparedStatement.java | 7 ++-
.../apache/commons/dbcp2/DelegatingResultSet.java | 6 ++
.../apache/commons/dbcp2/DelegatingStatement.java | 26 ++++++++
.../org/apache/commons/dbcp2/ListException.java | 3 +
.../org/apache/commons/dbcp2/SQLExceptionList.java | 4 ++
.../dbcp2/cpdsadapter/DriverAdapterCPDS.java | 15 ++++-
.../dbcp2/datasources/InstanceKeyDataSource.java | 72 ++++++++++++++++++++--
8 files changed, 129 insertions(+), 9 deletions(-)
diff --git a/src/main/java/org/apache/commons/dbcp2/DelegatingConnection.java
b/src/main/java/org/apache/commons/dbcp2/DelegatingConnection.java
index 1ad95be1..b565589f 100644
--- a/src/main/java/org/apache/commons/dbcp2/DelegatingConnection.java
+++ b/src/main/java/org/apache/commons/dbcp2/DelegatingConnection.java
@@ -167,6 +167,11 @@ public class DelegatingConnection<C extends Connection>
extends AbandonedTrace i
}
}
+ /**
+ * Closes the underlying connection for {@link #close()}.
+ *
+ * @throws SQLException SQLException if a database access error occurs.
+ */
protected final void closeInternal() throws SQLException {
try {
passivate();
diff --git
a/src/main/java/org/apache/commons/dbcp2/DelegatingPreparedStatement.java
b/src/main/java/org/apache/commons/dbcp2/DelegatingPreparedStatement.java
index 527d4cc3..41d7459a 100644
--- a/src/main/java/org/apache/commons/dbcp2/DelegatingPreparedStatement.java
+++ b/src/main/java/org/apache/commons/dbcp2/DelegatingPreparedStatement.java
@@ -167,10 +167,14 @@ public class DelegatingPreparedStatement extends
DelegatingStatement implements
}
}
+ /**
+ * Prepares internal states before calling {@link #passivate()}.
+ *
+ * @throws SQLException Thrown closing a traced resource or calling {@link
#passivate()}.
+ */
protected void prepareToReturn() throws SQLException {
setClosedInternal(true);
removeThisTrace(getConnectionInternal());
-
// The JDBC spec requires that a statement close any open
// ResultSet's when it is closed.
// FIXME The PreparedStatement we're wrapping should handle this for
us.
@@ -184,7 +188,6 @@ public class DelegatingPreparedStatement extends
DelegatingStatement implements
throw new SQLExceptionList(thrownList);
}
}
-
super.passivate();
}
diff --git a/src/main/java/org/apache/commons/dbcp2/DelegatingResultSet.java
b/src/main/java/org/apache/commons/dbcp2/DelegatingResultSet.java
index 14ab6c7e..3eca664f 100644
--- a/src/main/java/org/apache/commons/dbcp2/DelegatingResultSet.java
+++ b/src/main/java/org/apache/commons/dbcp2/DelegatingResultSet.java
@@ -1045,6 +1045,12 @@ public final class DelegatingResultSet extends
AbandonedTrace implements ResultS
}
}
+ /**
+ * Handles a SQL exception by delegating to a DelegatingStatement or
DelegatingConnection.
+ *
+ * @param e The exception to handle.
+ * @throws SQLException Throws the given exception if not handled.
+ */
protected void handleException(final SQLException e) throws SQLException {
if (statement instanceof DelegatingStatement) {
((DelegatingStatement) statement).handleException(e);
diff --git a/src/main/java/org/apache/commons/dbcp2/DelegatingStatement.java
b/src/main/java/org/apache/commons/dbcp2/DelegatingStatement.java
index df4b2115..47f96bcf 100644
--- a/src/main/java/org/apache/commons/dbcp2/DelegatingStatement.java
+++ b/src/main/java/org/apache/commons/dbcp2/DelegatingStatement.java
@@ -93,6 +93,11 @@ public class DelegatingStatement extends AbandonedTrace
implements Statement {
}
}
+ /**
+ * Checks whether this instance is closed and throws an exception if it is.
+ *
+ * @throws SQLException Thrown if this instance is closed.
+ */
protected void checkOpen() throws SQLException {
if (isClosed()) {
throw new SQLException(this.getClass().getName() + " with address:
\"" + toString() + "\" is closed.");
@@ -391,6 +396,11 @@ public class DelegatingStatement extends AbandonedTrace
implements Statement {
return getConnectionInternal(); // return the delegating connection
that created this
}
+ /**
+ * Gets the internal connection.
+ *
+ * @return the internal connection.
+ */
protected DelegatingConnection<?> getConnectionInternal() {
return connection;
}
@@ -616,6 +626,12 @@ public class DelegatingStatement extends AbandonedTrace
implements Statement {
}
}
+ /**
+ * Delegates the exception to the internal connection if set, otherwise
rethrows it.
+ *
+ * @param e The exception to handle.
+ * @throws SQLException The given exception if not handled.
+ */
protected void handleException(final SQLException e) throws SQLException {
if (connection == null) {
throw e;
@@ -631,6 +647,11 @@ public class DelegatingStatement extends AbandonedTrace
implements Statement {
return closed;
}
+ /**
+ * Tests whether this instance is closed.
+ *
+ * @return whether this instance is closed.
+ */
protected boolean isClosedInternal() {
return closed;
}
@@ -680,6 +701,11 @@ public class DelegatingStatement extends AbandonedTrace
implements Statement {
}
}
+ /**
+ * Sets the closed internal state.
+ *
+ * @param closed whether the instance is now closed.
+ */
protected void setClosedInternal(final boolean closed) {
this.closed = closed;
}
diff --git a/src/main/java/org/apache/commons/dbcp2/ListException.java
b/src/main/java/org/apache/commons/dbcp2/ListException.java
index ba5047bb..23835340 100644
--- a/src/main/java/org/apache/commons/dbcp2/ListException.java
+++ b/src/main/java/org/apache/commons/dbcp2/ListException.java
@@ -27,6 +27,9 @@ public class ListException extends Exception {
private static final long serialVersionUID = 1L;
+ /**
+ * A list of causes.
+ */
private final List<Throwable> exceptionList;
/**
diff --git a/src/main/java/org/apache/commons/dbcp2/SQLExceptionList.java
b/src/main/java/org/apache/commons/dbcp2/SQLExceptionList.java
index b9277bdc..b5b12d92 100644
--- a/src/main/java/org/apache/commons/dbcp2/SQLExceptionList.java
+++ b/src/main/java/org/apache/commons/dbcp2/SQLExceptionList.java
@@ -31,6 +31,10 @@ import java.util.List;
public class SQLExceptionList extends SQLException {
private static final long serialVersionUID = 1L;
+
+ /**
+ * The list of causes.
+ */
private final List<? extends Throwable> causeList;
/**
diff --git
a/src/main/java/org/apache/commons/dbcp2/cpdsadapter/DriverAdapterCPDS.java
b/src/main/java/org/apache/commons/dbcp2/cpdsadapter/DriverAdapterCPDS.java
index b5cc18a9..0cf27ff2 100644
--- a/src/main/java/org/apache/commons/dbcp2/cpdsadapter/DriverAdapterCPDS.java
+++ b/src/main/java/org/apache/commons/dbcp2/cpdsadapter/DriverAdapterCPDS.java
@@ -134,13 +134,22 @@ public class DriverAdapterCPDS implements
ConnectionPoolDataSource, Referenceabl
/** Log stream. NOT USED */
private transient PrintWriter logWriter;
- // PreparedStatement pool properties
+ /** PreparedStatement pool property defaults to false. */
private boolean poolPreparedStatements;
+
+ /** PreparedStatement pool property defaults to 10. */
private int maxIdle = 10;
+
+ /** PreparedStatement pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_DURATION_BETWEEN_EVICTION_RUNS}. */
private Duration durationBetweenEvictionRuns =
BaseObjectPoolConfig.DEFAULT_DURATION_BETWEEN_EVICTION_RUNS;
+
+ /** PreparedStatement pool property defaults to -1. */
private int numTestsPerEvictionRun = -1;
+
+ /** PreparedStatement pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_MIN_EVICTABLE_IDLE_DURATION}. */
private Duration minEvictableIdleDuration =
BaseObjectPoolConfig.DEFAULT_MIN_EVICTABLE_IDLE_DURATION;
+ /** Maximum number of prepared statements, defaults to -1, meaning no
limit. */
private int maxPreparedStatements = -1;
/** Whether or not getConnection has been called */
@@ -248,7 +257,7 @@ public class DriverAdapterCPDS implements
ConnectionPoolDataSource, Referenceabl
/**
* Gets the maximum number of prepared statements.
*
- * @return maxPrepartedStatements value
+ * @return maxPrepartedStatements, defaults to -1, meaning no limit.
*/
public int getMaxPreparedStatements() {
return maxPreparedStatements;
@@ -658,7 +667,7 @@ public class DriverAdapterCPDS implements
ConnectionPoolDataSource, Referenceabl
/**
* Sets the maximum number of prepared statements.
*
- * @param maxPreparedStatements the new maximum number of prepared
statements
+ * @param maxPreparedStatements the new maximum number of prepared
statements, <= 0 means no limit.
*/
public void setMaxPreparedStatements(final int maxPreparedStatements) {
this.maxPreparedStatements = maxPreparedStatements;
diff --git
a/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSource.java
b/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSource.java
index 85d99e64..ba537dcc 100644
---
a/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSource.java
+++
b/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSource.java
@@ -111,32 +111,70 @@ public abstract class InstanceKeyDataSource implements
DataSource, Referenceable
/** Instance key */
private String instanceKey;
- // Pool properties
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_BLOCK_WHEN_EXHAUSTED}. */
private boolean defaultBlockWhenExhausted =
BaseObjectPoolConfig.DEFAULT_BLOCK_WHEN_EXHAUSTED;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_EVICTION_POLICY_CLASS_NAME}. */
private String defaultEvictionPolicyClassName =
BaseObjectPoolConfig.DEFAULT_EVICTION_POLICY_CLASS_NAME;
+
+ /** Pool property defaults to {@link BaseObjectPoolConfig#DEFAULT_LIFO}. */
private boolean defaultLifo = BaseObjectPoolConfig.DEFAULT_LIFO;
+
+ /** Pool property defaults to {@link
GenericKeyedObjectPoolConfig#DEFAULT_MAX_IDLE_PER_KEY}. */
private int defaultMaxIdle =
GenericKeyedObjectPoolConfig.DEFAULT_MAX_IDLE_PER_KEY;
+
+ /** Pool property defaults to {@link
GenericKeyedObjectPoolConfig#DEFAULT_MAX_TOTAL}. */
private int defaultMaxTotal =
GenericKeyedObjectPoolConfig.DEFAULT_MAX_TOTAL;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_MAX_WAIT}. */
private Duration defaultMaxWaitDuration =
BaseObjectPoolConfig.DEFAULT_MAX_WAIT;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_MIN_EVICTABLE_IDLE_DURATION}. */
private Duration defaultMinEvictableIdleDuration =
BaseObjectPoolConfig.DEFAULT_MIN_EVICTABLE_IDLE_DURATION;
+
+ /** Pool property defaults to {@link
GenericKeyedObjectPoolConfig#DEFAULT_MIN_IDLE_PER_KEY}. */
private int defaultMinIdle =
GenericKeyedObjectPoolConfig.DEFAULT_MIN_IDLE_PER_KEY;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_NUM_TESTS_PER_EVICTION_RUN}. */
private int defaultNumTestsPerEvictionRun =
BaseObjectPoolConfig.DEFAULT_NUM_TESTS_PER_EVICTION_RUN;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_SOFT_MIN_EVICTABLE_IDLE_DURATION}. */
private Duration defaultSoftMinEvictableIdleDuration =
BaseObjectPoolConfig.DEFAULT_SOFT_MIN_EVICTABLE_IDLE_DURATION;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_TEST_ON_CREATE}. */
private boolean defaultTestOnCreate =
BaseObjectPoolConfig.DEFAULT_TEST_ON_CREATE;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_TEST_ON_BORROW}. */
private boolean defaultTestOnBorrow =
BaseObjectPoolConfig.DEFAULT_TEST_ON_BORROW;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_TEST_ON_RETURN}. */
private boolean defaultTestOnReturn =
BaseObjectPoolConfig.DEFAULT_TEST_ON_RETURN;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_TEST_WHILE_IDLE}. */
private boolean defaultTestWhileIdle =
BaseObjectPoolConfig.DEFAULT_TEST_WHILE_IDLE;
+
+ /** Pool property defaults to {@link
BaseObjectPoolConfig#DEFAULT_DURATION_BETWEEN_EVICTION_RUNS}. */
private Duration defaultDurationBetweenEvictionRuns =
BaseObjectPoolConfig.DEFAULT_DURATION_BETWEEN_EVICTION_RUNS;
- // Connection factory properties
+ /** Connection factory property defaults to null. */
private String validationQuery;
+
+ /** Connection factory property defaults to -1 seconds. */
private Duration validationQueryTimeoutDuration = Duration.ofSeconds(-1);
+
+ /** Connection factory property defaults to false. */
private boolean rollbackAfterValidation;
+
+ /** Connection factory property defaults to -1 milliseconds. */
private Duration maxConnDuration = Duration.ofMillis(-1);
- // Connection properties
+ /** Connection property defaults to false. */
private Boolean defaultAutoCommit;
+
+ /** Connection property defaults to {@link #UNKNOWN_TRANSACTIONISOLATION}.
*/
private int defaultTransactionIsolation = UNKNOWN_TRANSACTIONISOLATION;
+
+ /** Connection property defaults to false. */
private Boolean defaultReadOnly;
/**
@@ -269,6 +307,12 @@ public abstract class InstanceKeyDataSource implements
DataSource, Referenceable
}
}
+ /**
+ * Gets the pooled connection manager for the given key.
+ *
+ * @param upkey the key.
+ * @return the pooled connection manager for the given key.
+ */
protected abstract PooledConnectionManager
getConnectionManager(UserPassKey upkey);
/**
@@ -1155,6 +1199,13 @@ public abstract class InstanceKeyDataSource implements
DataSource, Referenceable
this.rollbackAfterValidation = rollbackAfterValidation;
}
+ /**
+ * Sets up the defaults for a given connection.
+ *
+ * @param connection The target connection.
+ * @param userName The user name for the connection.
+ * @throws SQLException if a database access error occurs or this method
is called on a closed connection
+ */
protected abstract void setupDefaults(Connection connection, String
userName) throws SQLException;
/**
@@ -1193,6 +1244,15 @@ public abstract class InstanceKeyDataSource implements
DataSource, Referenceable
this.validationQueryTimeoutDuration =
Duration.ofSeconds(validationQueryTimeoutSeconds);
}
+ /**
+ * Tests and returns whether a JNDI context can be created to lookup a
ConnectionPoolDataSource to then access a PooledConnection connection.
+ *
+ * @param userName An optional user name, may be null.
+ * @param userPassword An optional user user password, may be null.
+ * @return A ConnectionPoolDataSource from a JNDI context.
+ * @throws javax.naming.NamingException if a naming exception is
encountered.
+ * @throws SQLException if a ConnectionPoolDataSource or
PooledConnection is not available.
+ */
protected ConnectionPoolDataSource testCPDS(final String userName, final
String userPassword)
throws javax.naming.NamingException, SQLException {
// The source of physical database connections
@@ -1211,7 +1271,6 @@ public abstract class InstanceKeyDataSource implements
DataSource, Referenceable
}
cpds = (ConnectionPoolDataSource) ds;
}
-
// try to get a connection with the supplied userName/password
PooledConnection conn = null;
try {
@@ -1247,6 +1306,11 @@ public abstract class InstanceKeyDataSource implements
DataSource, Referenceable
return builder.toString();
}
+ /**
+ * Appends this instance's fields to a string builder.
+ *
+ * @param builder the target string builder.
+ */
protected void toStringFields(final StringBuilder builder) {
builder.append("getConnectionCalled=");
builder.append(getConnectionCalled);
