You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ma...@apache.org on 2018/06/19 10:11:57 UTC
commons-dbcp git commit: Fill in some gaps in the Javadoc
Repository: commons-dbcp
Updated Branches:
refs/heads/master c50607e7c -> ac934778a
Fill in some gaps in the Javadoc
Project: http://git-wip-us.apache.org/repos/asf/commons-dbcp/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-dbcp/commit/ac934778
Tree: http://git-wip-us.apache.org/repos/asf/commons-dbcp/tree/ac934778
Diff: http://git-wip-us.apache.org/repos/asf/commons-dbcp/diff/ac934778
Branch: refs/heads/master
Commit: ac934778af1eeb4d6dba25a7351c59430a3c8fc9
Parents: c50607e
Author: Mark Thomas <ma...@apache.org>
Authored: Tue Jun 19 11:11:30 2018 +0100
Committer: Mark Thomas <ma...@apache.org>
Committed: Tue Jun 19 11:11:30 2018 +0100
----------------------------------------------------------------------
.../apache/commons/dbcp2/BasicDataSource.java | 13 ++++++++++
.../apache/commons/dbcp2/PoolingConnection.java | 20 ++++++++++++++++
.../org/apache/commons/dbcp2/PoolingDriver.java | 3 +++
.../InstanceKeyDataSourceFactory.java | 25 +++++++++++++++++++-
4 files changed, 60 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/ac934778/src/main/java/org/apache/commons/dbcp2/BasicDataSource.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/dbcp2/BasicDataSource.java b/src/main/java/org/apache/commons/dbcp2/BasicDataSource.java
index 8c265cb..dc1c71c 100644
--- a/src/main/java/org/apache/commons/dbcp2/BasicDataSource.java
+++ b/src/main/java/org/apache/commons/dbcp2/BasicDataSource.java
@@ -2078,6 +2078,7 @@ public class BasicDataSource implements DataSource, BasicDataSourceMXBean, MBean
* Creates (if necessary) and return the internal data source we are using to manage our connections.
* </p>
*
+ * @return The current internal DataSource or a newly created instance if it has not yet been created.
* @throws SQLException
* if the object pool cannot be created.
*/
@@ -2172,6 +2173,11 @@ public class BasicDataSource implements DataSource, BasicDataSourceMXBean, MBean
* <li>If a driver still isn't loaded one is loaded via the {@link DriverManager} using the specified {@link #url}.
* </ol>
* This method exists so subclasses can replace the implementation class.
+ *
+ * @return A new connection factory.
+ *
+ * @throws SQLException
+ * If the connection factort cannot be created
*/
protected ConnectionFactory createConnectionFactory() throws SQLException {
// Load the JDBC driver class
@@ -2247,6 +2253,9 @@ public class BasicDataSource implements DataSource, BasicDataSourceMXBean, MBean
* property is deferred to {@link #startPoolMaintenance()}, since setting timeBetweenEvictionRunsMillis to a
* positive value causes {@link GenericObjectPool}'s eviction timer to be started.
* </p>
+ *
+ * @param factory
+ * The factory to use to create new connections for this pool.
*/
protected void createConnectionPool(final PoolableConnectionFactory factory) {
// Create an object pool to contain our active connections
@@ -2326,6 +2335,8 @@ public class BasicDataSource implements DataSource, BasicDataSourceMXBean, MBean
*
* @throws SQLException
* if unable to create a datasource instance
+ *
+ * @return A new DataSource instance
*/
protected DataSource createDataSourceInstance() throws SQLException {
final PoolingDataSource<PoolableConnection> pds = new PoolingDataSource<>(connectionPool);
@@ -2341,6 +2352,8 @@ public class BasicDataSource implements DataSource, BasicDataSourceMXBean, MBean
* JDBC connection factory
* @throws SQLException
* if an error occurs creating the PoolableConnectionFactory
+ *
+ * @return A new PoolableConnectionFactory configured with the current configuration of this BasicDataSource
*/
protected PoolableConnectionFactory createPoolableConnectionFactory(final ConnectionFactory driverConnectionFactory)
throws SQLException {
http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/ac934778/src/main/java/org/apache/commons/dbcp2/PoolingConnection.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/dbcp2/PoolingConnection.java b/src/main/java/org/apache/commons/dbcp2/PoolingConnection.java
index 725e1b5..8b2ffa0 100644
--- a/src/main/java/org/apache/commons/dbcp2/PoolingConnection.java
+++ b/src/main/java/org/apache/commons/dbcp2/PoolingConnection.java
@@ -121,6 +121,8 @@ public class PoolingConnection extends DelegatingConnection<Connection>
*
* @param sql
* the SQL string used to define the statement
+ *
+ * @return the PStmtKey created for the given arguments.
*/
protected PStmtKey createKey(final String sql) {
String catalog = null;
@@ -149,6 +151,8 @@ public class PoolingConnection extends DelegatingConnection<Connection>
* the SQL string used to define the statement
* @param columnIndexes
* column indexes
+ *
+ * @return the PStmtKey created for the given arguments.
*/
protected PStmtKey createKey(final String sql, final int columnIndexes[]) {
String catalog = null;
@@ -169,6 +173,8 @@ public class PoolingConnection extends DelegatingConnection<Connection>
* result set type
* @param resultSetConcurrency
* result set concurrency
+ *
+ * @return the PStmtKey created for the given arguments.
*/
protected PStmtKey createKey(final String sql, final int resultSetType, final int resultSetConcurrency) {
String catalog = null;
@@ -191,6 +197,8 @@ public class PoolingConnection extends DelegatingConnection<Connection>
* result set concurrency
* @param resultSetHoldability
* result set holdability
+ *
+ * @return the PStmtKey created for the given arguments.
*/
protected PStmtKey createKey(final String sql, final int resultSetType, final int resultSetConcurrency,
final int resultSetHoldability) {
@@ -216,6 +224,8 @@ public class PoolingConnection extends DelegatingConnection<Connection>
* result set holdability
* @param stmtType
* statement type
+ *
+ * @return the PStmtKey created for the given arguments.
*/
protected PStmtKey createKey(final String sql, final int resultSetType, final int resultSetConcurrency,
final int resultSetHoldability, final StatementType stmtType) {
@@ -240,6 +250,8 @@ public class PoolingConnection extends DelegatingConnection<Connection>
* result set concurrency
* @param stmtType
* statement type
+ *
+ * @return the PStmtKey created for the given arguments.
*/
protected PStmtKey createKey(final String sql, final int resultSetType, final int resultSetConcurrency,
final StatementType stmtType) {
@@ -259,6 +271,8 @@ public class PoolingConnection extends DelegatingConnection<Connection>
* the SQL string used to define the statement
* @param stmtType
* statement type
+ *
+ * @return the PStmtKey created for the given arguments.
*/
protected PStmtKey createKey(final String sql, final StatementType stmtType) {
String catalog = null;
@@ -277,6 +291,8 @@ public class PoolingConnection extends DelegatingConnection<Connection>
* the SQL string used to define the statement
* @param columnNames
* column names
+ *
+ * @return the PStmtKey created for the given arguments.
*/
protected PStmtKey createKey(final String sql, final String columnNames[]) {
String catalog = null;
@@ -331,6 +347,10 @@ public class PoolingConnection extends DelegatingConnection<Connection>
/**
* Normalizes the given SQL statement, producing a canonical form that is semantically equivalent to the original.
+ *
+ * @param sql The statement to be normalized.
+ *
+ * @return The canonical form of the supplied SQL statement.
*/
protected String normalizeSQL(final String sql) {
return sql.trim();
http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/ac934778/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java b/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java
index fbf7b9a..5ba3664 100644
--- a/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java
+++ b/src/main/java/org/apache/commons/dbcp2/PoolingDriver.java
@@ -61,6 +61,9 @@ public class PoolingDriver implements Driver {
/**
* For unit testing purposes.
+ *
+ * @param accessToUnderlyingConnectionAllowed
+ * Do {@link DelegatingConnection}s created by this driver permit access to the delegate?
*/
protected PoolingDriver(final boolean accessToUnderlyingConnectionAllowed) {
this.accessToUnderlyingConnectionAllowed = accessToUnderlyingConnectionAllowed;
http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/ac934778/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSourceFactory.java
----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSourceFactory.java b/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSourceFactory.java
index 9c996be..ee68cd7 100644
--- a/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSourceFactory.java
+++ b/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSourceFactory.java
@@ -287,17 +287,40 @@ abstract class InstanceKeyDataSourceFactory implements ObjectFactory {
}
/**
+ * @param className
+ * The class name to test.
+ *
* @return true if and only if className is the value returned from getClass().getName().toString()
*/
protected abstract boolean isCorrectClass(String className);
/**
* Creates an instance of the subclass and sets any properties contained in the Reference.
+ *
+ * @param ref
+ * The properties to be set on the created DataSource
+ *
+ * @return A configured DataSource of the appropriate type.
+ *
+ * @throws ClassNotFoundException
+ * If a class cannot be found during the deserialization of a configuration parameter.
+ * @throws IOException
+ * If an I/O error occurs during the deserialization of a configuration parameter.
*/
protected abstract InstanceKeyDataSource getNewInstance(Reference ref) throws IOException, ClassNotFoundException;
/**
- * Sets some properties saved within a Reference
+ * Deserializes the provided byte array to create an object.
+ *
+ * @param data
+ * Data to deserialize to create the configuration parameter.
+ *
+ * @return The Object created by deserializing the data.
+ *
+ * @throws ClassNotFoundException
+ * If a class cannot be found during the deserialization of a configuration parameter.
+ * @throws IOException
+ * If an I/O error occurs during the deserialization of a configuration parameter.
*/
protected static final Object deserialize(final byte[] data) throws IOException, ClassNotFoundException {
ObjectInputStream in = null;