The Tomcat JDBC Connection Pool

Date: Tue, 28 Oct 2008 19:50:26 +0000 (+0000) Subject: move over documentation to the module X-Git-Url: https://git.internetallee.de/?a=commitdiff_plain;h=4542f7cbcd84e76ee6355c15160d842a83030ccd;p=tomcat7.0 move over documentation to the module git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@708651 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/modules/jdbc-pool/doc/jdbc-pool.xml b/modules/jdbc-pool/doc/jdbc-pool.xml new file mode 100644 index 000000000..8aff55a07 --- /dev/null +++ b/modules/jdbc-pool/doc/jdbc-pool.xml @@ -0,0 +1,298 @@ + + + +]> + + + &project; + + + Filip Hanik + The Tomcat JDBC Connection Pool + + + + + +

+ +

The JDBC Connection Pool org.apache.tomcat.jdbc.pool + is a replacement or an alternative to the commons-dbcp + connection pool.

+ +

So why do we need a new connection pool?

+ +

Here are a few of the reasons: +

commons-dbcp is single threaded, in order to be thread safe commons-dbcp looks the entire pool, even during query validation
commons-dbcp is slow - as the number of logical CPUs grow, the performance suffers, the above point shows that there is not support for high concurrency
commons-dbcp is complex, over 60 classes. tomcat-jdbc-pool, is 8 classes, hence modifications for future requirement will require + much less changes.
commons-dbcp uses static interfaces. This means you can't compile it with JDK 1.6, or if you run on JDK 1.6/1.7 you will get + NoSuchMethodException for all the methods not implemented, even if the driver supports.
The commons-dbcp has become fairly stagnant. Sparse updates, releases, and new feature support.
It's not worth rewriting over 60 classes, when something as a connection pool can be accomplished with as a much simpler implementation.
Tomcat jdbc pool is a Tomcat module, it depends on Tomcat JULI, a greatly simplified logging framework used in Tomcat

+ +

Features added over other connection pool implementations +

Support for highly concurrent environments and multi core/cpu systems
Dynamic implementation of interface, will support java.sql and javax.sql interfaces for + your runtime environment (as long as your JDBC driver does the same), even when compiled with a lower JDK
Validation intervals - we don't have to validate every single time we use the connection, we can do this + when we borrow or return the connection, just not more frequent than an interval we can configure.
Run-Once query, a configurable query that will be run only once, when the connection to the database is established. + Very useful to setup session settings, that you want to exist during the entire time the connection is established.
Ability to configure custom interceptors. + This allows you to write custom interceptors to enhance the functionality. You can use interceptors to gather query stats, + cache session states, reconnect the connection upon failures, retry queries, cache query results, and so on. + Your options are endless and the interceptors are dynamic, not tied to a JDK version of a java.sql/javax.sql interface.
High performance - we will show some differences in performance later on
Extremely simple, due to the very simplified implementation, the line count and source file count are very low, compare with c3p0 + that has over 200 source files(last time we checked), Tomcat jdbc has a core of 8 files, the connection pool itself is about half + that.

+ + +

To provide a very simple switch to and from commons-dbcp and tomcat-jdbc-pool, + Most attributes are the same and have the same meaning.

+ + + + + +

factory is required, and the value should be org.apache.tomcat.jdbc.poo.DataSourceFactory

+ + +

Type should always be javax.sql.DataSource

+ + + + + +

These attributes are shared between commons-dbcp and tomcat-jdbc-pool, in some cases default values are different.

+ + + +

(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.)

+ + + +

(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)

+ + + +

(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc )
+ * NONE
+ * READ_COMMITTED
+ * READ_UNCOMMITTED
+ * REPEATABLE_READ
+ * SERIALIZABLE
+ If not set, the method will not be called and it defaults to the JDBC driver. +

+ + + +

(String) The default catalog of connections created by this pool.

+ + + +

(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 +

+ + + +

(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. +

+ + + +

(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. +

+ + + +

(int) The maximum number of active connections that can be allocated from this pool at the same time. + The default value is 100

+ + + +

(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)

+ + + +

+ (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) +

+ + + +

(int)The initial number of connections that are created when the pool is started. + Default value is 10

+ + + +

(long) 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)

+ + + +

(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. + Default value is false +

+ + + +

(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. +

+ + + +

(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) +

+ + + +

(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) +

+ + + +

(long) 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).

+ + + +

(int) Property not used in tomcat-jdbc-pool.

+ + + +

(long) The minimum amount of time an object may sit idle in the pool before it is eligable for eviction. + The default value is 60000 (60 seconds).

+ + + +

(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.

+ + + +

(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.

+ + + +

(long) 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.

+ + + +

(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.

+ + + +

(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.

+ + + +

(boolean) Property not used. The default value is false.

+ + + +

(int) Property not used. The default value is false.

+ + + + + + + + + + + + + +

(String) A custom query to be run when a connection is first created. + The default value is null.

+ + + +

(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.

+ + + +

(long) 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).

+ + + +

(boolean) Register the pool with JMX or not. + The default value is true.

+ + + +

+ + + + + diff --git a/webapps/docs/config/jdbc-pool.xml b/webapps/docs/config/jdbc-pool.xml deleted file mode 100644 index 8aff55a07..000000000 --- a/webapps/docs/config/jdbc-pool.xml +++ /dev/null @@ -1,298 +0,0 @@ - - - -]> - - - &project; - - - Filip Hanik - The Tomcat JDBC Connection Pool - - - - - -

- -

The JDBC Connection Pool org.apache.tomcat.jdbc.pool - is a replacement or an alternative to the commons-dbcp - connection pool.

- -

So why do we need a new connection pool?

- -

Here are a few of the reasons: -

commons-dbcp is single threaded, in order to be thread safe commons-dbcp looks the entire pool, even during query validation
commons-dbcp is slow - as the number of logical CPUs grow, the performance suffers, the above point shows that there is not support for high concurrency
commons-dbcp is complex, over 60 classes. tomcat-jdbc-pool, is 8 classes, hence modifications for future requirement will require - much less changes.
commons-dbcp uses static interfaces. This means you can't compile it with JDK 1.6, or if you run on JDK 1.6/1.7 you will get - NoSuchMethodException for all the methods not implemented, even if the driver supports.
The commons-dbcp has become fairly stagnant. Sparse updates, releases, and new feature support.
It's not worth rewriting over 60 classes, when something as a connection pool can be accomplished with as a much simpler implementation.
Tomcat jdbc pool is a Tomcat module, it depends on Tomcat JULI, a greatly simplified logging framework used in Tomcat

- -

Features added over other connection pool implementations -

Support for highly concurrent environments and multi core/cpu systems
Dynamic implementation of interface, will support java.sql and javax.sql interfaces for - your runtime environment (as long as your JDBC driver does the same), even when compiled with a lower JDK
Validation intervals - we don't have to validate every single time we use the connection, we can do this - when we borrow or return the connection, just not more frequent than an interval we can configure.
Run-Once query, a configurable query that will be run only once, when the connection to the database is established. - Very useful to setup session settings, that you want to exist during the entire time the connection is established.
Ability to configure custom interceptors. - This allows you to write custom interceptors to enhance the functionality. You can use interceptors to gather query stats, - cache session states, reconnect the connection upon failures, retry queries, cache query results, and so on. - Your options are endless and the interceptors are dynamic, not tied to a JDK version of a java.sql/javax.sql interface.
High performance - we will show some differences in performance later on
Extremely simple, due to the very simplified implementation, the line count and source file count are very low, compare with c3p0 - that has over 200 source files(last time we checked), Tomcat jdbc has a core of 8 files, the connection pool itself is about half - that.

- - -

To provide a very simple switch to and from commons-dbcp and tomcat-jdbc-pool, - Most attributes are the same and have the same meaning.

- - - - - -

factory is required, and the value should be org.apache.tomcat.jdbc.poo.DataSourceFactory

- - -

Type should always be javax.sql.DataSource

- - - - - -

These attributes are shared between commons-dbcp and tomcat-jdbc-pool, in some cases default values are different.

- - - -

(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.)

- - - -

(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)

- - - -

(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc )
- * NONE
- * READ_COMMITTED
- * READ_UNCOMMITTED
- * REPEATABLE_READ
- * SERIALIZABLE
- If not set, the method will not be called and it defaults to the JDBC driver. -

- - - -

(String) The default catalog of connections created by this pool.

- - - -

(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 -

- - - -

(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. -

- - - -

(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. -

- - - -

(int) The maximum number of active connections that can be allocated from this pool at the same time. - The default value is 100

- - - -

(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)

- - - -

- (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) -

- - - -

(int)The initial number of connections that are created when the pool is started. - Default value is 10

- - - -

(long) 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)

- - - -

(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. - Default value is false -

- - - -

(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. -

- - - -

(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) -

- - - -

(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) -

- - - -

(long) 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).

- - - -

(int) Property not used in tomcat-jdbc-pool.

- - - -

(long) The minimum amount of time an object may sit idle in the pool before it is eligable for eviction. - The default value is 60000 (60 seconds).

- - - -

(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.

- - - -

(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.

- - - -

(long) 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.

- - - -

(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.

- - - -

(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.

- - - -

(boolean) Property not used. The default value is false.

- - - -

(int) Property not used. The default value is false.

- - - - - - - - - - - - - -

(String) A custom query to be run when a connection is first created. - The default value is null.

- - - -

(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.

- - - -

(long) 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).

- - - -

(boolean) Register the pool with JMX or not. - The default value is true.

- - - -

- - - - -