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/release 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;