Repository: commons-dbcp Updated Branches: refs/heads/master e45d91d03 -> 80287ea5d
Fix typos in private ivar name, Javadocs, and param name: camel case 'username' as 'userName'. Project: http://git-wip-us.apache.org/repos/asf/commons-dbcp/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-dbcp/commit/80287ea5 Tree: http://git-wip-us.apache.org/repos/asf/commons-dbcp/tree/80287ea5 Diff: http://git-wip-us.apache.org/repos/asf/commons-dbcp/diff/80287ea5 Branch: refs/heads/master Commit: 80287ea5dcec5dc0fe8903fd94a51fcd7252dade Parents: e45d91d Author: Gary Gregory <[email protected]> Authored: Sun Jun 10 10:52:09 2018 -0600 Committer: Gary Gregory <[email protected]> Committed: Sun Jun 10 10:52:09 2018 -0600 ---------------------------------------------------------------------- src/changes/changes.xml | 2 +- .../apache/commons/dbcp2/BasicDataSource.java | 10 +- .../dbcp2/cpdsadapter/DriverAdapterCPDS.java | 20 +- .../datasources/CPDSConnectionFactory.java | 20 +- .../datasources/InstanceKeyDataSource.java | 33 +- .../datasources/KeyedCPDSConnectionFactory.java | 14 +- .../datasources/PerUserPoolDataSource.java | 4 +- .../commons/dbcp2/datasources/PoolKey.java | 4 +- .../datasources/PooledConnectionAndInfo.java | 22 +- .../dbcp2/datasources/SharedPoolDataSource.java | 36 +- .../commons/dbcp2/datasources/UserPassKey.java | 40 +- .../org/apache/commons/dbcp2/package-info.java | 4 +- src/site/xdoc/configuration.xml | 1012 +++++++++--------- src/site/xdoc/guide/jndi-howto.xml | 2 +- .../apache/commons/dbcp2/TesterConnection.java | 10 +- .../org/apache/commons/dbcp2/TesterDriver.java | 32 +- .../apache/commons/dbcp2/TesterStatement.java | 4 +- .../datasources/TestInstanceKeyDataSource.java | 2 +- .../datasources/TestPerUserPoolDataSource.java | 2 +- 19 files changed, 637 insertions(+), 636 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/changes/changes.xml ---------------------------------------------------------------------- diff --git a/src/changes/changes.xml b/src/changes/changes.xml index b76d938..676d879 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -785,7 +785,7 @@ The <action> type attribute can be add,update,fix,remove. Add a <i>JNDI How To</i> to the User Guide. </action> <action dev="dirkv " type="fix" issue="DBCP-108" due-to="Maxwell Grender-Jones"> - DriverManagerConnectionFactory: blank username/password handling. + DriverManagerConnectionFactory: blank user name and password handling. </action> <action dev="dirkv " type="fix" issue="DBCP-113" due-to="Rohan Lenard"> Broken behaviour for BasicDataSource.setMaxActive(0). http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/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 8a9186c..d40eda7 100644 --- a/src/main/java/org/apache/commons/dbcp2/BasicDataSource.java +++ b/src/main/java/org/apache/commons/dbcp2/BasicDataSource.java @@ -1063,7 +1063,7 @@ public class BasicDataSource implements DataSource, BasicDataSourceMXBean, MBean } /** - * The connection username to be passed to our JDBC driver to establish a connection. + * The connection user name to be passed to our JDBC driver to establish a connection. */ private String userName; @@ -1087,11 +1087,11 @@ public class BasicDataSource implements DataSource, BasicDataSourceMXBean, MBean * setLoginTimeout, getLoginTimeout, getLogWriter.</code> * </p> * - * @param username - * the new value for the JDBC connection username + * @param userName + * the new value for the JDBC connection user name */ - public void setUsername(final String username) { - this.userName = username; + public void setUsername(final String userName) { + this.userName = userName; } /** http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/cpdsadapter/DriverAdapterCPDS.java ---------------------------------------------------------------------- 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 fecf443..4bf0a01 100644 --- a/src/main/java/org/apache/commons/dbcp2/cpdsadapter/DriverAdapterCPDS.java +++ b/src/main/java/org/apache/commons/dbcp2/cpdsadapter/DriverAdapterCPDS.java @@ -115,7 +115,7 @@ public class DriverAdapterCPDS /** Url name */ private String url; /** User name */ - private String user; + private String userName; /** Driver class name */ private String driver; @@ -166,13 +166,13 @@ public class DriverAdapterCPDS /** * Attempt to establish a database connection. * - * @param username + * @param userName * name to be used for the connection * @param pass * password to be used fur the connection */ @Override - public PooledConnection getPooledConnection(final String username, final String pass) + public PooledConnection getPooledConnection(final String userName, final String pass) throws SQLException { getConnectionCalled = true; PooledConnectionImpl pci = null; @@ -180,13 +180,13 @@ public class DriverAdapterCPDS // exception upon first invocation. try { if (connectionProperties != null) { - update(connectionProperties, KEY_USER, username); + update(connectionProperties, KEY_USER, userName); update(connectionProperties, KEY_PASSWORD, pass); pci = new PooledConnectionImpl(DriverManager.getConnection( getUrl(), connectionProperties)); } else { pci = new PooledConnectionImpl(DriverManager.getConnection( - getUrl(), username, pass)); + getUrl(), userName, pass)); } pci.setAccessToUnderlyingConnectionAllowed(isAccessToUnderlyingConnectionAllowed()); } catch (final ClassCircularityError e) { @@ -195,7 +195,7 @@ public class DriverAdapterCPDS getUrl(), connectionProperties)); } else { pci = new PooledConnectionImpl(DriverManager.getConnection( - getUrl(), username, pass)); + getUrl(), userName, pass)); } pci.setAccessToUnderlyingConnectionAllowed(isAccessToUnderlyingConnectionAllowed()); } @@ -477,16 +477,16 @@ public class DriverAdapterCPDS } /** - * Gets the value of default user (login or username). + * Gets the value of default user (login or user name). * * @return value of user. */ public String getUser() { - return user; + return userName; } /** - * Sets the value of default user (login or username). + * Sets the value of default user (login or user name). * * @param v * Value to assign to user. @@ -495,7 +495,7 @@ public class DriverAdapterCPDS */ public void setUser(final String v) { assertInitializationAllowed(); - this.user = v; + this.userName = v; update(connectionProperties, KEY_USER, v); } http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/datasources/CPDSConnectionFactory.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/dbcp2/datasources/CPDSConnectionFactory.java b/src/main/java/org/apache/commons/dbcp2/datasources/CPDSConnectionFactory.java index 5b582e9..717de87 100644 --- a/src/main/java/org/apache/commons/dbcp2/datasources/CPDSConnectionFactory.java +++ b/src/main/java/org/apache/commons/dbcp2/datasources/CPDSConnectionFactory.java @@ -56,7 +56,7 @@ class CPDSConnectionFactory private final int _validationQueryTimeout; private final boolean _rollbackAfterValidation; private ObjectPool<PooledConnectionAndInfo> _pool; - private final String _username; + private final String _userName; private String _password = null; private long maxConnLifetimeMillis = -1; @@ -86,19 +86,19 @@ class CPDSConnectionFactory * @param validationQueryTimeout Timeout in seconds before validation fails * @param rollbackAfterValidation whether a rollback should be issued * after {@link #validateObject validating} {@link Connection}s. - * @param username The user name to use to create connections + * @param userName The user name to use to create connections * @param password The password to use to create connections */ public CPDSConnectionFactory(final ConnectionPoolDataSource cpds, final String validationQuery, final int validationQueryTimeout, final boolean rollbackAfterValidation, - final String username, + final String userName, final String password) { _cpds = cpds; _validationQuery = validationQuery; _validationQueryTimeout = validationQueryTimeout; - _username = username; + _userName = userName; _password = password; _rollbackAfterValidation = rollbackAfterValidation; } @@ -126,10 +126,10 @@ class CPDSConnectionFactory PooledConnectionAndInfo pci; try { PooledConnection pc = null; - if (_username == null) { + if (_userName == null) { pc = _cpds.getPooledConnection(); } else { - pc = _cpds.getPooledConnection(_username, _password); + pc = _cpds.getPooledConnection(_userName, _password); } if (pc == null) { @@ -139,7 +139,7 @@ class CPDSConnectionFactory // should we add this object as a listener or the pool. // consider the validateObject method in decision pc.addConnectionEventListener(this); - pci = new PooledConnectionAndInfo(pc, _username, _password); + pci = new PooledConnectionAndInfo(pc, _userName, _password); pcMap.put(pc, pci); } catch (final SQLException e) { throw new RuntimeException(e.getMessage()); @@ -341,13 +341,13 @@ class CPDSConnectionFactory } /** - * Verifies that the username matches the user whose connections are being managed by this + * Verifies that the user name matches the user whose connections are being managed by this * factory and closes the pool if this is the case; otherwise does nothing. */ @Override - public void closePool(final String username) throws SQLException { + public void closePool(final String userName) throws SQLException { synchronized (this) { - if (username == null || !username.equals(_username)) { + if (userName == null || !userName.equals(_userName)) { return; } } http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSource.java ---------------------------------------------------------------------- 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 cd091fd..242d538 100644 --- a/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSource.java +++ b/src/main/java/org/apache/commons/dbcp2/datasources/InstanceKeyDataSource.java @@ -930,9 +930,9 @@ public abstract class InstanceKeyDataSource /** * Attempt to retrieve a database connection using {@link #getPooledConnectionAndInfo(String, String)} - * with the provided username and password. The password on the {@link PooledConnectionAndInfo} + * with the provided user name and password. The password on the {@link PooledConnectionAndInfo} * instance returned by <code>getPooledConnectionAndInfo</code> is compared to the <code>password</code> - * parameter. If the comparison fails, a database connection using the supplied username and password + * parameter. If the comparison fails, a database connection using the supplied user name and password * is attempted. If the connection attempt fails, an SQLException is thrown, indicating that the given password * did not match the password used to create the pooled connection. If the connection attempt succeeds, this * means that the database password has been changed. In this case, the <code>PooledConnectionAndInfo</code> @@ -940,7 +940,7 @@ public abstract class InstanceKeyDataSource * repeatedly invoked until a <code>PooledConnectionAndInfo</code> instance with the new password is returned. */ @Override - public Connection getConnection(final String username, final String password) + public Connection getConnection(final String userName, final String password) throws SQLException { if (instanceKey == null) { throw new SQLException("Must set the ConnectionPoolDataSource " @@ -950,7 +950,7 @@ public abstract class InstanceKeyDataSource getConnectionCalled = true; PooledConnectionAndInfo info = null; try { - info = getPooledConnectionAndInfo(username, password); + info = getPooledConnectionAndInfo(userName, password); } catch (final NoSuchElementException e) { closeDueToException(info); throw new SQLException("Cannot borrow connection from pool", e); @@ -968,7 +968,7 @@ public abstract class InstanceKeyDataSource if (!(null == password ? null == info.getPassword() : password.equals(info.getPassword()))) { // Password on PooledConnectionAndInfo does not match try { // See if password has changed by attempting connection - testCPDS(username, password); + testCPDS(userName, password); } catch (final SQLException ex) { // Password has not changed, so refuse client, but return connection to the pool closeDueToException(info); @@ -989,7 +989,7 @@ public abstract class InstanceKeyDataSource info = null; for (int i = 0; i < 10; i++) { // Bound the number of retries - only needed if bad instances return try { - info = getPooledConnectionAndInfo(username, password); + info = getPooledConnectionAndInfo(userName, password); } catch (final NoSuchElementException e) { closeDueToException(info); throw new SQLException("Cannot borrow connection from pool", e); @@ -1018,7 +1018,7 @@ public abstract class InstanceKeyDataSource final Connection con = info.getPooledConnection().getConnection(); try { - setupDefaults(con, username); + setupDefaults(con, userName); con.clearWarnings(); return con; } catch (final SQLException ex) { @@ -1032,13 +1032,10 @@ public abstract class InstanceKeyDataSource } } - protected abstract PooledConnectionAndInfo - getPooledConnectionAndInfo(String username, String password) - throws SQLException; - - protected abstract void setupDefaults(Connection con, String username) - throws SQLException; + protected abstract PooledConnectionAndInfo getPooledConnectionAndInfo(String userName, String password) + throws SQLException; + protected abstract void setupDefaults(Connection connection, String userName) throws SQLException; private void closeDueToException(final PooledConnectionAndInfo info) { if (info != null) { @@ -1055,7 +1052,7 @@ public abstract class InstanceKeyDataSource } protected ConnectionPoolDataSource - testCPDS(final String username, final String password) + testCPDS(final String userName, final String password) throws javax.naming.NamingException, SQLException { // The source of physical db connections ConnectionPoolDataSource cpds = this.dataSource; @@ -1077,18 +1074,18 @@ public abstract class InstanceKeyDataSource } } - // try to get a connection with the supplied username/password + // try to get a connection with the supplied userName/password PooledConnection conn = null; try { - if (username != null) { - conn = cpds.getPooledConnection(username, password); + if (userName != null) { + conn = cpds.getPooledConnection(userName, password); } else { conn = cpds.getPooledConnection(); } if (conn == null) { throw new SQLException( - "Cannot connect using the supplied username/password"); + "Cannot connect using the supplied userName/password"); } } finally { http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/datasources/KeyedCPDSConnectionFactory.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/dbcp2/datasources/KeyedCPDSConnectionFactory.java b/src/main/java/org/apache/commons/dbcp2/datasources/KeyedCPDSConnectionFactory.java index 6ab3c55..bc0840c 100644 --- a/src/main/java/org/apache/commons/dbcp2/datasources/KeyedCPDSConnectionFactory.java +++ b/src/main/java/org/apache/commons/dbcp2/datasources/KeyedCPDSConnectionFactory.java @@ -119,12 +119,12 @@ class KeyedCPDSConnectionFactory implements KeyedPooledObjectFactory<UserPassKey PooledConnectionAndInfo pci = null; PooledConnection pc = null; - final String username = upkey.getUsername(); + final String userName = upkey.getUsername(); final String password = upkey.getPassword(); - if (username == null) { + if (userName == null) { pc = _cpds.getPooledConnection(); } else { - pc = _cpds.getPooledConnection(username, password); + pc = _cpds.getPooledConnection(userName, password); } if (pc == null) { @@ -134,7 +134,7 @@ class KeyedCPDSConnectionFactory implements KeyedPooledObjectFactory<UserPassKey // should we add this object as a listener or the pool. // consider the validateObject method in decision pc.addConnectionEventListener(this); - pci = new PooledConnectionAndInfo(pc, username, password); + pci = new PooledConnectionAndInfo(pc, userName, password); pcMap.put(pc, pci); return new DefaultPooledObject<>(pci); @@ -291,7 +291,7 @@ class KeyedCPDSConnectionFactory implements KeyedPooledObjectFactory<UserPassKey /** * Invalidates the PooledConnection in the pool. The KeyedCPDSConnectionFactory closes the connection and pool - * counters are updated appropriately. Also clears any idle instances associated with the username that was used to + * counters are updated appropriately. Also clears any idle instances associated with the user name that was used to * create the PooledConnection. Connections associated with this user are not affected and they will not be * automatically closed on return to the pool. */ @@ -334,9 +334,9 @@ class KeyedCPDSConnectionFactory implements KeyedPooledObjectFactory<UserPassKey * the pool associated with the given user. This method is not currently used. */ @Override - public void closePool(final String username) throws SQLException { + public void closePool(final String userName) throws SQLException { try { - _pool.clear(new UserPassKey(username, null)); + _pool.clear(new UserPassKey(userName, null)); } catch (final Exception ex) { throw new SQLException("Error closing connection pool", ex); } http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/datasources/PerUserPoolDataSource.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/dbcp2/datasources/PerUserPoolDataSource.java b/src/main/java/org/apache/commons/dbcp2/datasources/PerUserPoolDataSource.java index b6d3c63..c0dceef 100644 --- a/src/main/java/org/apache/commons/dbcp2/datasources/PerUserPoolDataSource.java +++ b/src/main/java/org/apache/commons/dbcp2/datasources/PerUserPoolDataSource.java @@ -46,9 +46,9 @@ import org.apache.commons.pool2.impl.GenericObjectPool; * set for users with read-only connections.</p> * * <p>User passwords can be changed without re-initializing the datasource. - * When a <code>getConnection(username, password)</code> request is processed + * When a <code>getConnection(userName, password)</code> request is processed * with a password that is different from those used to create connections in - * the pool associated with <code>username</code>, an attempt is made to create + * the pool associated with <code>userName</code>, an attempt is made to create * a new connection using the supplied password and if this succeeds, the * existing pool is cleared and a new pool is created for connections using the * new password.</p> http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/datasources/PoolKey.java ---------------------------------------------------------------------- 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 da40e52..dfbdc4f 100644 --- a/src/main/java/org/apache/commons/dbcp2/datasources/PoolKey.java +++ b/src/main/java/org/apache/commons/dbcp2/datasources/PoolKey.java @@ -28,9 +28,9 @@ class PoolKey implements Serializable { private final String dataSourceName; private final String userName; - PoolKey(final String dataSourceName, final String username) { + PoolKey(final String dataSourceName, final String userName) { this.dataSourceName = dataSourceName; - this.userName = username; + this.userName = userName; } @Override http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/datasources/PooledConnectionAndInfo.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/dbcp2/datasources/PooledConnectionAndInfo.java b/src/main/java/org/apache/commons/dbcp2/datasources/PooledConnectionAndInfo.java index 2825f8f..7f9bef8 100644 --- a/src/main/java/org/apache/commons/dbcp2/datasources/PooledConnectionAndInfo.java +++ b/src/main/java/org/apache/commons/dbcp2/datasources/PooledConnectionAndInfo.java @@ -20,22 +20,22 @@ package org.apache.commons.dbcp2.datasources; import javax.sql.PooledConnection; /** - * Immutable poolable object holding a PooledConnection along with the username and password - * used to create the connection. + * Immutable poolable object holding a PooledConnection along with the user name and password used to create the + * connection. * * @since 2.0 */ final class PooledConnectionAndInfo { private final PooledConnection pooledConnection; private final String password; - private final String username; + private final String userName; private final UserPassKey upkey; - PooledConnectionAndInfo(final PooledConnection pc, final String username, final String password) { + PooledConnectionAndInfo(final PooledConnection pc, final String userName, final String password) { this.pooledConnection = pc; - this.username = username; + this.userName = userName; this.password = password; - upkey = new UserPassKey(username, password); + upkey = new UserPassKey(userName, password); } PooledConnection getPooledConnection() { @@ -47,7 +47,8 @@ final class PooledConnectionAndInfo { } /** - * Get the value of password. + * Gets the value of password. + * * @return value of password. */ String getPassword() { @@ -55,10 +56,11 @@ final class PooledConnectionAndInfo { } /** - * Get the value of username. - * @return value of username. + * Gets the value of userName. + * + * @return value of userName. */ String getUsername() { - return username; + return userName; } } http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSource.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSource.java b/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSource.java index 5da2d5d..679852e 100644 --- a/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSource.java +++ b/src/main/java/org/apache/commons/dbcp2/datasources/SharedPoolDataSource.java @@ -34,13 +34,13 @@ import org.apache.commons.pool2.impl.GenericKeyedObjectPoolConfig; /** * <p>A pooling <code>DataSource</code> appropriate for deployment within * J2EE environment. There are many configuration options, most of which are - * defined in the parent class. All users (based on username) share a single - * maximum number of Connections in this datasource.</p> + * defined in the parent class. All users (based on user name) share a single + * maximum number of Connections in this data source.</p> * - * <p>User passwords can be changed without re-initializing the datasource. - * When a <code>getConnection(username, password)</code> request is processed + * <p>User passwords can be changed without re-initializing the data source. + * When a <code>getConnection(user name, password)</code> request is processed * with a password that is different from those used to create connections in the - * pool associated with <code>username</code>, an attempt is made to create a + * pool associated with <code>user name</code>, an attempt is made to create a * new connection using the supplied password and if this succeeds, idle connections * created using the old password are destroyed and new connections are created * using the new password.</p> @@ -59,14 +59,14 @@ public class SharedPoolDataSource extends InstanceKeyDataSource { private transient KeyedCPDSConnectionFactory factory = null; /** - * Default no-arg constructor for Serialization + * Default no-argument constructor for Serialization */ public SharedPoolDataSource() { // empty. } /** - * Closes pool being maintained by this datasource. + * Closes pool being maintained by this data source. */ @Override public void close() throws Exception { @@ -125,13 +125,13 @@ public class SharedPoolDataSource extends InstanceKeyDataSource { // Inherited abstract methods @Override - protected PooledConnectionAndInfo getPooledConnectionAndInfo(final String username, final String password) + protected PooledConnectionAndInfo getPooledConnectionAndInfo(final String userName, final String password) throws SQLException { synchronized (this) { if (pool == null) { try { - registerPool(username, password); + registerPool(userName, password); } catch (final NamingException e) { throw new SQLException("RegisterPool failed", e); } @@ -140,7 +140,7 @@ public class SharedPoolDataSource extends InstanceKeyDataSource { PooledConnectionAndInfo info = null; - final UserPassKey key = new UserPassKey(username, password); + final UserPassKey key = new UserPassKey(userName, password); try { info = pool.borrowObject(key); @@ -165,9 +165,9 @@ public class SharedPoolDataSource extends InstanceKeyDataSource { return ref; } - private void registerPool(final String username, final String password) throws NamingException, SQLException { + private void registerPool(final String userName, final String password) throws NamingException, SQLException { - final ConnectionPoolDataSource cpds = testCPDS(username, password); + final ConnectionPoolDataSource cpds = testCPDS(userName, password); // Create an object pool to contain our PooledConnections factory = new KeyedCPDSConnectionFactory(cpds, getValidationQuery(), getValidationQueryTimeout(), @@ -199,20 +199,20 @@ public class SharedPoolDataSource extends InstanceKeyDataSource { } @Override - protected void setupDefaults(final Connection con, final String username) throws SQLException { + protected void setupDefaults(final Connection connection, final String userName) throws SQLException { final Boolean defaultAutoCommit = isDefaultAutoCommit(); - if (defaultAutoCommit != null && con.getAutoCommit() != defaultAutoCommit.booleanValue()) { - con.setAutoCommit(defaultAutoCommit.booleanValue()); + if (defaultAutoCommit != null && connection.getAutoCommit() != defaultAutoCommit.booleanValue()) { + connection.setAutoCommit(defaultAutoCommit.booleanValue()); } final int defaultTransactionIsolation = getDefaultTransactionIsolation(); if (defaultTransactionIsolation != UNKNOWN_TRANSACTIONISOLATION) { - con.setTransactionIsolation(defaultTransactionIsolation); + connection.setTransactionIsolation(defaultTransactionIsolation); } final Boolean defaultReadOnly = isDefaultReadOnly(); - if (defaultReadOnly != null && con.isReadOnly() != defaultReadOnly.booleanValue()) { - con.setReadOnly(defaultReadOnly.booleanValue()); + if (defaultReadOnly != null && connection.isReadOnly() != defaultReadOnly.booleanValue()) { + connection.setReadOnly(defaultReadOnly.booleanValue()); } } http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/datasources/UserPassKey.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/dbcp2/datasources/UserPassKey.java b/src/main/java/org/apache/commons/dbcp2/datasources/UserPassKey.java index 3e8877c..ee32bce 100644 --- a/src/main/java/org/apache/commons/dbcp2/datasources/UserPassKey.java +++ b/src/main/java/org/apache/commons/dbcp2/datasources/UserPassKey.java @@ -20,10 +20,10 @@ package org.apache.commons.dbcp2.datasources; import java.io.Serializable; /** - * <p>Holds a username, password pair. Serves as a poolable object key for the KeyedObjectPool - * backing a SharedPoolDataSource. Two instances with the same username are considered equal. + * <p>Holds a user name, password pair. Serves as a poolable object key for the KeyedObjectPool + * backing a SharedPoolDataSource. Two instances with the same user name are considered equal. * This ensures that there will be only one keyed pool for each user in the pool. The password - * is used (along with the username) by the KeyedCPDSConnectionFactory when creating new connections.</p> + * is used (along with the user name) by the KeyedCPDSConnectionFactory when creating new connections.</p> * * <p>{@link InstanceKeyDataSource#getConnection(String, String)} validates that the password used to create * a connection matches the password provided by the client.</p> @@ -33,15 +33,16 @@ import java.io.Serializable; class UserPassKey implements Serializable { private static final long serialVersionUID = 5142970911626584817L; private final String password; - private final String username; + private final String userName; - UserPassKey(final String username, final String password) { - this.username = username; + UserPassKey(final String userName, final String password) { + this.userName = userName; this.password = password; } /** - * Get the value of password. + * Gets the value of password. + * * @return value of password. */ public String getPassword() { @@ -49,16 +50,17 @@ class UserPassKey implements Serializable { } /** - * Get the value of username. - * @return value of username. + * Gets the value of user name. + * + * @return value of user name. */ public String getUsername() { - return username; + return userName; } /** - * @return <code>true</code> if the username fields for both - * objects are equal. Two instances with the same username + * @return <code>true</code> if the user name fields for both + * objects are equal. Two instances with the same user name * but different passwords are considered equal. * * @see java.lang.Object#equals(java.lang.Object) @@ -79,25 +81,25 @@ class UserPassKey implements Serializable { final UserPassKey key = (UserPassKey) obj; - return this.username == null ? - key.username == null : - this.username.equals(key.username); + return this.userName == null ? + key.userName == null : + this.userName.equals(key.userName); } /** - * Returns the hash of the username. + * Returns the hash of the user name. */ @Override public int hashCode() { - return this.username != null ? - this.username.hashCode() : 0; + return this.userName != null ? + this.userName.hashCode() : 0; } @Override public String toString() { final StringBuffer sb = new StringBuffer(50); sb.append("UserPassKey("); - sb.append(username).append(", ").append(password).append(')'); + sb.append(userName).append(", ").append(password).append(')'); return sb.toString(); } } http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/main/java/org/apache/commons/dbcp2/package-info.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/dbcp2/package-info.java b/src/main/java/org/apache/commons/dbcp2/package-info.java index 5b75246..ecc2489 100644 --- a/src/main/java/org/apache/commons/dbcp2/package-info.java +++ b/src/main/java/org/apache/commons/dbcp2/package-info.java @@ -108,7 +108,7 @@ * In code, that might look like this: * </p> * <pre>GenericObjectPool connectionPool = new GenericObjectPool(null); - * ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "username", "password"); + * ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "userName", "password"); * PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,connectionPool,null,null,false,true); * PoolingDataSource dataSource = new PoolingDataSource(connectionPool);</pre> * <p> @@ -117,7 +117,7 @@ * we create a {@link org.apache.commons.dbcp2.PoolingDriver}, and register the * {@code connectionPool} with it. E.g.,:</p> * <pre>GenericObjectPool connectionPool = new GenericObjectPool(null); - * ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "username", "password"); + * ConnectionFactory connectionFactory = new DriverManagerConnectionFactory("jdbc:some:connect:string", "userName", "password"); * PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,connectionPool,null,null,false,true); * PoolingDriver driver = new PoolingDriver(); * driver.registerPool("example",connectionPool);</pre> http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/site/xdoc/configuration.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/configuration.xml b/src/site/xdoc/configuration.xml index eabb23a..6a3935a 100644 --- a/src/site/xdoc/configuration.xml +++ b/src/site/xdoc/configuration.xml @@ -1,506 +1,506 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> - <!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - --> -<document> - - <properties> - <title>BasicDataSource Configuration</title> - <author email="[email protected]">Commons Documentation Team</author> - </properties> - - <body> - -<!-- -<section name="Introduction"> -<p>TODO: add section about tomcat configuration and avoiding the resource leak when reloading tomcat webapps.</p> -</section> ---> - -<!-- -<section name="Dynamic Properties"> -maxTotal -maxIdle -minIdle -maxWaitMillis -testOnBorrow -testOnReturn -timeBetweenEvictionRunsMillis -numTestsPerEvictionRun -minEvictableIdleTimeMillis -testWhileIdle - -</section> ---> - -<section name="BasicDataSource Configuration Parameters"> - -<table> -<hr><th>Parameter</th><th>Description</th></hr> -<tr> - <td>username</td> - <td>The connection username to be passed to our JDBC driver to establish a connection.</td> -</tr> -<tr> - <td>password</td> - <td>The connection password to be passed to our JDBC driver to establish a connection.</td> -</tr> -<tr> - <td>url</td> - <td>The connection URL to be passed to our JDBC driver to establish a connection.</td> -</tr> -<tr> - <td>driverClassName</td> - <td>The fully qualified Java class name of the JDBC driver to be used.</td> -</tr> -<tr> - <td>connectionProperties</td> - <td>The connection properties that will be sent to our JDBC driver when establishing new connections. - <br/>Format of the string must be [propertyName=property;]* - <br/><strong>NOTE</strong> - The "user" and "password" properties will be passed explicitly, - so they do not need to be included here. - </td> -</tr> -</table> - - -<table> -<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> -<tr> - <td>defaultAutoCommit</td> - <td>driver default</td> - <td>The default auto-commit state of connections created by this pool. - If not set then the setAutoCommit method will not be called. - </td> -</tr> -<tr> - <td>defaultReadOnly</td> - <td>driver default</td> - <td>The default read-only state of connections created by this pool. - If not set then the setReadOnly method will not be called. - (Some drivers don't support read only mode, ex: Informix) - </td> -</tr> -<tr> - <td>defaultTransactionIsolation</td> - <td>driver default</td> - <td>The default TransactionIsolation state of connections created by this pool. - One of the following: (see - <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Connection.html#field_summary";>javadoc</a>) - <ul> - <li>NONE</li> - <li>READ_COMMITTED</li> - <li>READ_UNCOMMITTED</li> - <li>REPEATABLE_READ</li> - <li>SERIALIZABLE</li> - </ul> - </td> -</tr> -<tr> - <td>defaultCatalog</td> - <td></td> - <td>The default catalog of connections created by this pool.</td> -</tr> -<tr> - <td>cacheState</td> - <td>true</td> - <td>If true, the pooled connection will cache the current readOnly and - autoCommit settings when first read or written and on all subsequent - writes. This removes the need for additional database queries for any - further calls to the getter. If the underlying connection is accessed - directly and the readOnly and/or autoCommit settings changed the cached - values will not reflect the current state. In this case, caching should be - disabled by setting this attribute to false.</td> -</tr> -<tr> - <td>defaultQueryTimeout</td> - <td>null</td> - <td>If non-null, the value of this <code>Integer</code> property determines - the query timeout that will be used for Statements created from - connections managed by the pool. <code>null</code> means that the driver - default will be used.</td> -</tr> -<tr> - <td>enableAutoCommitOnReturn</td> - <td>true</td> - <td>If true, connections being returned to the pool will be checked and configured with - <code>Connection.setAutoCommit(true)</code> if the auto commit setting is - <code>false</code> when the connection is returned.</td> -</tr> -<tr> - <td>rollbackOnReturn</td> - <td>true</td> - <td>True means a connection will be rolled back when returned to the pool if - auto commit is not enabled and the connection is not read-only.</td> -</tr> -</table> - - -<table> -<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> -<tr> - <td>initialSize</td> - <td>0</td> - <td> - The initial number of connections that are created when the pool - is started. - <br/>Since: 1.2 - </td> -</tr> -<tr> - <td>maxTotal</td> - <td>8</td> - <td> - The maximum number of active connections that can be allocated from - this pool at the same time, or negative for no limit. - </td> -</tr> -<tr> - <td>maxIdle</td> - <td>8</td> - <td> - The maximum number of connections that can remain idle in the - pool, without extra ones being released, or negative for no limit. - </td> -</tr> -<tr> - <td>minIdle</td> - <td>0</td> - <td> - The minimum number of connections that can remain idle in the - pool, without extra ones being created, or zero to create none. - </td> -</tr> -<tr> - <td>maxWaitMillis</td> - <td>indefinitely</td> - <td> - The maximum number of milliseconds that the pool will wait (when there - are no available connections) for a connection to be returned before - throwing an exception, or -1 to wait indefinitely. - </td> -</tr> -</table> -<p> -<img src="images/icon_warning_sml.gif"/> -<strong>NOTE</strong>: If maxIdle is set too low on heavily loaded systems it is -possible you will see connections being closed and almost immediately new -connections being opened. This is a result of the active threads momentarily -closing connections faster than they are opening them, causing the number of -idle connections to rise above maxIdle. The best value for maxIdle for heavily -loaded system will vary but the default is a good starting point. -</p> - - -<table> -<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> -<tr> - <td>validationQuery</td> - <td></td> - <td> -The SQL query that will be used to validate connections from this pool -before returning them to the caller. If specified, this query -<strong>MUST</strong> be an SQL SELECT statement that returns at least -one row. If not specified, connections will be validation by calling the -isValid() method. - </td> -</tr> -<tr> - <td>validationQueryTimeout</td> - <td>no timeout</td> - <td>The timeout in seconds before connection validation queries fail. If set - to a positive value, this value is passed to the driver via the - <code>setQueryTimeout</code> method of the <code>Statement</code> - used to execute the validation query.</td> -</tr> -<tr> - <td>testOnCreate</td> - <td>false</td> - <td> - The indication of whether objects will be validated after creation. If the - object fails to validate, the borrow attempt that triggered the object - creation will fail. - </td> -</tr> -<tr> - <td>testOnBorrow</td> - <td>true</td> - <td> - The indication of whether objects will be validated before being - borrowed from the pool. If the object fails to validate, it will be - dropped from the pool, and we will attempt to borrow another. - </td> -</tr> -<tr> - <td>testOnReturn</td> - <td>false</td> - <td> - The indication of whether objects will be validated before being - returned to the pool. - </td> -</tr> -<tr> - <td>testWhileIdle</td> - <td>false</td> - <td> - The indication of whether objects will be validated by the idle object - evictor (if any). If an object fails to validate, it will be dropped - from the pool. - </td> -</tr> -<tr> - <td>timeBetweenEvictionRunsMillis</td> - <td>-1</td> - <td> - The number of milliseconds to sleep between runs of the idle object - evictor thread. When non-positive, no idle object evictor thread will - be run. - </td> -</tr> -<tr> - <td>numTestsPerEvictionRun</td> - <td>3</td> - <td> - The number of objects to examine during each run of the idle object - evictor thread (if any). - </td> -</tr> -<tr> - <td>minEvictableIdleTimeMillis</td> - <td>1000 * 60 * 30</td> - <td> - The minimum amount of time an object may sit idle in the pool before it - is eligible for eviction by the idle object evictor (if any). - </td> -</tr> -<tr> - <td>softMinEvictableIdleTimeMillis</td> - <td>-1</td> - <td> - The minimum amount of time a connection may sit idle in the pool before - it is eligible for eviction by the idle connection evictor, with - the extra condition that at least "minIdle" connections remain in the - pool. When minEvictableIdleTimeMillis is set to a positive value, - minEvictableIdleTimeMillis is examined first by the idle - connection evictor - i.e. when idle connections are visited by the - evictor, idle time is first compared against minEvictableIdleTimeMillis - (without considering the number of idle connections in the pool) and then - against softMinEvictableIdleTimeMillis, including the minIdle constraint. - </td> -</tr> -<tr> - <td>maxConnLifetimeMillis</td> - <td>-1</td> - <td> - The maximum lifetime in milliseconds of a connection. After this time is - exceeded the connection will fail the next activation, passivation or - validation test. A value of zero or less means the connection has an - infinite lifetime. - </td> -</tr> -<tr> - <td>logExpiredConnections</td> - <td>true</td> - <td> - Flag to log a message indicating that a connection is being closed by the - pool due to maxConnLifetimeMillis exceeded. Set this property to false - to suppress expired connection logging that is turned on by default. - </td> -</tr> -<tr> - <td>connectionInitSqls</td> - <td>null</td> - <td> - A Collection of SQL statements that will be used to initialize physical - connections when they are first created. These statements are executed - only once - when the configured connection factory creates the connection. - </td> -</tr> -<tr> - <td>lifo</td> - <td>true</td> - <td> - True means that borrowObject returns the most recently used ("last in") - connection in the pool (if there are idle connections available). False - means that the pool behaves as a FIFO queue - connections are taken from - the idle instance pool in the order that they are returned to the pool. - </td> -</tr> -</table> - -<table> -<hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr> - <td>poolPreparedStatements</td> - <td>false</td> - <td>Enable prepared statement pooling for this pool.</td> -</tr> -<tr> - <td>maxOpenPreparedStatements</td> - <td>unlimited</td> - <td> - The maximum number of open statements that can be allocated from - the statement pool at the same time, or negative for no limit. - </td> -</tr> -</table> -<p> -<img src="images/icon_info_sml.gif"/> -This component has also the ability to pool PreparedStatements. -When enabled a statement pool will be created for each Connection -and PreparedStatements created by one of the following methods will be pooled: -<ul> - <li>public PreparedStatement prepareStatement(String sql)</li> - <li>public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)</li> -</ul> -</p> -<p> -<img src="images/icon_warning_sml.gif"/> -<strong>NOTE</strong> - Make sure your connection has some resources left for the other statements. -Pooling PreparedStatements may keep their cursors open in the database, causing a connection to run out of cursors, -especially if maxOpenPreparedStatements is left at the default (unlimited) and an application opens a large number -of different PreparedStatements per connection. To avoid this problem, maxOpenPreparedStatements should be set to a -value less than the maximum number of cursors that can be open on a Connection. -</p> - - -<table> -<hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr> - <td>accessToUnderlyingConnectionAllowed</td> - <td>false</td> - <td>Controls if the PoolGuard allows access to the underlying connection.</td> -</tr> -</table> -<p>When allowed you can access the underlying connection using the following construct:</p> -<source> - Connection conn = ds.getConnection(); - Connection dconn = ((DelegatingConnection) conn).getInnermostDelegate(); - ... - conn.close() -</source> -<p> -<img src="images/icon_info_sml.gif"/> -Default is false, it is a potential dangerous operation and misbehaving programs can do harmful things. (closing the underlying or continue using it when the guarded connection is already closed) -Be careful and only use when you need direct access to driver specific extensions. -</p> -<p> -<img src="images/icon_warning_sml.gif"/> -<b>NOTE:</b> Do not close the underlying connection, only the original one. -</p> - - -<table> -<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> -<tr> - <td>removeAbandonedOnMaintenance <br/> - removeAbandonedOnBorrow - </td> - <td>false</td> - <td> - Flags to remove abandoned connections if they exceed the - removeAbandonedTimout.<br/> - A connection is considered abandoned and eligible - for removal if it has not been used for longer than removeAbandonedTimeout.<br/> - Creating a Statement, PreparedStatement or CallableStatement or using - one of these to execute a query (using one of the execute methods) - resets the lastUsed property of the parent connection.<br/> - Setting one or both of these to true can recover db connections from poorly written - applications which fail to close connections.<br/> - Setting removeAbandonedOnMaintenance to true removes abandoned connections on the - maintenance cycle (when eviction ends). This property has no effect unless maintenance - is enabled by setting timeBetweenEvictionRunsMillis to a positive value. <br/> - If removeAbandonedOnBorrow is true, abandoned connections are removed each time - a connection is borrowed from the pool, with the additional requirements that - <ul><li>getNumActive() > getMaxTotal() - 3; and</li> - <li>getNumIdle() < 2 </li></ul> - </td> -</tr> -<tr> - <td>removeAbandonedTimeout</td> - <td>300</td> - <td>Timeout in <b>seconds</b> before an abandoned connection can be removed.</td> -</tr> -<tr> - <td>logAbandoned</td> - <td>false</td> - <td> - Flag to log stack traces for application code which abandoned - a Statement or Connection.<br/> - Logging of abandoned Statements and Connections adds overhead - for every Connection open or new Statement because a stack - trace has to be generated. - </td> -</tr> -<tr> - <td>abandonedUsageTracking</td> - <td>false</td> - <td> - If true, the connection pool records a stack trace every time a method is called on a - pooled connection and retains the most recent stack trace to aid debugging - of abandoned connections. There is significant overhead added by setting this - to true. - </td> -</tr> -</table> -<p> -<img src="images/icon_info_sml.gif"/> -If you have enabled removeAbandonedOnMaintenance or removeAbandonedOnBorrow then it is possible that -a connection is reclaimed by the pool because it is considered to be abandoned. This mechanism is triggered -when (getNumIdle() < 2) and (getNumActive() > getMaxTotal() - 3) and removeAbandonedOnBorrow is true; -or after eviction finishes and removeAbandonedOnMaintenance is true. For example, maxTotal=20 and 18 active -connections and 1 idle connection would trigger removeAbandonedOnBorrow, but only the active connections -that aren't used for more then "removeAbandonedTimeout" seconds are removed (default 300 sec). Traversing -a resultset doesn't count as being used. Creating a Statement, PreparedStatement or CallableStatement or -using one of these to execute a query (using one of the execute methods) resets the lastUsed property of -the parent connection. -</p> -<table> -<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> -<tr> - <td>fastFailValidation</td> - <td>false</td> - <td> - When this property is true, validation fails fast for connections that have - thrown "fatal" SQLExceptions. Requests to validate disconnected connections - fail immediately, with no call to the driver's isValid method or attempt to - execute a validation query.<br/> - The SQL_STATE codes considered to signal fatal errors are by default the following: - <ul> - <li>57P01 (ADMIN SHUTDOWN)</li> - <li>57P02 (CRASH SHUTDOWN)</li> - <li>57P03 (CANNOT CONNECT NOW)</li> - <li>01002 (SQL92 disconnect error)</li> - <li>JZ0C0 (Sybase disconnect error)</li> - <li>JZ0C1 (Sybase disconnect error)</li> - <li>Any SQL_STATE code that starts with "08"</li> - </ul> - To override this default set of disconnection codes, set the - <code>disconnectionSqlCodes</code> property. - </td> -</tr> -<tr> - <td>disconnectionSqlCodes</td> - <td>null</td> - <td>Comma-delimited list of SQL_STATE codes considered to signal fatal disconnection - errors. Setting this property has no effect unless - <code>fastFailValidation</code> is set to <code>true.</code> - </td> -</tr> -</table> - -</section> - -</body> -</document> +<?xml version="1.0" encoding="ISO-8859-1"?> + <!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> +<document> + + <properties> + <title>BasicDataSource Configuration</title> + <author email="[email protected]">Commons Documentation Team</author> + </properties> + + <body> + +<!-- +<section name="Introduction"> +<p>TODO: add section about tomcat configuration and avoiding the resource leak when reloading tomcat webapps.</p> +</section> +--> + +<!-- +<section name="Dynamic Properties"> +maxTotal +maxIdle +minIdle +maxWaitMillis +testOnBorrow +testOnReturn +timeBetweenEvictionRunsMillis +numTestsPerEvictionRun +minEvictableIdleTimeMillis +testWhileIdle + +</section> +--> + +<section name="BasicDataSource Configuration Parameters"> + +<table> +<hr><th>Parameter</th><th>Description</th></hr> +<tr> + <td>username</td> + <td>The connection user name to be passed to our JDBC driver to establish a connection.</td> +</tr> +<tr> + <td>password</td> + <td>The connection password to be passed to our JDBC driver to establish a connection.</td> +</tr> +<tr> + <td>url</td> + <td>The connection URL to be passed to our JDBC driver to establish a connection.</td> +</tr> +<tr> + <td>driverClassName</td> + <td>The fully qualified Java class name of the JDBC driver to be used.</td> +</tr> +<tr> + <td>connectionProperties</td> + <td>The connection properties that will be sent to our JDBC driver when establishing new connections. + <br/>Format of the string must be [propertyName=property;]* + <br/><strong>NOTE</strong> - The "user" and "password" properties will be passed explicitly, + so they do not need to be included here. + </td> +</tr> +</table> + + +<table> +<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> +<tr> + <td>defaultAutoCommit</td> + <td>driver default</td> + <td>The default auto-commit state of connections created by this pool. + If not set then the setAutoCommit method will not be called. + </td> +</tr> +<tr> + <td>defaultReadOnly</td> + <td>driver default</td> + <td>The default read-only state of connections created by this pool. + If not set then the setReadOnly method will not be called. + (Some drivers don't support read only mode, ex: Informix) + </td> +</tr> +<tr> + <td>defaultTransactionIsolation</td> + <td>driver default</td> + <td>The default TransactionIsolation state of connections created by this pool. + One of the following: (see + <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Connection.html#field_summary";>javadoc</a>) + <ul> + <li>NONE</li> + <li>READ_COMMITTED</li> + <li>READ_UNCOMMITTED</li> + <li>REPEATABLE_READ</li> + <li>SERIALIZABLE</li> + </ul> + </td> +</tr> +<tr> + <td>defaultCatalog</td> + <td></td> + <td>The default catalog of connections created by this pool.</td> +</tr> +<tr> + <td>cacheState</td> + <td>true</td> + <td>If true, the pooled connection will cache the current readOnly and + autoCommit settings when first read or written and on all subsequent + writes. This removes the need for additional database queries for any + further calls to the getter. If the underlying connection is accessed + directly and the readOnly and/or autoCommit settings changed the cached + values will not reflect the current state. In this case, caching should be + disabled by setting this attribute to false.</td> +</tr> +<tr> + <td>defaultQueryTimeout</td> + <td>null</td> + <td>If non-null, the value of this <code>Integer</code> property determines + the query timeout that will be used for Statements created from + connections managed by the pool. <code>null</code> means that the driver + default will be used.</td> +</tr> +<tr> + <td>enableAutoCommitOnReturn</td> + <td>true</td> + <td>If true, connections being returned to the pool will be checked and configured with + <code>Connection.setAutoCommit(true)</code> if the auto commit setting is + <code>false</code> when the connection is returned.</td> +</tr> +<tr> + <td>rollbackOnReturn</td> + <td>true</td> + <td>True means a connection will be rolled back when returned to the pool if + auto commit is not enabled and the connection is not read-only.</td> +</tr> +</table> + + +<table> +<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> +<tr> + <td>initialSize</td> + <td>0</td> + <td> + The initial number of connections that are created when the pool + is started. + <br/>Since: 1.2 + </td> +</tr> +<tr> + <td>maxTotal</td> + <td>8</td> + <td> + The maximum number of active connections that can be allocated from + this pool at the same time, or negative for no limit. + </td> +</tr> +<tr> + <td>maxIdle</td> + <td>8</td> + <td> + The maximum number of connections that can remain idle in the + pool, without extra ones being released, or negative for no limit. + </td> +</tr> +<tr> + <td>minIdle</td> + <td>0</td> + <td> + The minimum number of connections that can remain idle in the + pool, without extra ones being created, or zero to create none. + </td> +</tr> +<tr> + <td>maxWaitMillis</td> + <td>indefinitely</td> + <td> + The maximum number of milliseconds that the pool will wait (when there + are no available connections) for a connection to be returned before + throwing an exception, or -1 to wait indefinitely. + </td> +</tr> +</table> +<p> +<img src="images/icon_warning_sml.gif"/> +<strong>NOTE</strong>: If maxIdle is set too low on heavily loaded systems it is +possible you will see connections being closed and almost immediately new +connections being opened. This is a result of the active threads momentarily +closing connections faster than they are opening them, causing the number of +idle connections to rise above maxIdle. The best value for maxIdle for heavily +loaded system will vary but the default is a good starting point. +</p> + + +<table> +<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> +<tr> + <td>validationQuery</td> + <td></td> + <td> +The SQL query that will be used to validate connections from this pool +before returning them to the caller. If specified, this query +<strong>MUST</strong> be an SQL SELECT statement that returns at least +one row. If not specified, connections will be validation by calling the +isValid() method. + </td> +</tr> +<tr> + <td>validationQueryTimeout</td> + <td>no timeout</td> + <td>The timeout in seconds before connection validation queries fail. If set + to a positive value, this value is passed to the driver via the + <code>setQueryTimeout</code> method of the <code>Statement</code> + used to execute the validation query.</td> +</tr> +<tr> + <td>testOnCreate</td> + <td>false</td> + <td> + The indication of whether objects will be validated after creation. If the + object fails to validate, the borrow attempt that triggered the object + creation will fail. + </td> +</tr> +<tr> + <td>testOnBorrow</td> + <td>true</td> + <td> + The indication of whether objects will be validated before being + borrowed from the pool. If the object fails to validate, it will be + dropped from the pool, and we will attempt to borrow another. + </td> +</tr> +<tr> + <td>testOnReturn</td> + <td>false</td> + <td> + The indication of whether objects will be validated before being + returned to the pool. + </td> +</tr> +<tr> + <td>testWhileIdle</td> + <td>false</td> + <td> + The indication of whether objects will be validated by the idle object + evictor (if any). If an object fails to validate, it will be dropped + from the pool. + </td> +</tr> +<tr> + <td>timeBetweenEvictionRunsMillis</td> + <td>-1</td> + <td> + The number of milliseconds to sleep between runs of the idle object + evictor thread. When non-positive, no idle object evictor thread will + be run. + </td> +</tr> +<tr> + <td>numTestsPerEvictionRun</td> + <td>3</td> + <td> + The number of objects to examine during each run of the idle object + evictor thread (if any). + </td> +</tr> +<tr> + <td>minEvictableIdleTimeMillis</td> + <td>1000 * 60 * 30</td> + <td> + The minimum amount of time an object may sit idle in the pool before it + is eligible for eviction by the idle object evictor (if any). + </td> +</tr> +<tr> + <td>softMinEvictableIdleTimeMillis</td> + <td>-1</td> + <td> + The minimum amount of time a connection may sit idle in the pool before + it is eligible for eviction by the idle connection evictor, with + the extra condition that at least "minIdle" connections remain in the + pool. When minEvictableIdleTimeMillis is set to a positive value, + minEvictableIdleTimeMillis is examined first by the idle + connection evictor - i.e. when idle connections are visited by the + evictor, idle time is first compared against minEvictableIdleTimeMillis + (without considering the number of idle connections in the pool) and then + against softMinEvictableIdleTimeMillis, including the minIdle constraint. + </td> +</tr> +<tr> + <td>maxConnLifetimeMillis</td> + <td>-1</td> + <td> + The maximum lifetime in milliseconds of a connection. After this time is + exceeded the connection will fail the next activation, passivation or + validation test. A value of zero or less means the connection has an + infinite lifetime. + </td> +</tr> +<tr> + <td>logExpiredConnections</td> + <td>true</td> + <td> + Flag to log a message indicating that a connection is being closed by the + pool due to maxConnLifetimeMillis exceeded. Set this property to false + to suppress expired connection logging that is turned on by default. + </td> +</tr> +<tr> + <td>connectionInitSqls</td> + <td>null</td> + <td> + A Collection of SQL statements that will be used to initialize physical + connections when they are first created. These statements are executed + only once - when the configured connection factory creates the connection. + </td> +</tr> +<tr> + <td>lifo</td> + <td>true</td> + <td> + True means that borrowObject returns the most recently used ("last in") + connection in the pool (if there are idle connections available). False + means that the pool behaves as a FIFO queue - connections are taken from + the idle instance pool in the order that they are returned to the pool. + </td> +</tr> +</table> + +<table> +<hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr> + <td>poolPreparedStatements</td> + <td>false</td> + <td>Enable prepared statement pooling for this pool.</td> +</tr> +<tr> + <td>maxOpenPreparedStatements</td> + <td>unlimited</td> + <td> + The maximum number of open statements that can be allocated from + the statement pool at the same time, or negative for no limit. + </td> +</tr> +</table> +<p> +<img src="images/icon_info_sml.gif"/> +This component has also the ability to pool PreparedStatements. +When enabled a statement pool will be created for each Connection +and PreparedStatements created by one of the following methods will be pooled: +<ul> + <li>public PreparedStatement prepareStatement(String sql)</li> + <li>public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)</li> +</ul> +</p> +<p> +<img src="images/icon_warning_sml.gif"/> +<strong>NOTE</strong> - Make sure your connection has some resources left for the other statements. +Pooling PreparedStatements may keep their cursors open in the database, causing a connection to run out of cursors, +especially if maxOpenPreparedStatements is left at the default (unlimited) and an application opens a large number +of different PreparedStatements per connection. To avoid this problem, maxOpenPreparedStatements should be set to a +value less than the maximum number of cursors that can be open on a Connection. +</p> + + +<table> +<hr><th>Parameter</th><th>Default</th><th>Description</th></hr><tr> + <td>accessToUnderlyingConnectionAllowed</td> + <td>false</td> + <td>Controls if the PoolGuard allows access to the underlying connection.</td> +</tr> +</table> +<p>When allowed you can access the underlying connection using the following construct:</p> +<source> + Connection conn = ds.getConnection(); + Connection dconn = ((DelegatingConnection) conn).getInnermostDelegate(); + ... + conn.close() +</source> +<p> +<img src="images/icon_info_sml.gif"/> +Default is false, it is a potential dangerous operation and misbehaving programs can do harmful things. (closing the underlying or continue using it when the guarded connection is already closed) +Be careful and only use when you need direct access to driver specific extensions. +</p> +<p> +<img src="images/icon_warning_sml.gif"/> +<b>NOTE:</b> Do not close the underlying connection, only the original one. +</p> + + +<table> +<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> +<tr> + <td>removeAbandonedOnMaintenance <br/> + removeAbandonedOnBorrow + </td> + <td>false</td> + <td> + Flags to remove abandoned connections if they exceed the + removeAbandonedTimout.<br/> + A connection is considered abandoned and eligible + for removal if it has not been used for longer than removeAbandonedTimeout.<br/> + Creating a Statement, PreparedStatement or CallableStatement or using + one of these to execute a query (using one of the execute methods) + resets the lastUsed property of the parent connection.<br/> + Setting one or both of these to true can recover db connections from poorly written + applications which fail to close connections.<br/> + Setting removeAbandonedOnMaintenance to true removes abandoned connections on the + maintenance cycle (when eviction ends). This property has no effect unless maintenance + is enabled by setting timeBetweenEvictionRunsMillis to a positive value. <br/> + If removeAbandonedOnBorrow is true, abandoned connections are removed each time + a connection is borrowed from the pool, with the additional requirements that + <ul><li>getNumActive() > getMaxTotal() - 3; and</li> + <li>getNumIdle() < 2 </li></ul> + </td> +</tr> +<tr> + <td>removeAbandonedTimeout</td> + <td>300</td> + <td>Timeout in <b>seconds</b> before an abandoned connection can be removed.</td> +</tr> +<tr> + <td>logAbandoned</td> + <td>false</td> + <td> + Flag to log stack traces for application code which abandoned + a Statement or Connection.<br/> + Logging of abandoned Statements and Connections adds overhead + for every Connection open or new Statement because a stack + trace has to be generated. + </td> +</tr> +<tr> + <td>abandonedUsageTracking</td> + <td>false</td> + <td> + If true, the connection pool records a stack trace every time a method is called on a + pooled connection and retains the most recent stack trace to aid debugging + of abandoned connections. There is significant overhead added by setting this + to true. + </td> +</tr> +</table> +<p> +<img src="images/icon_info_sml.gif"/> +If you have enabled removeAbandonedOnMaintenance or removeAbandonedOnBorrow then it is possible that +a connection is reclaimed by the pool because it is considered to be abandoned. This mechanism is triggered +when (getNumIdle() < 2) and (getNumActive() > getMaxTotal() - 3) and removeAbandonedOnBorrow is true; +or after eviction finishes and removeAbandonedOnMaintenance is true. For example, maxTotal=20 and 18 active +connections and 1 idle connection would trigger removeAbandonedOnBorrow, but only the active connections +that aren't used for more then "removeAbandonedTimeout" seconds are removed (default 300 sec). Traversing +a resultset doesn't count as being used. Creating a Statement, PreparedStatement or CallableStatement or +using one of these to execute a query (using one of the execute methods) resets the lastUsed property of +the parent connection. +</p> +<table> +<hr><th>Parameter</th><th>Default</th><th>Description</th></hr> +<tr> + <td>fastFailValidation</td> + <td>false</td> + <td> + When this property is true, validation fails fast for connections that have + thrown "fatal" SQLExceptions. Requests to validate disconnected connections + fail immediately, with no call to the driver's isValid method or attempt to + execute a validation query.<br/> + The SQL_STATE codes considered to signal fatal errors are by default the following: + <ul> + <li>57P01 (ADMIN SHUTDOWN)</li> + <li>57P02 (CRASH SHUTDOWN)</li> + <li>57P03 (CANNOT CONNECT NOW)</li> + <li>01002 (SQL92 disconnect error)</li> + <li>JZ0C0 (Sybase disconnect error)</li> + <li>JZ0C1 (Sybase disconnect error)</li> + <li>Any SQL_STATE code that starts with "08"</li> + </ul> + To override this default set of disconnection codes, set the + <code>disconnectionSqlCodes</code> property. + </td> +</tr> +<tr> + <td>disconnectionSqlCodes</td> + <td>null</td> + <td>Comma-delimited list of SQL_STATE codes considered to signal fatal disconnection + errors. Setting this property has no effect unless + <code>fastFailValidation</code> is set to <code>true.</code> + </td> +</tr> +</table> + +</section> + +</body> +</document> http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/site/xdoc/guide/jndi-howto.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/guide/jndi-howto.xml b/src/site/xdoc/guide/jndi-howto.xml index 60d950c..c803f20 100644 --- a/src/site/xdoc/guide/jndi-howto.xml +++ b/src/site/xdoc/guide/jndi-howto.xml @@ -56,7 +56,7 @@ BasicDataSource bds = new BasicDataSource(); bds.setDriverClassName("org.apache.commons.dbcp2.TesterDriver"); bds.setUrl("jdbc:apache:commons:testdriver"); - bds.setUsername("username"); + bds.setUsername("userName"); bds.setPassword("password"); ic.rebind("jdbc/basic", bds); http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/test/java/org/apache/commons/dbcp2/TesterConnection.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/dbcp2/TesterConnection.java b/src/test/java/org/apache/commons/dbcp2/TesterConnection.java index 103a841..cf1ad21 100644 --- a/src/test/java/org/apache/commons/dbcp2/TesterConnection.java +++ b/src/test/java/org/apache/commons/dbcp2/TesterConnection.java @@ -50,16 +50,16 @@ public class TesterConnection implements Connection { protected Map<String,Class<?>> _typeMap = null; protected boolean _readOnly = false; protected SQLWarning warnings = null; - protected String username = null; + protected String userName = null; protected Exception failure; - public TesterConnection(final String username, + public TesterConnection(final String userName, @SuppressWarnings("unused") final String password) { - this.username = username; + this.userName = userName; } - public String getUsername() { - return this.username; + public String getUserName() { + return this.userName; } public void setWarnings(final SQLWarning warning) { http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/test/java/org/apache/commons/dbcp2/TesterDriver.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/dbcp2/TesterDriver.java b/src/test/java/org/apache/commons/dbcp2/TesterDriver.java index eb6352a..5c4f62b 100644 --- a/src/test/java/org/apache/commons/dbcp2/TesterDriver.java +++ b/src/test/java/org/apache/commons/dbcp2/TesterDriver.java @@ -29,7 +29,7 @@ import java.util.logging.Logger; /** * Mock object implementing the <code>java.sql.Driver</code> interface. * Returns <code>TestConnection</code>'s from getConnection methods. - * Valid username, password combinations are: + * Valid user name, password combinations are: * * <table summary="valid credentials"> * <tr><th>user</th><th>password</th></tr> @@ -59,9 +59,9 @@ public class TesterDriver implements Driver { /** * TesterDriver specific method to add users to the list of valid users */ - public static void addUser(final String username, final String password) { + public static void addUser(final String userName, final String password) { synchronized (validUserPasswords) { - validUserPasswords.put(username, password); + validUserPasswords.put(userName, password); } } @@ -70,18 +70,18 @@ public class TesterDriver implements Driver { return url != null && url.startsWith(CONNECT_STRING); } - private void assertValidUserPassword(final String user, final String password) + private void assertValidUserPassword(final String userName, final String password) throws SQLException { - if (user == null){ - throw new SQLException("username cannot be null."); + if (userName == null){ + throw new SQLException("user name cannot be null."); } synchronized (validUserPasswords) { - final String realPassword = validUserPasswords.getProperty(user); + final String realPassword = validUserPasswords.getProperty(userName); if (realPassword == null) { - throw new SQLException(user + " is not a valid username."); + throw new SQLException(userName + " is not a valid user name."); } if (!realPassword.equals(password)) { - throw new SQLException(password + " is not the correct password for " + user + throw new SQLException(password + " is not the correct password for " + userName + ". The correct password is " + realPassword); } } @@ -93,22 +93,22 @@ public class TesterDriver implements Driver { Connection conn = null; if (acceptsURL(url)) { - String username = "test"; + String userName = "test"; String password = "test"; if (info != null) { - username = info.getProperty("user"); + userName = info.getProperty("user"); password = info.getProperty("password"); - if (username == null) { + if (userName == null) { final String[] parts = url.split(";"); - username = parts[1]; - username = username.split("=")[1]; + userName = parts[1]; + userName = userName.split("=")[1]; password = parts[2]; password = password.split("=")[1]; } - assertValidUserPassword(username, password); + assertValidUserPassword(userName, password); } - conn = new TesterConnection(username, password); + conn = new TesterConnection(userName, password); } return conn; http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/test/java/org/apache/commons/dbcp2/TesterStatement.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/dbcp2/TesterStatement.java b/src/test/java/org/apache/commons/dbcp2/TesterStatement.java index 8081c9e..590c4e5 100644 --- a/src/test/java/org/apache/commons/dbcp2/TesterStatement.java +++ b/src/test/java/org/apache/commons/dbcp2/TesterStatement.java @@ -77,8 +77,8 @@ public class TesterStatement implements Statement { throw new SQLException("broken connection"); } if("select username".equals(sql)) { - final String username = ((TesterConnection) _connection).getUsername(); - final Object[][] data = {{username}}; + final String userName = ((TesterConnection) _connection).getUserName(); + final Object[][] data = {{userName}}; return new TesterResultSet(this, data); } // Simulate timeout if queryTimout is set to less than 5 seconds http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/test/java/org/apache/commons/dbcp2/datasources/TestInstanceKeyDataSource.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/dbcp2/datasources/TestInstanceKeyDataSource.java b/src/test/java/org/apache/commons/dbcp2/datasources/TestInstanceKeyDataSource.java index 1cb00d0..654a677 100644 --- a/src/test/java/org/apache/commons/dbcp2/datasources/TestInstanceKeyDataSource.java +++ b/src/test/java/org/apache/commons/dbcp2/datasources/TestInstanceKeyDataSource.java @@ -65,7 +65,7 @@ public class TestInstanceKeyDataSource { super(); } @Override - protected void setupDefaults(final Connection con, final String username) + protected void setupDefaults(final Connection connection, final String userName) throws SQLException { throw new SQLException("bang!"); } http://git-wip-us.apache.org/repos/asf/commons-dbcp/blob/80287ea5/src/test/java/org/apache/commons/dbcp2/datasources/TestPerUserPoolDataSource.java ---------------------------------------------------------------------- diff --git a/src/test/java/org/apache/commons/dbcp2/datasources/TestPerUserPoolDataSource.java b/src/test/java/org/apache/commons/dbcp2/datasources/TestPerUserPoolDataSource.java index 0a0b7a5..79be39c 100644 --- a/src/test/java/org/apache/commons/dbcp2/datasources/TestPerUserPoolDataSource.java +++ b/src/test/java/org/apache/commons/dbcp2/datasources/TestPerUserPoolDataSource.java @@ -427,7 +427,7 @@ public class TestPerUserPoolDataSource extends TestConnectionPool { } // see issue http://issues.apache.org/bugzilla/show_bug.cgi?id=23843 - // unregistered user is in the same pool as without username + // unregistered user is in the same pool as without user name @Test public void testUnregisteredUser() throws Exception { final PerUserPoolDataSource tds = (PerUserPoolDataSource) ds;
