Modified: tomcat/tc8.0.x/trunk/java/org/apache/tomcat/dbcp/dbcp2/BasicDataSource.java URL: http://svn.apache.org/viewvc/tomcat/tc8.0.x/trunk/java/org/apache/tomcat/dbcp/dbcp2/BasicDataSource.java?rev=1833816&r1=1833815&r2=1833816&view=diff ============================================================================== --- tomcat/tc8.0.x/trunk/java/org/apache/tomcat/dbcp/dbcp2/BasicDataSource.java (original) +++ tomcat/tc8.0.x/trunk/java/org/apache/tomcat/dbcp/dbcp2/BasicDataSource.java Tue Jun 19 11:21:13 2018 @@ -18,7 +18,6 @@ package org.apache.tomcat.dbcp.dbcp2; import java.io.OutputStreamWriter; import java.io.PrintWriter; -import java.lang.management.ManagementFactory; import java.nio.charset.StandardCharsets; import java.security.AccessController; import java.security.PrivilegedActionException; @@ -33,17 +32,14 @@ import java.util.Collection; import java.util.Collections; import java.util.HashSet; import java.util.List; +import java.util.Objects; import java.util.Properties; import java.util.Set; import java.util.logging.Logger; -import javax.management.InstanceAlreadyExistsException; -import javax.management.JMException; import javax.management.MBeanRegistration; -import javax.management.MBeanRegistrationException; import javax.management.MBeanServer; import javax.management.MalformedObjectNameException; -import javax.management.NotCompliantMBeanException; import javax.management.ObjectName; import javax.sql.DataSource; @@ -57,14 +53,12 @@ import org.apache.tomcat.dbcp.pool2.impl import org.apache.tomcat.dbcp.pool2.impl.GenericObjectPoolConfig; /** - * <p>Basic implementation of <code>javax.sql.DataSource</code> that is - * configured via JavaBeans properties. This is not the only way to - * combine the <em>commons-dbcp2</em> and <em>commons-pool2</em> packages, - * but provides a "one stop shopping" solution for basic requirements.</p> + * <p> + * Basic implementation of <code>javax.sql.DataSource</code> that is configured via JavaBeans properties. This is not + * the only way to combine the <em>commons-dbcp2</em> and <em>commons-pool2</em> packages, but provides a "one stop + * shopping" solution for basic requirements. + * </p> * - * @author Glenn L. Nielsen - * @author Craig R. McClanahan - * @author Dirk Verbeeck * @since 2.0 */ public class BasicDataSource implements DataSource, BasicDataSourceMXBean, MBeanRegistration, AutoCloseable { @@ -119,21 +113,22 @@ public class BasicDataSource implements } /** - * <p>Sets default auto-commit state of connections returned by this - * datasource.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets default auto-commit state of connections returned by this datasource. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param defaultAutoCommit default auto-commit value + * @param defaultAutoCommit + * default auto-commit value */ public void setDefaultAutoCommit(final Boolean defaultAutoCommit) { this.defaultAutoCommit = defaultAutoCommit; } - /** * The default read-only state of connections created by this pool. */ @@ -150,14 +145,17 @@ public class BasicDataSource implements } /** - * <p>Sets defaultReadonly property.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets defaultReadonly property. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param defaultReadOnly default read-only value + * @param defaultReadOnly + * default read-only value */ public void setDefaultReadOnly(final Boolean defaultReadOnly) { this.defaultReadOnly = defaultReadOnly; @@ -166,8 +164,7 @@ public class BasicDataSource implements /** * The default TransactionIsolation state of connections created by this pool. */ - private volatile int defaultTransactionIsolation = - PoolableConnectionFactory.UNKNOWN_TRANSACTIONISOLATION; + private volatile int defaultTransactionIsolation = PoolableConnectionFactory.UNKNOWN_TRANSACTIONISOLATION; /** * Returns the default transaction isolation state of returned connections. @@ -181,45 +178,46 @@ public class BasicDataSource implements } /** - * <p>Sets the default transaction isolation state for returned - * connections.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the default transaction isolation state for returned connections. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param defaultTransactionIsolation the default transaction isolation - * state + * @param defaultTransactionIsolation + * the default transaction isolation state * @see Connection#getTransactionIsolation */ public void setDefaultTransactionIsolation(final int defaultTransactionIsolation) { this.defaultTransactionIsolation = defaultTransactionIsolation; } - - private Integer defaultQueryTimeout; + private Integer defaultQueryTimeoutSeconds; /** - * Obtain the default query timeout that will be used for {@link java.sql.Statement Statement}s - * created from this connection. <code>null</code> means that the driver - * default will be used. + * Gets the default query timeout that will be used for {@link java.sql.Statement Statement}s created from this + * connection. <code>null</code> means that the driver default will be used. + * + * @return The default query timeout in seconds. */ public Integer getDefaultQueryTimeout() { - return defaultQueryTimeout; + return defaultQueryTimeoutSeconds; } - /** - * Set the default query timeout that will be used for {@link java.sql.Statement Statement}s - * created from this connection. <code>null</code> means that the driver - * default will be used. + * Sets the default query timeout that will be used for {@link java.sql.Statement Statement}s created from this + * connection. <code>null</code> means that the driver default will be used. + * + * @param defaultQueryTimeoutSeconds + * The default query timeout in seconds. */ - public void setDefaultQueryTimeout(final Integer defaultQueryTimeout) { - this.defaultQueryTimeout = defaultQueryTimeout; + public void setDefaultQueryTimeout(final Integer defaultQueryTimeoutSeconds) { + this.defaultQueryTimeoutSeconds = defaultQueryTimeoutSeconds; } - /** * The default "catalog" of connections created by this pool. */ @@ -236,34 +234,36 @@ public class BasicDataSource implements } /** - * <p>Sets the default catalog.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the default catalog. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param defaultCatalog the default catalog + * @param defaultCatalog + * the default catalog */ public void setDefaultCatalog(final String defaultCatalog) { if (defaultCatalog != null && defaultCatalog.trim().length() > 0) { this.defaultCatalog = defaultCatalog; - } - else { + } else { this.defaultCatalog = null; } } /** - * The property that controls if the pooled connections cache some state - * rather than query the database for current state to improve performance. + * The property that controls if the pooled connections cache some state rather than query the database for current + * state to improve performance. */ private boolean cacheState = true; /** * Returns the state caching flag. * - * @return the state caching flag + * @return the state caching flag */ @Override public boolean getCacheState() { @@ -273,7 +273,8 @@ public class BasicDataSource implements /** * Sets the state caching flag. * - * @param cacheState The new value for the state caching flag + * @param cacheState + * The new value for the state caching flag */ public void setCacheState(final boolean cacheState) { this.cacheState = cacheState; @@ -287,10 +288,9 @@ public class BasicDataSource implements /** * Returns the JDBC Driver that has been configured for use by this pool. * <p> - * Note: This getter only returns the last value set by a call to - * {@link #setDriver(Driver)}. It does not return any driver instance that - * may have been created from the value set via - * {@link #setDriverClassName(String)}. + * Note: This getter only returns the last value set by a call to {@link #setDriver(Driver)}. It does not return any + * driver instance that may have been created from the value set via {@link #setDriverClassName(String)}. + * </p> * * @return the JDBC Driver that has been configured for use by this pool */ @@ -301,12 +301,13 @@ public class BasicDataSource implements /** * Sets the JDBC Driver instance to use for this pool. * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * * @param driver + * The JDBC Driver instance to use for this pool. */ public synchronized void setDriver(final Driver driver) { this.driver = driver; @@ -320,9 +321,9 @@ public class BasicDataSource implements /** * Returns the JDBC driver class name. * <p> - * Note: This getter only returns the last value set by a call to - * {@link #setDriverClassName(String)}. It does not return the class name of - * any driver that may have been set via {@link #setDriver(Driver)}. + * Note: This getter only returns the last value set by a call to {@link #setDriverClassName(String)}. It does not + * return the class name of any driver that may have been set via {@link #setDriver(Driver)}. + * </p> * * @return the JDBC driver class name */ @@ -332,66 +333,67 @@ public class BasicDataSource implements } /** - * <p>Sets the JDBC driver class name.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the JDBC driver class name. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param driverClassName the class name of the JDBC driver + * @param driverClassName + * the class name of the JDBC driver */ public synchronized void setDriverClassName(final String driverClassName) { if (driverClassName != null && driverClassName.trim().length() > 0) { this.driverClassName = driverClassName; - } - else { + } else { this.driverClassName = null; } } /** - * The class loader instance to use to load the JDBC driver. If not - * specified, {@link Class#forName(String)} is used to load the JDBC driver. - * If specified, {@link Class#forName(String, boolean, ClassLoader)} is - * used. + * The class loader instance to use to load the JDBC driver. If not specified, {@link Class#forName(String)} is used + * to load the JDBC driver. If specified, {@link Class#forName(String, boolean, ClassLoader)} is used. */ private ClassLoader driverClassLoader; /** - * Returns the class loader specified for loading the JDBC driver. Returns - * <code>null</code> if no class loader has been explicitly specified. + * Returns the class loader specified for loading the JDBC driver. Returns <code>null</code> if no class loader has + * been explicitly specified. * <p> - * Note: This getter only returns the last value set by a call to - * {@link #setDriverClassLoader(ClassLoader)}. It does not return the class - * loader of any driver that may have been set via - * {@link #setDriver(Driver)}. + * Note: This getter only returns the last value set by a call to {@link #setDriverClassLoader(ClassLoader)}. It + * does not return the class loader of any driver that may have been set via {@link #setDriver(Driver)}. + * </p> + * + * @return The class loader specified for loading the JDBC driver. */ public synchronized ClassLoader getDriverClassLoader() { return this.driverClassLoader; } /** - * <p>Sets the class loader to be used to load the JDBC driver.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the class loader to be used to load the JDBC driver. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param driverClassLoader the class loader with which to load the JDBC - * driver + * @param driverClassLoader + * the class loader with which to load the JDBC driver */ - public synchronized void setDriverClassLoader( - final ClassLoader driverClassLoader) { + public synchronized void setDriverClassLoader(final ClassLoader driverClassLoader) { this.driverClassLoader = driverClassLoader; } /** - * 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. + * 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. */ private boolean lifo = BaseObjectPoolConfig.DEFAULT_LIFO; @@ -406,10 +408,10 @@ public class BasicDataSource implements } /** - * Sets the LIFO property. True means the pool behaves as a LIFO queue; - * false means FIFO. + * Sets the LIFO property. True means the pool behaves as a LIFO queue; false means FIFO. * - * @param lifo the new value for the LIFO property + * @param lifo + * the new value for the LIFO property * */ public synchronized void setLifo(final boolean lifo) { @@ -420,16 +422,18 @@ public class BasicDataSource implements } /** - * The maximum number of active connections that can be allocated from - * this pool at the same time, or negative for no limit. + * The maximum number of active connections that can be allocated from this pool at the same time, or negative for + * no limit. */ private int maxTotal = GenericObjectPoolConfig.DEFAULT_MAX_TOTAL; /** - * <p>Returns the maximum number of active connections that can be - * allocated at the same time. + * <p> + * Returns the maximum number of active connections that can be allocated at the same time. + * </p> + * <p> + * A negative number means that there is no limit. * </p> - * <p>A negative number means that there is no limit.</p> * * @return the maximum number of active connections */ @@ -439,10 +443,11 @@ public class BasicDataSource implements } /** - * Sets the maximum total number of idle and borrows connections that can be - * active at the same time. Use a negative value for no limit. + * Sets the maximum total number of idle and borrows connections that can be active at the same time. Use a negative + * value for no limit. * - * @param maxTotal the new value for maxTotal + * @param maxTotal + * the new value for maxTotal * @see #getMaxTotal() */ public synchronized void setMaxTotal(final int maxTotal) { @@ -453,22 +458,23 @@ public class BasicDataSource implements } /** - * The maximum number of connections that can remain idle in the - * pool, without extra ones being destroyed, or negative for no limit. - * 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. + * The maximum number of connections that can remain idle in the pool, without extra ones being destroyed, or + * negative for no limit. 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. */ private int maxIdle = GenericObjectPoolConfig.DEFAULT_MAX_IDLE; /** - * <p>Returns the maximum number of connections that can remain idle in the - * pool. Excess idle connections are destroyed on return to the pool. + * <p> + * Returns the maximum number of connections that can remain idle in the pool. Excess idle connections are destroyed + * on return to the pool. + * </p> + * <p> + * A negative value indicates that there is no limit * </p> - * <p>A negative value indicates that there is no limit</p> * * @return the maximum number of idle connections */ @@ -478,11 +484,12 @@ public class BasicDataSource implements } /** - * Sets the maximum number of connections that can remain idle in the - * pool. Excess idle connections are destroyed on return to the pool. + * Sets the maximum number of connections that can remain idle in the pool. Excess idle connections are destroyed on + * return to the pool. * * @see #getMaxIdle() - * @param maxIdle the new value for maxIdle + * @param maxIdle + * the new value for maxIdle */ public synchronized void setMaxIdle(final int maxIdle) { this.maxIdle = maxIdle; @@ -492,19 +499,17 @@ public class BasicDataSource implements } /** - * The minimum number of active connections that can remain idle in the - * pool, without extra ones being created when the evictor runs, or 0 to create none. - * The pool attempts to ensure that minIdle connections are available when the idle object evictor - * runs. The value of this property has no effect unless {@link #timeBetweenEvictionRunsMillis} - * has a positive value. + * The minimum number of active connections that can remain idle in the pool, without extra ones being created when + * the evictor runs, or 0 to create none. The pool attempts to ensure that minIdle connections are available when + * the idle object evictor runs. The value of this property has no effect unless + * {@link #timeBetweenEvictionRunsMillis} has a positive value. */ private int minIdle = GenericObjectPoolConfig.DEFAULT_MIN_IDLE; /** - * Returns the minimum number of idle connections in the pool. The pool attempts - * to ensure that minIdle connections are available when the idle object evictor - * runs. The value of this property has no effect unless {@link #timeBetweenEvictionRunsMillis} - * has a positive value. + * Returns the minimum number of idle connections in the pool. The pool attempts to ensure that minIdle connections + * are available when the idle object evictor runs. The value of this property has no effect unless + * {@link #timeBetweenEvictionRunsMillis} has a positive value. * * @return the minimum number of idle connections * @see GenericObjectPool#getMinIdle() @@ -515,24 +520,23 @@ public class BasicDataSource implements } /** - * Sets the minimum number of idle connections in the pool. The pool attempts - * to ensure that minIdle connections are available when the idle object evictor - * runs. The value of this property has no effect unless {@link #timeBetweenEvictionRunsMillis} - * has a positive value. + * Sets the minimum number of idle connections in the pool. The pool attempts to ensure that minIdle connections are + * available when the idle object evictor runs. The value of this property has no effect unless + * {@link #timeBetweenEvictionRunsMillis} has a positive value. * - * @param minIdle the new value for minIdle + * @param minIdle + * the new value for minIdle * @see GenericObjectPool#setMinIdle(int) */ public synchronized void setMinIdle(final int minIdle) { - this.minIdle = minIdle; - if (connectionPool != null) { - connectionPool.setMinIdle(minIdle); - } + this.minIdle = minIdle; + if (connectionPool != null) { + connectionPool.setMinIdle(minIdle); + } } /** - * The initial number of connections that are created when the pool - * is started. + * The initial number of connections that are created when the pool is started. */ private int initialSize = 0; @@ -547,32 +551,31 @@ public class BasicDataSource implements } /** - * <p>Sets the initial size of the connection pool.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the initial size of the connection pool. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param initialSize the number of connections created when the pool - * is initialized + * @param initialSize + * the number of connections created when the pool is initialized */ public synchronized void setInitialSize(final int initialSize) { this.initialSize = initialSize; } /** - * 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 <= 0 to wait indefinitely. + * 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 <= 0 to wait indefinitely. */ - private long maxWaitMillis = - BaseObjectPoolConfig.DEFAULT_MAX_WAIT_MILLIS; + private long maxWaitMillis = BaseObjectPoolConfig.DEFAULT_MAX_WAIT_MILLIS; /** - * Returns the maximum number of milliseconds that the pool will wait - * for a connection to be returned before throwing an exception. A value - * less than or equal to zero means the pool is set to wait indefinitely. + * Returns the maximum number of milliseconds that the pool will wait for a connection to be returned before + * throwing an exception. A value less than or equal to zero means the pool is set to wait indefinitely. * * @return the maxWaitMillis property value */ @@ -582,10 +585,10 @@ public class BasicDataSource implements } /** - * Sets the MaxWaitMillis property. Use -1 to make the pool wait - * indefinitely. + * Sets the MaxWaitMillis property. Use -1 to make the pool wait indefinitely. * - * @param maxWaitMillis the new value for MaxWaitMillis + * @param maxWaitMillis + * the new value for MaxWaitMillis * @see #getMaxWaitMillis() */ public synchronized void setMaxWaitMillis(final long maxWaitMillis) { @@ -596,8 +599,8 @@ public class BasicDataSource implements } /** - * Prepared statement pooling for this pool. When this property is set to <code>true</code> - * both PreparedStatements and CallableStatements are pooled. + * Prepared statement pooling for this pool. When this property is set to <code>true</code> both PreparedStatements + * and CallableStatements are pooled. */ private boolean poolPreparedStatements = false; @@ -612,32 +615,36 @@ public class BasicDataSource implements } /** - * <p>Sets whether to pool statements or not.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets whether to pool statements or not. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param poolingStatements pooling on or off + * @param poolingStatements + * pooling on or off */ public synchronized void setPoolPreparedStatements(final boolean poolingStatements) { this.poolPreparedStatements = poolingStatements; } /** - * <p>The maximum number of open statements that can be allocated from - * the statement pool at the same time, or negative for no limit. Since - * a connection usually only uses one or two statements at a time, this is - * mostly used to help detect resource leaks.</p> - * - * <p>Note: As of version 1.3, CallableStatements (those produced by {@link Connection#prepareCall}) - * are pooled along with PreparedStatements (produced by {@link Connection#prepareStatement}) - * and <code>maxOpenPreparedStatements</code> limits the total number of prepared or callable statements - * that may be in use at a given time.</p> + * <p> + * The maximum number of open statements that can be allocated from the statement pool at the same time, or negative + * for no limit. Since a connection usually only uses one or two statements at a time, this is mostly used to help + * detect resource leaks. + * </p> + * <p> + * Note: As of version 1.3, CallableStatements (those produced by {@link Connection#prepareCall}) are pooled along + * with PreparedStatements (produced by {@link Connection#prepareStatement}) and + * <code>maxOpenPreparedStatements</code> limits the total number of prepared or callable statements that may be in + * use at a given time. + * </p> */ - private int maxOpenPreparedStatements = - GenericKeyedObjectPoolConfig.DEFAULT_MAX_TOTAL; + private int maxOpenPreparedStatements = GenericKeyedObjectPoolConfig.DEFAULT_MAX_TOTAL; /** * Gets the value of the <code>maxOpenPreparedStatements</code> property. @@ -650,33 +657,32 @@ public class BasicDataSource implements } /** - * <p>Sets the value of the <code>maxOpenPreparedStatements</code> - * property.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the value of the <code>maxOpenPreparedStatements</code> property. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param maxOpenStatements the new maximum number of prepared statements + * @param maxOpenStatements + * the new maximum number of prepared statements */ public synchronized void setMaxOpenPreparedStatements(final int maxOpenStatements) { this.maxOpenPreparedStatements = maxOpenStatements; } /** - * The indication of whether objects will be validated as soon as they have - * been created by the pool. If the object fails to validate, the borrow - * operation that triggered the creation will fail. + * The indication of whether objects will be validated as soon as they have been created by the pool. If the object + * fails to validate, the borrow operation that triggered the creation will fail. */ private boolean testOnCreate = false; /** * Returns the {@link #testOnCreate} property. * - * @return true if objects are validated immediately after they are created - * by the pool - * + * @return true if objects are validated immediately after they are created by the pool * @see #testOnCreate */ @Override @@ -685,11 +691,11 @@ public class BasicDataSource implements } /** - * Sets the {@link #testOnCreate} property. This property determines - * whether or not the pool will validate objects immediately after they are - * created by the pool + * Sets the {@link #testOnCreate} property. This property determines whether or not the pool will validate objects + * immediately after they are created by the pool * - * @param testOnCreate new value for testOnCreate property + * @param testOnCreate + * new value for testOnCreate property */ public synchronized void setTestOnCreate(final boolean testOnCreate) { this.testOnCreate = testOnCreate; @@ -699,17 +705,15 @@ public class BasicDataSource implements } /** - * 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. + * 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. */ private boolean testOnBorrow = true; /** * Returns the {@link #testOnBorrow} property. * - * @return true if objects are validated before being borrowed from the - * pool + * @return true if objects are validated before being borrowed from the pool * * @see #testOnBorrow */ @@ -719,11 +723,11 @@ public class BasicDataSource implements } /** - * Sets the {@link #testOnBorrow} property. This property determines - * whether or not the pool will validate objects before they are borrowed - * from the pool. + * Sets the {@link #testOnBorrow} property. This property determines whether or not the pool will validate objects + * before they are borrowed from the pool. * - * @param testOnBorrow new value for testOnBorrow property + * @param testOnBorrow + * new value for testOnBorrow property */ public synchronized void setTestOnBorrow(final boolean testOnBorrow) { this.testOnBorrow = testOnBorrow; @@ -733,16 +737,14 @@ public class BasicDataSource implements } /** - * The indication of whether objects will be validated before being - * returned to the pool. + * The indication of whether objects will be validated before being returned to the pool. */ private boolean testOnReturn = false; /** * Returns the value of the {@link #testOnReturn} property. * - * @return true if objects are validated before being returned to the - * pool + * @return true if objects are validated before being returned to the pool * @see #testOnReturn */ public synchronized boolean getTestOnReturn() { @@ -750,11 +752,11 @@ public class BasicDataSource implements } /** - * Sets the <code>testOnReturn</code> property. This property determines - * whether or not the pool will validate objects before they are returned - * to the pool. + * Sets the <code>testOnReturn</code> property. This property determines whether or not the pool will validate + * objects before they are returned to the pool. * - * @param testOnReturn new value for testOnReturn property + * @param testOnReturn + * new value for testOnReturn property */ public synchronized void setTestOnReturn(final boolean testOnReturn) { this.testOnReturn = testOnReturn; @@ -764,16 +766,13 @@ public class BasicDataSource implements } /** - * 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. + * 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. */ - private long timeBetweenEvictionRunsMillis = - BaseObjectPoolConfig.DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS; + private long timeBetweenEvictionRunsMillis = BaseObjectPoolConfig.DEFAULT_TIME_BETWEEN_EVICTION_RUNS_MILLIS; /** - * Returns the value of the {@link #timeBetweenEvictionRunsMillis} - * property. + * Returns the value of the {@link #timeBetweenEvictionRunsMillis} property. * * @return the time (in milliseconds) between evictor runs * @see #timeBetweenEvictionRunsMillis @@ -786,7 +785,8 @@ public class BasicDataSource implements /** * Sets the {@link #timeBetweenEvictionRunsMillis} property. * - * @param timeBetweenEvictionRunsMillis the new time between evictor runs + * @param timeBetweenEvictionRunsMillis + * the new time between evictor runs * @see #timeBetweenEvictionRunsMillis */ public synchronized void setTimeBetweenEvictionRunsMillis(final long timeBetweenEvictionRunsMillis) { @@ -797,17 +797,14 @@ public class BasicDataSource implements } /** - * The number of objects to examine during each run of the idle object - * evictor thread (if any). + * The number of objects to examine during each run of the idle object evictor thread (if any). */ - private int numTestsPerEvictionRun = - BaseObjectPoolConfig.DEFAULT_NUM_TESTS_PER_EVICTION_RUN; + private int numTestsPerEvictionRun = BaseObjectPoolConfig.DEFAULT_NUM_TESTS_PER_EVICTION_RUN; /** * Returns the value of the {@link #numTestsPerEvictionRun} property. * - * @return the number of objects to examine during idle object evictor - * runs + * @return the number of objects to examine during idle object evictor runs * @see #numTestsPerEvictionRun */ @Override @@ -818,8 +815,8 @@ public class BasicDataSource implements /** * Sets the value of the {@link #numTestsPerEvictionRun} property. * - * @param numTestsPerEvictionRun the new {@link #numTestsPerEvictionRun} - * value + * @param numTestsPerEvictionRun + * the new {@link #numTestsPerEvictionRun} value * @see #numTestsPerEvictionRun */ public synchronized void setNumTestsPerEvictionRun(final int numTestsPerEvictionRun) { @@ -830,11 +827,10 @@ public class BasicDataSource implements } /** - * 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). + * 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). */ - private long minEvictableIdleTimeMillis = - BaseObjectPoolConfig.DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS; + private long minEvictableIdleTimeMillis = BaseObjectPoolConfig.DEFAULT_MIN_EVICTABLE_IDLE_TIME_MILLIS; /** * Returns the {@link #minEvictableIdleTimeMillis} property. @@ -850,8 +846,8 @@ public class BasicDataSource implements /** * Sets the {@link #minEvictableIdleTimeMillis} property. * - * @param minEvictableIdleTimeMillis the minimum amount of time an object - * may sit idle in the pool + * @param minEvictableIdleTimeMillis + * the minimum amount of time an object may sit idle in the pool * @see #minEvictableIdleTimeMillis */ public synchronized void setMinEvictableIdleTimeMillis(final long minEvictableIdleTimeMillis) { @@ -862,23 +858,20 @@ public class BasicDataSource implements } /** - * The minimum amount of time a connection may sit idle in the pool before - * it is eligible for eviction by the idle object evictor, with the extra - * condition that at least "minIdle" connections remain in the pool. - * Note that {@code minEvictableIdleTimeMillis} takes precedence over this - * parameter. See {@link #getSoftMinEvictableIdleTimeMillis()}. - */ - private long softMinEvictableIdleTimeMillis = - BaseObjectPoolConfig.DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS; - - /** - * Sets the minimum amount of time a connection may sit idle in the pool - * before it is eligible for eviction by the idle object evictor, with the - * extra condition that at least "minIdle" connections remain in the pool. - * - * @param softMinEvictableIdleTimeMillis minimum amount of time a - * connection may sit idle in the pool before it is eligible for eviction, - * assuming there are minIdle idle connections in the pool. + * The minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle + * object evictor, with the extra condition that at least "minIdle" connections remain in the pool. Note that + * {@code minEvictableIdleTimeMillis} takes precedence over this parameter. See + * {@link #getSoftMinEvictableIdleTimeMillis()}. + */ + private long softMinEvictableIdleTimeMillis = BaseObjectPoolConfig.DEFAULT_SOFT_MIN_EVICTABLE_IDLE_TIME_MILLIS; + + /** + * Sets the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the + * idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool. + * + * @param softMinEvictableIdleTimeMillis + * minimum amount of time a connection may sit idle in the pool before it is eligible for eviction, + * assuming there are minIdle idle connections in the pool. * @see #getSoftMinEvictableIdleTimeMillis */ public synchronized void setSoftMinEvictableIdleTimeMillis(final long softMinEvictableIdleTimeMillis) { @@ -889,34 +882,33 @@ public class BasicDataSource implements } /** - * <p>Returns the minimum amount of time a connection may sit idle in the - * pool before it is eligible for eviction by the idle object evictor, with - * the extra condition that at least "minIdle" connections remain in the - * pool.</p> - * - * <p>When {@link #getMinEvictableIdleTimeMillis() 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 - * {@code minEvictableIdleTimeMillis} (without considering the number of idle - * connections in the pool) and then against - * {@code softMinEvictableIdleTimeMillis}, including the {@code minIdle}, - * constraint.</p> - * - * @return minimum amount of time a connection may sit idle in the pool before - * it is eligible for eviction, assuming there are minIdle idle connections - * in the pool + * <p> + * Returns the minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by + * the idle object evictor, with the extra condition that at least "minIdle" connections remain in the pool. + * </p> + * + * <p> + * When {@link #getMinEvictableIdleTimeMillis() 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 {@code minEvictableIdleTimeMillis} (without + * considering the number of idle connections in the pool) and then against {@code softMinEvictableIdleTimeMillis}, + * including the {@code minIdle}, constraint. + * </p> + * + * @return minimum amount of time a connection may sit idle in the pool before it is eligible for eviction, assuming + * there are minIdle idle connections in the pool */ @Override public synchronized long getSoftMinEvictableIdleTimeMillis() { return softMinEvictableIdleTimeMillis; } - private String evictionPolicyClassName = - BaseObjectPoolConfig.DEFAULT_EVICTION_POLICY_CLASS_NAME; + private String evictionPolicyClassName = BaseObjectPoolConfig.DEFAULT_EVICTION_POLICY_CLASS_NAME; /** * Gets the EvictionPolicy implementation in use with this connection pool. + * + * @return The EvictionPolicy implementation in use with this connection pool. */ public synchronized String getEvictionPolicyClassName() { return evictionPolicyClassName; @@ -925,11 +917,10 @@ public class BasicDataSource implements /** * Sets the EvictionPolicy implementation to use with this connection pool. * - * @param evictionPolicyClassName The fully qualified class name of the - * EvictionPolicy implementation + * @param evictionPolicyClassName + * The fully qualified class name of the EvictionPolicy implementation */ - public synchronized void setEvictionPolicyClassName( - final String evictionPolicyClassName) { + public synchronized void setEvictionPolicyClassName(final String evictionPolicyClassName) { if (connectionPool != null) { connectionPool.setEvictionPolicyClassName(evictionPolicyClassName); } @@ -937,17 +928,15 @@ public class BasicDataSource implements } /** - * 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. + * 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. */ private boolean testWhileIdle = false; /** * Returns the value of the {@link #testWhileIdle} property. * - * @return true if objects examined by the idle object evictor are - * validated + * @return true if objects examined by the idle object evictor are validated * @see #testWhileIdle */ @Override @@ -956,10 +945,11 @@ public class BasicDataSource implements } /** - * Sets the <code>testWhileIdle</code> property. This property determines - * whether or not the idle object evictor will validate connections. + * Sets the <code>testWhileIdle</code> property. This property determines whether or not the idle object evictor + * will validate connections. * - * @param testWhileIdle new value for testWhileIdle property + * @param testWhileIdle + * new value for testWhileIdle property */ public synchronized void setTestWhileIdle(final boolean testWhileIdle) { this.testWhileIdle = testWhileIdle; @@ -969,8 +959,7 @@ public class BasicDataSource implements } /** - * [Read Only] The current number of active connections that have been - * allocated from this data source. + * [Read Only] The current number of active connections that have been allocated from this data source. * * @return the current number of active connections */ @@ -984,10 +973,8 @@ public class BasicDataSource implements return 0; } - /** - * [Read Only] The current number of idle connections that are waiting - * to be allocated from this data source. + * [Read Only] The current number of idle connections that are waiting to be allocated from this data source. * * @return the current number of idle connections */ @@ -1002,8 +989,7 @@ public class BasicDataSource implements } /** - * The connection password to be passed to our JDBC driver to establish - * a connection. + * The connection password to be passed to our JDBC driver to establish a connection. */ private volatile String password; @@ -1018,30 +1004,31 @@ public class BasicDataSource implements } /** - * <p>Sets the {@link #password}.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the {@link #password}. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param password new value for the password + * @param password + * new value for the password */ public void setPassword(final String password) { this.password = password; } /** - * The connection URL to be passed to our JDBC driver to establish - * a connection. + * The connection URL to be passed to our JDBC driver to establish a connection. */ private String url; /** * Returns the JDBC connection {@link #url} property. * - * @return the {@link #url} passed to the JDBC driver to establish - * connections + * @return the {@link #url} passed to the JDBC driver to establish connections */ @Override public synchronized String getUrl() { @@ -1049,62 +1036,63 @@ public class BasicDataSource implements } /** - * <p>Sets the {@link #url}.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the {@link #url}. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param url the new value for the JDBC connection url + * @param url + * the new value for the JDBC connection url */ public synchronized void setUrl(final String url) { this.url = url; } /** - * 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; + private String userName; /** - * Returns the JDBC connection {@link #username} property. + * Returns the JDBC connection {@link #userName} property. * - * @return the {@link #username} passed to the JDBC driver to establish - * connections + * @return the {@link #userName} passed to the JDBC driver to establish connections */ @Override public String getUsername() { - return this.username; + return this.userName; } /** - * <p>Sets the {@link #username}.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the {@link #userName}. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * 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; } /** - * 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, {@link Connection#isValid(int)} will be used - * to validate connections. + * 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, {@link Connection#isValid(int)} will be used to validate connections. */ private volatile String validationQuery; /** - * Returns the validation query used to validate connections before - * returning them. + * Returns the validation query used to validate connections before returning them. * * @return the SQL validation query * @see #validationQuery @@ -1115,14 +1103,17 @@ public class BasicDataSource implements } /** - * <p>Sets the {@link #validationQuery}.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the {@link #validationQuery}. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param validationQuery the new value for the validation query + * @param validationQuery + * the new value for the validation query */ public void setValidationQuery(final String validationQuery) { if (validationQuery != null && validationQuery.trim().length() > 0) { @@ -1135,7 +1126,7 @@ public class BasicDataSource implements /** * Timeout in seconds before connection validation queries fail. */ - private volatile int validationQueryTimeout = -1; + private volatile int validationQueryTimeoutSeconds = -1; /** * Returns the validation query timeout. @@ -1144,40 +1135,37 @@ public class BasicDataSource implements */ @Override public int getValidationQueryTimeout() { - return validationQueryTimeout; + return validationQueryTimeoutSeconds; } /** - * Sets the validation query timeout, the amount of time, in seconds, that - * connection validation will wait for a response from the database when - * executing a validation query. Use a value less than or equal to 0 for - * no timeout. + * Sets the validation query timeout, the amount of time, in seconds, that connection validation will wait for a + * response from the database when executing a validation query. Use a value less than or equal to 0 for no timeout. * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param timeout new validation query timeout value in seconds + * @param validationQueryTimeoutSeconds + * new validation query timeout value in seconds */ - public void setValidationQueryTimeout(final int timeout) { - this.validationQueryTimeout = timeout; + public void setValidationQueryTimeout(final int validationQueryTimeoutSeconds) { + this.validationQueryTimeoutSeconds = validationQueryTimeoutSeconds; } /** * These SQL statements run once after a Connection is created. * <p> - * This property can be used for example to run ALTER SESSION SET - * NLS_SORT=XCYECH in an Oracle Database only once after connection - * creation. + * This property can be used for example to run ALTER SESSION SET NLS_SORT=XCYECH in an Oracle Database only once + * after connection creation. * </p> */ private volatile List<String> connectionInitSqls; /** - * Returns the list of SQL statements executed when a physical connection - * is first created. Returns an empty list if there are no initialization - * statements configured. + * Returns the list of SQL statements executed when a physical connection is first created. Returns an empty list if + * there are no initialization statements configured. * * @return initialization SQL statements */ @@ -1190,8 +1178,7 @@ public class BasicDataSource implements } /** - * Provides the same data as {@link #getConnectionInitSqls()} but in an - * array so it is accessible via JMX. + * Provides the same data as {@link #getConnectionInitSqls()} but in an array so it is accessible via JMX. */ @Override public String[] getConnectionInitSqlsAsArray() { @@ -1200,22 +1187,21 @@ public class BasicDataSource implements } /** - * Sets the list of SQL statements to be executed when a physical - * connection is first created. + * Sets the list of SQL statements to be executed when a physical connection is first created. * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param connectionInitSqls Collection of SQL statements to execute - * on connection creation + * @param connectionInitSqls + * Collection of SQL statements to execute on connection creation */ public void setConnectionInitSqls(final Collection<String> connectionInitSqls) { if (connectionInitSqls != null && connectionInitSqls.size() > 0) { ArrayList<String> newVal = null; for (final String s : connectionInitSqls) { - if (s != null && s.trim().length() > 0) { + if (s != null && s.trim().length() > 0) { if (newVal == null) { newVal = new ArrayList<>(); } @@ -1228,7 +1214,6 @@ public class BasicDataSource implements } } - /** * Controls access to the underlying connection. */ @@ -1237,8 +1222,7 @@ public class BasicDataSource implements /** * Returns the value of the accessToUnderlyingConnectionAllowed property. * - * @return true if access to the underlying connection is allowed, false - * otherwise. + * @return true if access to the underlying connection is allowed, false otherwise. */ @Override public synchronized boolean isAccessToUnderlyingConnectionAllowed() { @@ -1246,27 +1230,28 @@ public class BasicDataSource implements } /** - * <p>Sets the value of the accessToUnderlyingConnectionAllowed property. - * It controls if the PoolGuard allows access to the underlying connection. - * (Default: false)</p> - * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * <p> + * Sets the value of the accessToUnderlyingConnectionAllowed property. It controls if the PoolGuard allows access to + * the underlying connection. (Default: false) + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> * - * @param allow Access to the underlying connection is granted when true. + * @param allow + * Access to the underlying connection is granted when true. */ public synchronized void setAccessToUnderlyingConnectionAllowed(final boolean allow) { this.accessToUnderlyingConnectionAllowed = allow; } - private long maxConnLifetimeMillis = -1; /** - * Returns the maximum permitted lifetime of a connection in milliseconds. A - * value of zero or less indicates an infinite lifetime. + * Returns the maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an + * infinite lifetime. */ @Override public long getMaxConnLifetimeMillis() { @@ -1276,9 +1261,8 @@ public class BasicDataSource implements private boolean logExpiredConnections = true; /** - * When {@link #getMaxConnLifetimeMillis()} is set to limit connection lifetime, - * this property determines whether or not log messages are generated when the - * pool closes connections due to maximum lifetime exceeded. + * When {@link #getMaxConnLifetimeMillis()} is set to limit connection lifetime, this property determines whether or + * not log messages are generated when the pool closes connections due to maximum lifetime exceeded. * * @since 2.1 */ @@ -1288,23 +1272,31 @@ public class BasicDataSource implements } /** - * <p>Sets the maximum permitted lifetime of a connection in - * milliseconds. A value of zero or less indicates an infinite lifetime.</p> * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: <code>getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter.</code></p> + * Sets the maximum permitted lifetime of a connection in milliseconds. A value of zero or less indicates an + * infinite lifetime. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: <code>getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter.</code> + * </p> + * + * @param maxConnLifetimeMillis + * The maximum permitted lifetime of a connection in milliseconds. */ public void setMaxConnLifetimeMillis(final long maxConnLifetimeMillis) { this.maxConnLifetimeMillis = maxConnLifetimeMillis; } /** - * When {@link #getMaxConnLifetimeMillis()} is set to limit connection lifetime, - * this property determines whether or not log messages are generated when the - * pool closes connections due to maximum lifetime exceeded. Set this property - * to false to suppress log messages when connections expire. + * When {@link #getMaxConnLifetimeMillis()} is set to limit connection lifetime, this property determines whether or + * not log messages are generated when the pool closes connections due to maximum lifetime exceeded. Set this + * property to false to suppress log messages when connections expire. + * + * @param logExpiredConnections + * Whether or not log messages are generated when the pool closes connections due to maximum lifetime + * exceeded. */ public void setLogExpiredConnections(final boolean logExpiredConnections) { this.logExpiredConnections = logExpiredConnections; @@ -1313,44 +1305,48 @@ public class BasicDataSource implements private String jmxName; /** - * Returns the JMX name that has been requested for this DataSource. If the - * requested name is not valid, an alternative may be chosen. + * Returns the JMX name that has been requested for this DataSource. If the requested name is not valid, an + * alternative may be chosen. + * + * @return The JMX name that has been requested for this DataSource. */ public String getJmxName() { return jmxName; } /** - * Sets the JMX name that has been requested for this DataSource. If the - * requested name is not valid, an alternative may be chosen. This - * DataSource will attempt to register itself using this name. If another - * component registers this DataSource with JMX and this name is valid this - * name will be used in preference to any specified by the other component. + * Sets the JMX name that has been requested for this DataSource. If the requested name is not valid, an alternative + * may be chosen. This DataSource will attempt to register itself using this name. If another component registers + * this DataSource with JMX and this name is valid this name will be used in preference to any specified by the + * other component. + * + * @param jmxName + * The JMX name that has been requested for this DataSource */ public void setJmxName(final String jmxName) { this.jmxName = jmxName; } - private boolean enableAutoCommitOnReturn = true; /** - * Returns the value of the flag that controls whether or not connections - * being returned to the pool will be checked and configured with - * {@link Connection#setAutoCommit(boolean) Connection.setAutoCommit(true)} - * if the auto commit setting is {@code false} when the connection - * is returned. It is <code>true</code> by default. + * Returns the value of the flag that controls whether or not connections being returned to the pool will be checked + * and configured with {@link Connection#setAutoCommit(boolean) Connection.setAutoCommit(true)} if the auto commit + * setting is {@code false} when the connection is returned. It is <code>true</code> by default. + * + * @return Whether or not connections being returned to the pool will be checked and configured with auto-commit. */ public boolean getEnableAutoCommitOnReturn() { return enableAutoCommitOnReturn; } /** - * Sets the value of the flag that controls whether or not connections - * being returned to the pool will be checked and configured with - * {@link Connection#setAutoCommit(boolean) Connection.setAutoCommit(true)} - * if the auto commit setting is {@code false} when the connection - * is returned. It is <code>true</code> by default. + * Sets the value of the flag that controls whether or not connections being returned to the pool will be checked + * and configured with {@link Connection#setAutoCommit(boolean) Connection.setAutoCommit(true)} if the auto commit + * setting is {@code false} when the connection is returned. It is <code>true</code> by default. + * + * @param enableAutoCommitOnReturn + * Whether or not connections being returned to the pool will be checked and configured with auto-commit. */ public void setEnableAutoCommitOnReturn(final boolean enableAutoCommitOnReturn) { this.enableAutoCommitOnReturn = enableAutoCommitOnReturn; @@ -1359,18 +1355,21 @@ public class BasicDataSource implements private boolean rollbackOnReturn = true; /** - * Gets the current value of the flag that controls if a connection will be - * rolled back when it is returned to the pool if auto commit is not enabled - * and the connection is not read only. + * Gets the current value of the flag that controls whether a connection will be rolled back when it is returned to + * the pool if auto commit is not enabled and the connection is not read only. + * + * @return whether a connection will be rolled back when it is returned to the pool. */ public boolean getRollbackOnReturn() { return rollbackOnReturn; } /** - * Sets the flag that controls if a connection will be rolled back when it - * is returned to the pool if auto commit is not enabled and the connection - * is not read only. + * Sets the flag that controls if a connection will be rolled back when it is returned to the pool if auto commit is + * not enabled and the connection is not read only. + * + * @param rollbackOnReturn + * whether a connection will be rolled back when it is returned to the pool. */ public void setRollbackOnReturn(final boolean rollbackOnReturn) { this.rollbackOnReturn = rollbackOnReturn; @@ -1380,6 +1379,7 @@ public class BasicDataSource implements /** * Returns the set of SQL_STATE codes considered to signal fatal conditions. + * * @return fatal disconnection state codes * @see #setDisconnectionSqlCodes(Collection) * @since 2.1 @@ -1393,8 +1393,8 @@ public class BasicDataSource implements } /** - * Provides the same data as {@link #getDisconnectionSqlCodes} but in an - * array so it is accessible via JMX. + * Provides the same data as {@link #getDisconnectionSqlCodes} but in an array so it is accessible via JMX. + * * @since 2.1 */ @Override @@ -1406,30 +1406,30 @@ public class BasicDataSource implements /** * Sets the SQL_STATE codes considered to signal fatal conditions. * <p> - * Overrides the defaults in {@link Utils#DISCONNECTION_SQL_CODES} - * (plus anything starting with {@link Utils#DISCONNECTION_SQL_CODE_PREFIX}). - * If this property is non-null and {@link #getFastFailValidation()} is - * {@code true}, whenever connections created by this datasource generate exceptions - * with SQL_STATE codes in this list, they will be marked as "fatally disconnected" - * and subsequent validations will fail fast (no attempt at isValid or validation - * query).</p> - * <p> - * If {@link #getFastFailValidation()} is {@code false} setting this property has no - * effect.</p> - * <p> - * Note: this method currently has no effect once the pool has been - * initialized. The pool is initialized the first time one of the - * following methods is invoked: {@code getConnection, setLogwriter, - * setLoginTimeout, getLoginTimeout, getLogWriter}.</p> + * Overrides the defaults in {@link Utils#DISCONNECTION_SQL_CODES} (plus anything starting with + * {@link Utils#DISCONNECTION_SQL_CODE_PREFIX}). If this property is non-null and {@link #getFastFailValidation()} + * is {@code true}, whenever connections created by this datasource generate exceptions with SQL_STATE codes in this + * list, they will be marked as "fatally disconnected" and subsequent validations will fail fast (no attempt at + * isValid or validation query). + * </p> + * <p> + * If {@link #getFastFailValidation()} is {@code false} setting this property has no effect. + * </p> + * <p> + * Note: this method currently has no effect once the pool has been initialized. The pool is initialized the first + * time one of the following methods is invoked: {@code getConnection, setLogwriter, + * setLoginTimeout, getLoginTimeout, getLogWriter}. + * </p> * - * @param disconnectionSqlCodes SQL_STATE codes considered to signal fatal conditions + * @param disconnectionSqlCodes + * SQL_STATE codes considered to signal fatal conditions * @since 2.1 */ public void setDisconnectionSqlCodes(final Collection<String> disconnectionSqlCodes) { if (disconnectionSqlCodes != null && disconnectionSqlCodes.size() > 0) { HashSet<String> newVal = null; for (final String s : disconnectionSqlCodes) { - if (s != null && s.trim().length() > 0) { + if (s != null && s.trim().length() > 0) { if (newVal == null) { newVal = new HashSet<>(); } @@ -1445,9 +1445,8 @@ public class BasicDataSource implements private boolean fastFailValidation; /** - * True means that validation will fail immediately for connections that - * have previously thrown SQLExceptions with SQL_STATE indicating fatal - * disconnection errors. + * True means that validation will fail immediately for connections that have previously thrown SQLExceptions with + * SQL_STATE indicating fatal disconnection errors. * * @return true if connections created by this datasource will fast fail validation. * @see #setDisconnectionSqlCodes(Collection) @@ -1460,16 +1459,14 @@ public class BasicDataSource implements /** * @see #getFastFailValidation() - * @param fastFailValidation true means connections created by this factory will - * fast fail validation + * @param fastFailValidation + * true means connections created by this factory will fast fail validation * @since 2.1 */ public void setFastFailValidation(final boolean fastFailValidation) { this.fastFailValidation = fastFailValidation; } - // ----------------------------------------------------- Instance Variables - /** * The object pool that internally manages our connections. */ @@ -1480,10 +1477,9 @@ public class BasicDataSource implements } /** - * The connection properties that will be sent to our JDBC driver when - * establishing new connections. <strong>NOTE</strong> - The "user" and - * "password" properties will be passed explicitly, so they do not need - * to be included here. + * The connection properties that will be sent to our JDBC driver when establishing new connections. + * <strong>NOTE</strong> - The "user" and "password" properties will be passed explicitly, so they do not need to be + * included here. */ private Properties connectionProperties = new Properties(); @@ -1493,26 +1489,24 @@ public class BasicDataSource implements } /** - * The data source we will use to manage connections. This object should - * be acquired <strong>ONLY</strong> by calls to the - * <code>createDataSource()</code> method. + * The data source we will use to manage connections. This object should be acquired <strong>ONLY</strong> by calls + * to the <code>createDataSource()</code> method. */ private volatile DataSource dataSource; /** * The PrintWriter to which log messages should be directed. */ - private volatile PrintWriter logWriter = new PrintWriter(new OutputStreamWriter( - System.out, StandardCharsets.UTF_8)); - + private volatile PrintWriter logWriter = new PrintWriter( + new OutputStreamWriter(System.out, StandardCharsets.UTF_8)); // ----------------------------------------------------- DataSource Methods - /** - * Create (if necessary) and return a connection to the database. + * Creates (if necessary) and return a connection to the database. * - * @throws SQLException if a database access error occurs + * @throws SQLException + * if a database access error occurs * @return a database connection */ @Override @@ -1532,54 +1526,58 @@ public class BasicDataSource implements return createDataSource().getConnection(); } - /** - * <strong>BasicDataSource does NOT support this method. </strong> + * <strong>BasicDataSource does NOT support this method.</strong> * - * @param user Database user on whose behalf the Connection - * is being made - * @param pass The database user's password + * @param user + * Database user on whose behalf the Connection is being made + * @param pass + * The database user's password * * @throws UnsupportedOperationException - * @throws SQLException if a database access error occurs + * always thrown. + * @throws SQLException + * if a database access error occurs * @return nothing - always throws UnsupportedOperationException */ @Override public Connection getConnection(final String user, final String pass) throws SQLException { - // This method isn't supported by the PoolingDataSource returned by - // the createDataSource + // This method isn't supported by the PoolingDataSource returned by the createDataSource throw new UnsupportedOperationException("Not supported by BasicDataSource"); } - /** - * <strong>BasicDataSource does NOT support this method. </strong> + * <strong>BasicDataSource does NOT support this method.</strong> * - * <p>Returns the login timeout (in seconds) for connecting to the database. + * <p> + * Returns the login timeout (in seconds) for connecting to the database. + * </p> + * <p> + * Calls {@link #createDataSource()}, so has the side effect of initializing the connection pool. * </p> - * <p>Calls {@link #createDataSource()}, so has the side effect - * of initializing the connection pool.</p> * - * @throws SQLException if a database access error occurs - * @throws UnsupportedOperationException If the DataSource implementation - * does not support the login timeout feature. + * @throws SQLException + * if a database access error occurs + * @throws UnsupportedOperationException + * If the DataSource implementation does not support the login timeout feature. * @return login timeout in seconds */ @Override public int getLoginTimeout() throws SQLException { - // This method isn't supported by the PoolingDataSource returned by - // the createDataSource + // This method isn't supported by the PoolingDataSource returned by the createDataSource throw new UnsupportedOperationException("Not supported by BasicDataSource"); } - /** - * <p>Returns the log writer being used by this data source.</p> * <p> - * Calls {@link #createDataSource()}, so has the side effect - * of initializing the connection pool.</p> + * Returns the log writer being used by this data source. + * </p> + * <p> + * Calls {@link #createDataSource()}, so has the side effect of initializing the connection pool. + * </p> * - * @throws SQLException if a database access error occurs + * @throws SQLException + * if a database access error occurs * @return log writer in use */ @Override @@ -1587,37 +1585,41 @@ public class BasicDataSource implements return createDataSource().getLogWriter(); } - /** * <strong>BasicDataSource does NOT support this method. </strong> * - * <p>Set the login timeout (in seconds) for connecting to the - * database.</p> * <p> - * Calls {@link #createDataSource()}, so has the side effect - * of initializing the connection pool.</p> + * Set the login timeout (in seconds) for connecting to the database. + * </p> + * <p> + * Calls {@link #createDataSource()}, so has the side effect of initializing the connection pool. + * </p> * - * @param loginTimeout The new login timeout, or zero for no timeout - * @throws UnsupportedOperationException If the DataSource implementation - * does not support the login timeout feature. - * @throws SQLException if a database access error occurs + * @param loginTimeout + * The new login timeout, or zero for no timeout + * @throws UnsupportedOperationException + * If the DataSource implementation does not support the login timeout feature. + * @throws SQLException + * if a database access error occurs */ @Override public void setLoginTimeout(final int loginTimeout) throws SQLException { - // This method isn't supported by the PoolingDataSource returned by - // the createDataSource + // This method isn't supported by the PoolingDataSource returned by the createDataSource throw new UnsupportedOperationException("Not supported by BasicDataSource"); } - /** - * <p>Sets the log writer being used by this data source.</p> * <p> - * Calls {@link #createDataSource()}, so has the side effect - * of initializing the connection pool.</p> + * Sets the log writer being used by this data source. + * </p> + * <p> + * Calls {@link #createDataSource()}, so has the side effect of initializing the connection pool. + * </p> * - * @param logWriter The new log writer - * @throws SQLException if a database access error occurs + * @param logWriter + * The new log writer + * @throws SQLException + * if a database access error occurs */ @Override public void setLogWriter(final PrintWriter logWriter) throws SQLException { @@ -1628,21 +1630,25 @@ public class BasicDataSource implements private AbandonedConfig abandonedConfig; /** - * <p>Flag to remove abandoned connections if they exceed the - * removeAbandonedTimeout when borrowObject is invoked.</p> - * - * <p>The default value is false.</p> - * - * <p>If set to true a connection is considered abandoned and eligible - * for removal if it has not been used for more than - * {@link #getRemoveAbandonedTimeout() removeAbandonedTimeout} seconds.</p> - * - * <p>Abandoned connections are identified and removed when - * {@link #getConnection()} is invoked and all of the following conditions hold: + * <p> + * Flag to remove abandoned connections if they exceed the removeAbandonedTimeout when borrowObject is invoked. + * </p> + * <p> + * The default value is false. * </p> - * <ul><li>{@link #getRemoveAbandonedOnBorrow()} </li> - * <li>{@link #getNumActive()} > {@link #getMaxTotal()} - 3 </li> - * <li>{@link #getNumIdle()} < 2 </li></ul> + * <p> + * If set to true a connection is considered abandoned and eligible for removal if it has not been used for more + * than {@link #getRemoveAbandonedTimeout() removeAbandonedTimeout} seconds. + * </p> + * <p> + * Abandoned connections are identified and removed when {@link #getConnection()} is invoked and all of the + * following conditions hold: + * </p> + * <ul> + * <li>{@link #getRemoveAbandonedOnBorrow()}</li> + * <li>{@link #getNumActive()} > {@link #getMaxTotal()} - 3</li> + * <li>{@link #getNumIdle()} < 2</li> + * </ul> * * @see #getRemoveAbandonedTimeout() */ @@ -1655,17 +1661,15 @@ public class BasicDataSource implements } /** - * @param removeAbandonedOnMaintenance true means abandoned connections may - * be removed on pool maintenance. + * @param removeAbandonedOnMaintenance + * true means abandoned connections may be removed on pool maintenance. * @see #getRemoveAbandonedOnMaintenance() */ - public void setRemoveAbandonedOnMaintenance( - final boolean removeAbandonedOnMaintenance) { + public void setRemoveAbandonedOnMaintenance(final boolean removeAbandonedOnMaintenance) { if (abandonedConfig == null) { abandonedConfig = new AbandonedConfig(); } - abandonedConfig.setRemoveAbandonedOnMaintenance( - removeAbandonedOnMaintenance); + abandonedConfig.setRemoveAbandonedOnMaintenance(removeAbandonedOnMaintenance); final GenericObjectPool<?> gop = this.connectionPool; if (gop != null) { gop.setAbandonedConfig(abandonedConfig); @@ -1673,14 +1677,18 @@ public class BasicDataSource implements } /** - * <p>Flag to remove abandoned connections if they exceed the - * removeAbandonedTimeout during pool maintenance.</p> + * <p> + * Flag to remove abandoned connections if they exceed the removeAbandonedTimeout during pool maintenance. + * </p> * - * <p>The default value is false.</p> + * <p> + * The default value is false. + * </p> * - * <p>If set to true a connection is considered abandoned and eligible - * for removal if it has not been used for more than - * {@link #getRemoveAbandonedTimeout() removeAbandonedTimeout} seconds.</p> + * <p> + * If set to true a connection is considered abandoned and eligible for removal if it has not been used for more + * than {@link #getRemoveAbandonedTimeout() removeAbandonedTimeout} seconds. + * </p> * * @see #getRemoveAbandonedTimeout() */ @@ -1693,8 +1701,8 @@ public class BasicDataSource implements } /** - * @param removeAbandonedOnBorrow true means abandoned connections may be - * removed when connections are borrowed from the pool. + * @param removeAbandonedOnBorrow + * true means abandoned connections may be removed when connections are borrowed from the pool. * @see #getRemoveAbandonedOnBorrow() */ public void setRemoveAbandonedOnBorrow(final boolean removeAbandonedOnBorrow) { @@ -1709,21 +1717,24 @@ public class BasicDataSource implements } /** - * <p>Timeout in seconds before an abandoned connection can be removed.</p> - * - * <p>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> - * - * <p>Abandoned connection cleanup happens when:</p> + * <p> + * Timeout in seconds before an abandoned connection can be removed. + * </p> + * <p> + * 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> + * <p> + * Abandoned connection cleanup happens when: + * </p> * <ul> - * <li>{@link #getRemoveAbandonedOnBorrow()} or - * {@link #getRemoveAbandonedOnMaintenance()} = true</li> + * <li>{@link #getRemoveAbandonedOnBorrow()} or {@link #getRemoveAbandonedOnMaintenance()} = true</li> * <li>{@link #getNumIdle() numIdle} < 2</li> * <li>{@link #getNumActive() numActive} > {@link #getMaxTotal() maxTotal} - 3</li> * </ul> - * - * <p>The default value is 300 seconds.</p> + * <p> + * The default value is 300 seconds. + * </p> */ @Override public int getRemoveAbandonedTimeout() { @@ -1734,14 +1745,17 @@ public class BasicDataSource implements } /** - * <p>Sets the timeout in seconds before an abandoned connection can be - * removed.</p> + * <p> + * Sets the timeout in seconds before an abandoned connection can be removed. + * </p> * - * <p>Setting this property has no effect if - * {@link #getRemoveAbandonedOnBorrow()} and - * {@link #getRemoveAbandonedOnMaintenance()} are false.</p> + * <p> + * Setting this property has no effect if {@link #getRemoveAbandonedOnBorrow()} and + * {@link #getRemoveAbandonedOnMaintenance()} are false. + * </p> * - * @param removeAbandonedTimeout new abandoned timeout in seconds + * @param removeAbandonedTimeout + * new abandoned timeout in seconds * @see #getRemoveAbandonedTimeout()
[... 602 lines stripped ...] --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
