（翻译）Tomcat JDBC 连接池
介绍
org.apache.tomcat.jdbc.pool包的JDBC连接池被用来替代commons-dbcp连接池。
为什么我们需要一个新的连接池？
有这样一些原因：
相比其他连接池实现增加的特性：
???????? 为了熟悉commons-dbcp的用户，Tomcat连接池的使用方法被设计得尽可能简单，过度非常简单。从其他连接池迁移也很容易。
附加特性
???????? Tomcat连接池在其他连接池之外还提供一些附加特性：
???????? 遵守TheTomcat JDBC documentation描述，Tomcat连接池被配置为一个资源，。唯一的不同是你必须指定factory属性，并且这是value为org.apache.tomcat.jdbc.pool.DataSourceFactory。
独立运行
为了简化切换commons-dbcp和Tomcat JDBC池，多数属性和commons-dbcp相同，并有相同的意义。
JNDI Factory和Type
Factory是必需的，并且值必须为org.apache.tomcat.jdbc.pool.DataSourceFactory
类型应该永远为javax.sql.DataSource或javax.sql.XADataSource。
根据类型不同，org.apache.tomcat.jdbc.pool.DataSource或org.apache.tomcat.jdbc.pool.XADataSource对象将被建立。
?
Attribute
Description
defaultAutoCommit
(boolean) The default auto-commit state of connections created by this pool. If not set, default is JDBC driver default (If not set then the setAutoCommit method will not be called.)
defaultReadOnly
(boolean) 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)
defaultTransactionIsolation
(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc )
If not set, the method will not be called and it defaults to the JDBC driver.
defaultCatalog
(String) The default catalog of connections created by this pool.
driverClassName
(String) The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible from the same classloader as tomcat-jdbc.jar
username
(String) The connection username to be passed to our JDBC driver to establish a connection. Note, at this point, DataSource.getConnection(username,password) is not using the credentials passed into the method.
password
(String) The connection password to be passed to our JDBC driver to establish a connection. Note, at this point, DataSource.getConnection(username,password) is not using the credentials passed into the method.
maxActive
(int) The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
maxIdle
(int) The maximum number of connections that should be kept in the pool at all times. Default value is maxActive:100 Idle connections are checked periodically (if enabled) and connections that been idle for longer than minEvictableIdleTimeMillis will be released. (also see testWhileIdle)
minIdle
(int) The minimum number of established connections that should be kept in the pool at all times. The connection pool can shrink below this number if validation queries fail. Default value is derived from initialSize:10 (also see testWhileIdle)
initialSize
(int)The initial number of connections that are created when the pool is started. Default value is 10
maxWait
(int) 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. Default value is 30000 (30 seconds)
testOnBorrow
(boolean) 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. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. In order to have a more efficient validation, see validationInterval. Default value is false
testOnReturn
(boolean) The indication of whether objects will be validated before being returned to the pool. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. The default value is false.
testWhileIdle
(boolean) 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. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. The default value is false and this property has to be set in order for the pool cleaner/test thread is to run (also see timeBetweenEvictionRunsMillis)
validationQuery
(String) The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query does not have to return any data, it just can't throw a SQLException. The default value is null. Example values are SELECT 1(mysql), select 1 from dual(oracle), SELECT 1(MS Sql Server)
validatorClassName
(String) The name of a class which implements the org.apache.tomcat.jdbc.pool.Validator interface and provides a no-arg constructor (may be implicit). If specified, the class will be used to create a Validator instance which is then used instead of any validation query to validate connections. The default value is null. An example value is com.mycompany.project.SimpleValidator.
timeBetweenEvictionRunsMillis
(int) The number of milliseconds to sleep between runs of the idle connection validation/cleaner thread. This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often we validate idle connections. The default value is 5000 (5 seconds).
numTestsPerEvictionRun
(int) Property not used in tomcat-jdbc-pool.
minEvictableIdleTimeMillis
(int) The minimum amount of time an object may sit idle in the pool before it is eligible for eviction. The default value is 60000 (60 seconds).
accessToUnderlyingConnectionAllowed
(boolean) Property not used. Access can be achieved by calling unwrap on the pooled connection. see javax.sql.DataSource interface, or call getConnection through reflection or or cast the object as javax.sql.PooledConnection
removeAbandoned
(boolean) Flag to remove abandoned connections if they exceed the removeAbandonedTimout. If set to true a connection is considered abandoned and eligible for removal if it has been in use longer than the removeAbandonedTimeout Setting this to true can recover db connections from applications that fail to close a connection. See also logAbandoned The default value is false.
removeAbandonedTimeout
(int) Timeout in seconds before an abandoned(in use) connection can be removed. The default value is 60 (60 seconds). The value should be set to the longest running query your applications might have.
logAbandoned
(boolean) Flag to log stack traces for application code which abandoned a Connection. Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated. The default value is false.
connectionProperties
(String) The connection properties that will be sent to our JDBC driver when establishing new connections. Format of the string must be [propertyName=property;]* NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here. The default value is null.
poolPreparedStatements
(boolean) Property not used.
maxOpenPreparedStatements
(int) Property not used.
?
Tomcat连接池增加的属性
?
Attribute
Description
initSQL
(String)当连接第一次建立时执行的SQL，默认值为null。
A custom query to be run when a connection is first created. The default value is null.
jdbcInterceptors
(String) A semicolon separated list of classnames extending org.apache.tomcat.jdbc.pool.JdbcInterceptor class. These interceptors will be inserted as an interceptor into the chain of operations on a java.sql.Connection object. The default value is null.
Predefined interceptors:
org.apache.tomcat.jdbc.pool.interceptor.ConnectionState - keeps track of auto commit, read only, catalog and transaction isolation level.
org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer - keeps track of opened statements, and closes them when the connection is returned to the pool.
More predefined interceptors are described in detail in the JDBC Interceptors section.
validationInterval
(long) 避免过度验证，保证验证不超过这个频率——以毫秒为单位。如果一个连接应该被验证，但上次验证未达到指定间隔，将不再次验证。默认值是30000（30秒）。
avoid excess validation, only run validation at most at this frequency - time in milliseconds. If a connection is due for validation, but has been validated previously within this interval, it will not be validated again. The default value is 30000 (30 seconds).
jmxEnabled
(boolean) Register the pool with JMX or not. The default value is true.
fairQueue
(boolean) 如果被设为true，getConnection方法将被以先进先出的方式对待。此属性使用 org.apache.tomcat.jdbc.pool.FairBlockingQueue实现闲置连接列表。默认值是true。
如果需要使用异步连接回收，这个标记是必须的。
这个标记确保线程取得连接的顺序和他们调用getConnection方法的顺序是相同的。
在性能测试中，这个标记对锁和锁等待有非常大的影响。当fairQueue=true，将有一个依赖于操作系统的线程作为决定线程。如果是Linux系统（系统属性os.name=Linux）。可以在线程池的类加载之前设置系统属性 org.apache.tomcat.jdbc.pool.FairBlockingQueue.ignoreOS=true关闭Linux特定行为但仍然使用公平队列） **杜天微注：这里好像有句话没说完？不同系统有什么不同行为？
Set to true if you wish that calls to getConnection should be treated fairly in a true FIFO fashion. This uses the org.apache.tomcat.jdbc.pool.FairBlockingQueue implementation for the list of the idle connections. The default value is true. This flag is required when you want to use asynchronous connection retrieval.
Setting this flag ensures that threads receive connections in the order they arrive.
During performance tests, there is a very large difference in how locks and lock waiting is implemented. When fairQueue=true there is a decision making process based on what operating system the system is running. If the system is running on Linux (property os.name=Linux. To disable this Linux specific behavior and still use the fair queue, simply add the property org.apache.tomcat.jdbc.pool.FairBlockingQueue.ignoreOS=true to your system properties before the connection pool classes are loaded.
abandonWhenPercentageFull
(int) Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are above the percentage defined by abandonWhenPercentageFull. The value should be between 0-100. The default value is 0, which implies that connections are eligible for closure as soon as removeAbandonedTimeout has been reached.
maxAge
(long) Time in milliseconds to keep this connection. When a connection is returned to the pool, the pool will check to see if the now - time-when-connected > maxAge has been reached, and if so, it closes the connection rather than returning it to the pool. The default value is 0, which implies that connections will be left open and no age check will be done upon returning the connection to the pool.
useEquals
(boolean) Set to true if you wish the ProxyConnection class to use String.equals and set to false when you wish to use == when comparing method names. This property does not apply to added interceptors as those are configured individually. The default value is true.
suspectTimeout
(int) Timeout value in seconds. Default value is 0.
Similar to to the removeAbandonedTimeout value but instead of treating the connection as abandoned, and potentially closing the connection, this simply logs the warning if logAbandoned is set to true. If this value is equal or less than 0, no suspect checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets logged and a JMX notification gets sent once.
rollbackOnReturn
(boolean) If autoCommit==false then the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool Default value is false.
commitOnReturn
(boolean) If autoCommit==false then the pool can complete the transaction by calling commit on the connection as it is returned to the pool If rollbackOnReturn==true then this attribute is ignored. Default value is false.
alternateUsernameAllowed
(boolean) By default, the jdbc-pool will ignore the DataSource.getConnection(username,password) call, and simply return a previously pooled connection under the globally configured properties username and password, for performance reasons. The pool can however be used with different credentials each time a connection is used. Should you request a connection with the credentials user1/password1 and the connection was previously connected using user2/password2, the connection will be closed, and reopened with the requested credentials. This way, the pool size is still managed on a global level, and not on a per schema level. To enable the functionality described in the DataSource.getConnection(username,password) call, simply set the property alternateUsernameAllowed to true.
The default value is false.
This property was added as an enhancement to bug 50025.
dataSource
(javax.sql.DataSource) Inject a data source to the connection pool, and the pool will use the data source to retrieve connections instead of establishing them using the java.sql.Driver interface. This is useful when you wish to pool XA connections or connections established using a data source instead of a connection string. Default value is null
dataSourceJNDI
(String) The JNDI name for a data source to be looked up in JNDI and then used to establish connections to the database. See the dataSource attribute. Default value is null
useDisposableConnectionFacade
(boolean) Set this to true if you wish to put a facade on your connection so that it cannot be reused after it has been closed. This prevents a thread holding on to a reference of a connection it has already called closed on, to execute queries on it. Default value is true.
logValidationErrors
(boolean) Set this to true to log errors during the validation phase to the log file. If set to true, errors will be logged as SEVERE. Default value is false for backwards compatibility.
propagateInterruptState
(boolean) Set this to true to propagate the interrupt state for a thread that has been interrupted (not clearing the interrupt state). Default value is false for backwards compatibility.
?