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
commit 4157240c1aa560eaec3b22bd7a95ede5f1adfa1d
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Sat Nov 23 17:17:22 2024 -0500
Add missing Javadoc and missing Javadoc elements
---
.../apache/commons/dbcp2/DelegatingConnection.java | 19 +++-
.../apache/commons/dbcp2/PoolableConnection.java | 6 +-
.../commons/dbcp2/PoolableConnectionFactory.java | 58 ++++++++--
.../commons/dbcp2/PoolableConnectionMXBean.java | 124 +++++++++++++++++++++
.../apache/commons/dbcp2/PoolingDataSource.java | 5 +
.../org/apache/commons/dbcp2/PoolingDriver.java | 4 +-
.../apache/commons/dbcp2/datasources/PoolKey.java | 2 +
.../datasources/SharedPoolDataSourceFactory.java | 8 ++
.../managed/PoolableManagedConnectionFactory.java | 2 +
9 files changed, 209 insertions(+), 19 deletions(-)
diff --git a/src/main/java/org/apache/commons/dbcp2/DelegatingConnection.java
b/src/main/java/org/apache/commons/dbcp2/DelegatingConnection.java
index 4484ac83..996d31f2 100644
--- a/src/main/java/org/apache/commons/dbcp2/DelegatingConnection.java
+++ b/src/main/java/org/apache/commons/dbcp2/DelegatingConnection.java
@@ -325,7 +325,13 @@ public class DelegatingConnection<C extends Connection>
extends AbandonedTrace i
}
/**
- * Returns the state caching flag.
+ * Gets whether to cache properties. The cached properties are:
+ * <ul>
+ * <li>auto-commit</li>
+ * <li>catalog</li>
+ * <li>schema</li>
+ * <li>read-only</li>
+ * </ul>
*
* @return the state caching flag
*/
@@ -844,10 +850,15 @@ public class DelegatingConnection<C extends Connection>
extends AbandonedTrace i
}
/**
- * Sets the state caching flag.
+ * Sets whether to cache properties. The cached properties are:
+ * <ul>
+ * <li>auto-commit</li>
+ * <li>catalog</li>
+ * <li>schema</li>
+ * <li>read-only</li>
+ * </ul>
*
- * @param cacheState
- * The new value for the state caching flag
+ * @param cacheState The new value for the state caching flag
*/
public void setCacheState(final boolean cacheState) {
this.cacheState = cacheState;
diff --git a/src/main/java/org/apache/commons/dbcp2/PoolableConnection.java
b/src/main/java/org/apache/commons/dbcp2/PoolableConnection.java
index 01ce941d..7a8dca46 100644
--- a/src/main/java/org/apache/commons/dbcp2/PoolableConnection.java
+++ b/src/main/java/org/apache/commons/dbcp2/PoolableConnection.java
@@ -174,7 +174,7 @@ public class PoolableConnection extends
DelegatingConnection<Connection> impleme
}
/**
- * Returns me to my pool.
+ * Returns this instance to my containing pool.
*/
@Override
public void close() throws SQLException {
@@ -247,7 +247,7 @@ public class PoolableConnection extends
DelegatingConnection<Connection> impleme
}
/**
- * Expose the {@link #toString()} method via a bean getter, so it can be
read as a property via JMX.
+ * Gets the value of the {@link #toString()} method via a bean getter, so
it can be read as a property via JMX.
*/
@Override
public String getToString() {
@@ -356,7 +356,7 @@ public class PoolableConnection extends
DelegatingConnection<Connection> impleme
}
/**
- * Actually close my underlying {@link Connection}.
+ * Closes the underlying {@link Connection}.
*/
@Override
public void reallyClose() throws SQLException {
diff --git
a/src/main/java/org/apache/commons/dbcp2/PoolableConnectionFactory.java
b/src/main/java/org/apache/commons/dbcp2/PoolableConnectionFactory.java
index 532e8578..0b7cdf68 100644
--- a/src/main/java/org/apache/commons/dbcp2/PoolableConnectionFactory.java
+++ b/src/main/java/org/apache/commons/dbcp2/PoolableConnectionFactory.java
@@ -175,11 +175,18 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
return connectionFactory;
}
+ /**
+ * Gets how many connections were created in {@link #makeObject()}.
+ *
+ * @return the connection count.
+ */
protected AtomicLong getConnectionIndex() {
return connectionIndex;
}
/**
+ * Gets the collection of initialization SQL statements.
+ *
* @return The collection of initialization SQL statements.
* @since 2.6.0
*/
@@ -188,7 +195,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return The data source JMX ObjectName
+ * Gets data source JMX ObjectName.
+ *
+ * @return The data source JMX ObjectName.
* @since 2.6.0.
*/
public ObjectName getDataSourceJmxName() {
@@ -196,7 +205,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return The data source JMS ObjectName.
+ * Gets the data source JMX ObjectName.
+ *
+ * @return The data source JMX ObjectName.
* @since 2.6.0
*/
public ObjectName getDataSourceJmxObjectName() {
@@ -204,7 +215,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return Default auto-commit value.
+ * Gets the Default auto-commit value.
+ *
+ * @return The default auto-commit value.
* @since 2.6.0
*/
public Boolean getDefaultAutoCommit() {
@@ -212,7 +225,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return Default catalog.
+ * Gets the default catalog.
+ *
+ * @return The default catalog.
* @since 2.6.0
*/
public String getDefaultCatalog() {
@@ -220,7 +235,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return Default query timeout in seconds.
+ * Gets the default query timeout in seconds.
+ *
+ * @return The default query timeout in seconds.
* @deprecated Use {@link #getDefaultQueryTimeoutDuration()}.
*/
@Deprecated
@@ -231,7 +248,7 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
/**
* Gets the default query timeout Duration.
*
- * @return Default query timeout Duration.
+ * @return The default query timeout Duration.
* @since 2.10.0
*/
public Duration getDefaultQueryTimeoutDuration() {
@@ -239,7 +256,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return Default query timeout in seconds.
+ * Gets the default query timeout in seconds.
+ *
+ * @return The default query timeout in seconds.
* @since 2.6.0
* @deprecated Use {@link #getDefaultQueryTimeoutDuration()}.
*/
@@ -249,7 +268,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return Default read-only-value.
+ * Gets the default read-only-value.
+ *
+ * @return The default read-only-value.
* @since 2.6.0
*/
public Boolean getDefaultReadOnly() {
@@ -257,7 +278,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return Default schema.
+ * Gets the default schema.
+ *
+ * @return The default schema.
* @since 2.6.0
*/
public String getDefaultSchema() {
@@ -265,7 +288,9 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
}
/**
- * @return Default transaction isolation.
+ * Gets the default transaction isolation.
+ *
+ * @return The default transaction isolation.
* @since 2.6.0
*/
public int getDefaultTransactionIsolation() {
@@ -327,9 +352,15 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
return maxConnDuration.toMillis();
}
+ /**
+ * Gets the maximum number of open prepared statements.
+ *
+ * @return The maximum number of open prepared statements.
+ */
protected int getMaxOpenPreparedStatements() {
return maxOpenPreparedStatements;
}
+
/**
* Returns the {@link ObjectPool} in which {@link Connection}s are pooled.
*
@@ -381,6 +412,13 @@ public class PoolableConnectionFactory implements
PooledObjectFactory<PoolableCo
return (int) validationQueryTimeoutDuration.getSeconds();
}
+ /**
+ * Initializes the given connection with the collection of SQL statements
set in {@link #setConnectionInitSql(Collection)}.
+ *
+ * @param conn the connection to initialize.
+ * @throws SQLException if a database access error occurs or this method
is called on a closed connection.
+ * @see #setConnectionInitSql(Collection)
+ */
protected void initializeConnection(final Connection conn) throws
SQLException {
final Collection<String> sqls = connectionInitSqls;
if (conn.isClosed()) {
diff --git
a/src/main/java/org/apache/commons/dbcp2/PoolableConnectionMXBean.java
b/src/main/java/org/apache/commons/dbcp2/PoolableConnectionMXBean.java
index b2336508..a31b3f37 100644
--- a/src/main/java/org/apache/commons/dbcp2/PoolableConnectionMXBean.java
+++ b/src/main/java/org/apache/commons/dbcp2/PoolableConnectionMXBean.java
@@ -16,6 +16,7 @@
*/
package org.apache.commons.dbcp2;
+import java.sql.Connection;
import java.sql.SQLException;
/**
@@ -25,43 +26,166 @@ import java.sql.SQLException;
*/
public interface PoolableConnectionMXBean {
+ /**
+ * Clears the cached state. Call when you know that the underlying
connection may have been accessed directly.
+ */
void clearCachedState();
+ /**
+ * See {@link Connection#clearWarnings()}.
+ *
+ * @throws SQLException See {@link Connection#clearWarnings()}.
+ */
void clearWarnings() throws SQLException;
+ /**
+ * Returns this instance to my containing pool.
+ *
+ * @throws SQLException Throw if this instance cannot be returned.
+ */
void close() throws SQLException;
+ /**
+ * See {@link Connection#getAutoCommit()}.
+ *
+ * @return See {@link Connection#getAutoCommit()}.
+ * @throws SQLException See {@link Connection#getAutoCommit()}.
+ */
boolean getAutoCommit() throws SQLException;
+ /**
+ * Gets whether to cache properties. The cached properties are:
+ * <ul>
+ * <li>auto-commit</li>
+ * <li>catalog</li>
+ * <li>schema</li>
+ * <li>read-only</li>
+ * </ul>
+ *
+ * @return The value for the state caching flag.
+ */
boolean getCacheState();
+ /**
+ * See {@link Connection#getCatalog()}.
+ *
+ * @return See {@link Connection#getCatalog()}.
+ * @throws SQLException See {@link Connection#getCatalog()}.
+ */
String getCatalog() throws SQLException;
+ /**
+ * See {@link Connection#getHoldability()}.
+ *
+ * @return See {@link Connection#getHoldability()}.
+ * @throws SQLException See {@link Connection#getHoldability()}.
+ */
int getHoldability() throws SQLException;
+ /**
+ * See {@link Connection#getSchema()}.
+ *
+ * @return See {@link Connection#getSchema()}.
+ * @throws SQLException See {@link Connection#getSchema()}.
+ */
String getSchema() throws SQLException;
+ /**
+ * Gets the value of the {@link Object#toString()} method via a bean
getter, so it can be read as a property via JMX.
+ *
+ * @return the value of the {@link Object#toString()}.
+ */
String getToString();
+ /**
+ * See {@link Connection#getTransactionIsolation()}.
+ *
+ * @return See {@link Connection#getTransactionIsolation()}.
+ * @throws SQLException See {@link Connection#getTransactionIsolation()}.
+ */
int getTransactionIsolation() throws SQLException;
+ /**
+ * See {@link Connection#isClosed()}.
+ *
+ * @return See {@link Connection#isClosed()}.
+ * @throws SQLException See {@link Connection#isClosed()}.
+ */
boolean isClosed() throws SQLException;
+ /**
+ * See {@link Connection#isReadOnly()}.
+ *
+ * @return See {@link Connection#isReadOnly()}.
+ * @throws SQLException See {@link Connection#isReadOnly()}.
+ */
boolean isReadOnly() throws SQLException;
+ /**
+ * Closes the underlying {@link Connection}.
+ *
+ * @throws SQLException Thrown if the connection can be closed.
+ */
void reallyClose() throws SQLException;
+ /**
+ * See {@link Connection#setAutoCommit(boolean)}.
+ *
+ * @param autoCommit See {@link Connection#setAutoCommit(boolean)}.
+ * @throws SQLException See {@link Connection#setAutoCommit(boolean)}.
+ */
void setAutoCommit(boolean autoCommit) throws SQLException;
+ /**
+ * Sets whether to cache properties. The cached properties are:
+ * <ul>
+ * <li>auto-commit</li>
+ * <li>catalog</li>
+ * <li>schema</li>
+ * <li>read-only</li>
+ * </ul>
+ *
+ * @param cacheState The new value for the state caching flag
+ */
void setCacheState(boolean cacheState);
+ /**
+ * See {@link Connection#setCatalog(String)}.
+ *
+ * @param catalog See {@link Connection#setCatalog(String)}.
+ * @throws SQLException See {@link Connection#setCatalog(String)}.
+ */
void setCatalog(String catalog) throws SQLException;
+ /**
+ * See {@link Connection#setHoldability(int)}.
+ *
+ * @param holdability {@link Connection#setHoldability(int)}.
+ * @throws SQLException See {@link Connection#setHoldability(int)}.
+ */
void setHoldability(int holdability) throws SQLException;
+ /**
+ * See {@link Connection#setReadOnly(boolean)}.
+ *
+ * @param readOnly See {@link Connection#setReadOnly(boolean)}.
+ * @throws SQLException See {@link Connection#setReadOnly(boolean)}.
+ */
void setReadOnly(boolean readOnly) throws SQLException;
+ /**
+ * See {@link Connection#setSchema(String)}.
+ *
+ * @param schema See {@link Connection#setSchema(String)}.
+ * @throws SQLException See {@link Connection#setSchema(String)}.
+ */
void setSchema(String schema) throws SQLException;
+ /**
+ * See {@link Connection#setTransactionIsolation(int)}.
+ *
+ * @param level See {@link Connection#setTransactionIsolation(int)}.
+ * @throws SQLException See {@link
Connection#setTransactionIsolation(int)}.
+ */
void setTransactionIsolation(int level) throws SQLException;
}
diff --git a/src/main/java/org/apache/commons/dbcp2/PoolingDataSource.java
b/src/main/java/org/apache/commons/dbcp2/PoolingDataSource.java
index 4762107e..fe019b95 100644
--- a/src/main/java/org/apache/commons/dbcp2/PoolingDataSource.java
+++ b/src/main/java/org/apache/commons/dbcp2/PoolingDataSource.java
@@ -192,6 +192,11 @@ public class PoolingDataSource<C extends Connection>
implements DataSource, Auto
throw new SQLFeatureNotSupportedException();
}
+ /**
+ * Gets the backing object pool.
+ *
+ * @return the backing object pool.
+ */
protected ObjectPool<C> getPool() {
return pool;
}
diff --git a/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java
b/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java
index eec6a0e0..d1aacd28 100644
--- a/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java
+++ b/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java
@@ -87,13 +87,13 @@ public class PoolingDriver implements Driver {
/** The map of registered pools. */
protected static final HashMap<String, ObjectPool<? extends Connection>>
pools = new HashMap<>();
- /**
+ /**
* The Apache Commons connection string prefix {@value}.
*/
public static final String URL_PREFIX = "jdbc:apache:commons:dbcp:";
/**
- * The length of {@Link #URL_PREFIX}.
+ * The String length of {@link #URL_PREFIX}.
*/
protected static final int URL_PREFIX_LEN = URL_PREFIX.length();
diff --git a/src/main/java/org/apache/commons/dbcp2/datasources/PoolKey.java
b/src/main/java/org/apache/commons/dbcp2/datasources/PoolKey.java
index 01d8675a..31be5411 100644
--- a/src/main/java/org/apache/commons/dbcp2/datasources/PoolKey.java
+++ b/src/main/java/org/apache/commons/dbcp2/datasources/PoolKey.java
@@ -20,6 +20,8 @@ import java.io.Serializable;
import java.util.Objects;
/**
+ * The key type for entries in a {@link PerUserPoolDataSource}.
+ *
* @since 2.0
*/
final class PoolKey implements Serializable {
diff --git
a/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSourceFactory.java
b/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSourceFactory.java
index 937ccd1f..b2014365 100644
---
a/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSourceFactory.java
+++
b/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSourceFactory.java
@@ -25,8 +25,16 @@ import javax.naming.Reference;
* @since 2.0
*/
public class SharedPoolDataSourceFactory extends InstanceKeyDataSourceFactory {
+
private static final String SHARED_POOL_CLASSNAME =
SharedPoolDataSource.class.getName();
+ /**
+ * Constructs a new instance.
+ */
+ public SharedPoolDataSourceFactory() {
+ // empty
+ }
+
@Override
protected InstanceKeyDataSource getNewInstance(final Reference ref) {
final SharedPoolDataSource spds = new SharedPoolDataSource();
diff --git
a/src/main/java/org/apache/commons/dbcp2/managed/PoolableManagedConnectionFactory.java
b/src/main/java/org/apache/commons/dbcp2/managed/PoolableManagedConnectionFactory.java
index 92db944f..9dc80ccb 100644
---
a/src/main/java/org/apache/commons/dbcp2/managed/PoolableManagedConnectionFactory.java
+++
b/src/main/java/org/apache/commons/dbcp2/managed/PoolableManagedConnectionFactory.java
@@ -58,6 +58,8 @@ public class PoolableManagedConnectionFactory extends
PoolableConnectionFactory
}
/**
+ * Gets the transaction registry.
+ *
* @return The transaction registry.
* @since 2.6.0
*/
