Configuring the High Concurrency JDBC Connection Pool

JDBC datasources make it easy for a user to access data in a database server. A datasource defines a pool of JDBC connections which in turn connect to a specific database using a specified URL, username, and so on.

With SpringSource tc Server you can create the following two types of JDBC data sources:

The DBCP Datasource is the standard datasource provided by tc Server; it uses the org.apache.commons.dbcp package. Although this datasource is adequate for simple applications, it is single-threaded, which means that in order to be thread-safe, tc Server must lock the entire pool, even during query validation. Thus it is not suitable for highly concurrent environments. Additionally, it can be slow, which in turn can negatively affect the performance of Web applications.

The tc Server Datasource includes all the functionality of the DBCP datasource, but adds additional features to support highly-concurrent environments and multiple core/cpu systems. The tc Server datasource typically performs much better than the DBCP datasource. Additional features include:

As with any tc Server resource, you configure the high-concurrency JDBC connection pool datasource using a <Resource> child element of <GlobalNamingResource>. Many of the attributes are the same as you would use for the standard DBCP datasource; there are, however, a few new attributes that apply only to the new tc Server datasource. These attributes are as follows; see High-Concurrency Connection Pool Configuration Attributes for detailed information about them:

The way to specify that you want to use the high-concurrency JDBC connection pool is with the factory attribute of the <Resource> element. In particular:

IBM JVM USERS ONLY: If you are using an IBM JVM, see useEquals for important information.

The following server.xml snippet shows how to configure the high-concurrency JDBC connection pool for your tc Server instance. See the CATALINA_BASE/conf/samples/server-with-jdbc.xml file for an actual product sample, where CATALINA_BASE refers to the tc Server instance directory. For an explanation of the following example, see Description of the High Concurrency JDBC Connection Pool.

<?xml version='1.0' encoding='utf-8'?>
<Server port="-1" shutdown="SHUTDOWN">

 ...

  <GlobalNamingResources>

    <Resource name="jdbc/TestDB"
              auth="Container"
              type="javax.sql.DataSource"
              username="root"
              password="password"
              driverClassName="com.mysql.jdbc.Driver"
              url="jdbc:mysql://localhost:3306/mysql?autoReconnect=true"

              testWhileIdle="true"
              testOnBorrow="true"
              testOnReturn="false"
              validationQuery="SELECT 1"
              validationInterval="30000"
              timeBetweenEvictionRunsMillis="5000"
              maxActive="100"
              minIdle="10"
              maxWait="10000"
              initialSize="10"
              removeAbandonedTimeout="60"
              removeAbandoned="true"
              logAbandoned="true"
              minEvictableIdleTimeMillis="30000"
              jmxEnabled="true"
              jdbcInterceptors="org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
                     org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer;
                     org.apache.tomcat.jdbc.pool.interceptor.SlowQueryReportJmx(threshold=10000)"/>

  </GlobalNamingResources>
  ...
  <Service name="Catalina">
  ...
  </Service>
</Server>
 

Description of the High Concurrency JDBC Connection Pool

In the preceding sample server.xml:

For documentation on the attributes that are common between the DBCP and the high-concurrency datasources, such as username and driverClassName see the Apache Commons. For information about the attributes that are specific to the high-concurrency connection pool, see High-Concurrency Connection Pool Configuration Attributes.

For complete documentation about the tc Server server.xml file and all the possible XML elements you can include, see Apache Tomcat Configuration Reference.

High-Concurrency Connection Pool Configuration Attributes

The following table describes the attributes that are specific to the high-concurrency connection pool.

Attribute Description
initSQL Specifies an initial SQL statement that is run only when a connection is first created. You can use this feature to setup session settings that you want to exist during the entire time the connection is established.
jdbcInterceptors Semi-colon separated list of classnames that tc Server inserts as interceptors in the chain of operations on the java.sql.Connection object. The interceptor classes must extend the org.apache.tomcat.jdbc.pool.JdbcInterceptor abstract class.
validationInterval Specifies the time, in milliseconds, that tc Server waits before running a validation check to ensure that the JDBC connection is still valid. Too frequent validation checks can slow performance. Default value is 30000 (30 seconds).
jmxEnabled Specifies whether the connection pool is registered with the JMX server. Default value for this Boolean attribute is true.
fairQueue Specifies that calls to getConnection() should be treated fairly in a true FIFO (first in, first out) fashion. You are required to enable this feature if you want to use the asynchronous connection retrieval feature, which is the ability to queue your connection request. The default value for this Boolean attribute is false.
useEquals Specifies whether the ProxyConnection class should use String.equals() instead of "==" when comparing method names. Does not apply to added interceptors as those are configured individually. Default value of this Boolean attribute is false.

NOTE FOR IBM JVM USERS: If you are running tc Server on a platform that uses the IBM JVM (such as AIX), then you must always set the userEquals attribute to true if you want a high-concurrency connection pool to work correctly. The reason is that IBM JVMs do not use String literal pools for method names, which means you always want to use String.equals() when comparing method names in this case.