Tomcat JDBC Reference

This page provides reference information about the fields on the Views > Server Configuration > Resources tab used to configure and create JDBC data sources.

SpringSource tc Server provides two types of JDBC datasources: the standard DBCP one and a Tomcat datasource for highly-concurrent environments. For additional information about the two types of datasources, see Configuring and Creating JDBC Data Sources.

General Properties

Field Name Description
JNDI Name The JNDI path to which this data source is bound. By default, the JNDI name is the name of the data source.

Connection Properties

Field Name Description
Username The username that the JDBC driver uses to establish a connection to the database server.
Password The password that the JDBC driver uses to establish a connection to the database server.
URL The connection URL that the JDBC driver uses to establish a connection to the database server. This URL varies for each type of database driver. An example for the MySQL database is "jdbc:mysql://localhost:3306/javatest?autoReconnect=true".
Driver Class Name The fully qualified name of the JDBC driver class used to create the physical database connections in the connection pool. The driver class name varies for the type of JDBC driver. An example of the driver class name for connecting to a MySQL database server is "com.mysql.jdbc.Driver".
Connection Properties The connection properties that tc Server sends to the JDBC driver when establishing new connections. Format of the string must be [propertyName=property;].

NOTE - tc Server passes the "user" and "password" properties explicitly, so do not include them in this field.

Tomcat/DBCP Connection Pool Properties

Field Name Description
Default Auto Commit Specifies whether connections created by this pool are by default in an auto-commit state.
Default Read Only Specifies whether connections created by this pool are by default read only.
Default Transaction Isolation Specifies the default transation isolation state for connections created by this pool. Values can be:
  • NONE: Transactions are not supported.
  • READ_COMMITTED: Dirty reads are prevented; non-repeatable reads and phantom reads can occur.
  • READ_UNCOMMITTED: Dirty reads, non-repeatable reads and phantom reads can occur.
  • REPEATABLE_READ: Dirty reads and non-repeatable reads are prevented; phantom reads can occur.
  • SERIALIZABLE: Dirty reads, non-repeatable reads and phantom reads are prevented.
Default value depends on the database driver.
Default Catalog Specifies the default catalog of connections created by this pool.
Initial Number of Connections Specifies the initial number of connections that are created when tc Server starts this connection pool. Default value is 0 (DBCP datasource) or 10 (Tomcat datasource).
Max Active Connections Specifies the maximum number of active connections that tc Server can allocate from this pool at the same time. Specify a negative number for no limit. Default value is 8 (DBCP datasource) or 100 (Tomcat datasource).
Max Idle Connections Specifies the maximum number of connections that can remain idle in the pool without any extra ones being released. Specify a negative number for no limit. Default value is 8 (DBCP datasource) or 100 (Tomcat datasource).
Min Idle Connections Specifies the minimum number of connections that can remain idle in the pool without any extra ones being created. Specify 0 to create none. Default value is 0 (DBCP datasource) or 10 (Tomcat datasource).
Max Wait Time For Connection Return (ms) The maximum number of milliseconds that the connection pool waits (when there are no available connections) for a connection to be returned before throwing an exception. Specify -1 to wait indefinitely. Default value is -1 (DBCP datasource) or 30000 (Tomcat datasource).
Validation Query The SQL query that the driver uses to validate connections from this pool before returning them to the caller. If specified, this query MUST be an SQL SELECT statement that returns at least one row.
Test on Borrow Specifies whether tc Server validates objects before being borrowed from the pool. If the object fails to validate, tc Server drops it from the pool and attempts to borrow another.

NOTE - for a value in this field to have any effect, you must set the Validation Query field to a non-null string.
Test on Return Specifies whether tc Server validates objects before returning them to the connection pool.
Test While Idle Specifies whether the idle object evictor validates objects. If an object fails to validate, tc Server drops it from the connection pool.

NOTE - for a value in this field to have any effect, you must set the Validation Query field to a non-null string.
Time Between Eviction Runs The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, tc Server does not run an idle object evictor thread. Default value is -1 (DBCP datasource) or 5000 (Tomcat datasource).
Test Per Eviction Runs The number of objects to examine during each run of the idle object evictor thread (if any). Default value is 3.
Min Evictable Idle Time The minimum amount of time, in milliseconds, that an object may sit idle in the pool before it is eligable for eviction by the idle object evictor (if any).
Pool Prepared Statements Enables prepared statement pooling for this connection pool.
Max Opened Prepared Statements The maximum number of open statements that can be allocated from the statement pool at the same time. Set this field to 0 for no limit. Default value is 0.
Allow Access to Underlying Connection Specifies whether the PoolGuard allows access to the underlying connection.
Remove Abandoned Connections Specifies whether tc Server should remove abandoned connections if they exceed the value of the Remove Abandoned Timeouts field. If checked, a connection is considered abandoned and eligible for removal if it has been idle longer than the value of Remove Abandoned Timeouts. Checking this field can recover database connections from poorly written applications which fail to close a connection.
Remove Abandoned Timeouts Specifies the amount of time, in seconds, before tc Server can remove an abandoned connection. Default value is 300 seconds.
Log Abandoned Statements and Connections Specifies whether tc Server should log stack traces for application code that abandoned a Statement or Connection.

NOTE: Logging of abandoned Statements and Connections adds overhead for every Connection open or new Statement because a stack trace has to be generated.
Validation Interval (ms) Tomcat datasource only. 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 for this field is 30000 (30 seconds).
Fair Queue Tomcat datasource only. 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.
JMX Enabled Tomcat datasource only. Specifies whether the connection pool is registered with the JMX server.
Use equals comparison Tomcat datasource only. 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.
Init SQL Tomcat datasource only. Specifies an initial SQL statement that is run only when a connection is first created. You can use this featuer to setup session settings that you want to exist during the entire time the connection is established.
JDBC Interceptors Tomcat datasource only. 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.

SpringSource tc Server provides a JDBC Interceptor called SlowQueryReportJmx that keeps a report of slow JDBC queries, or JDBC queries that did not complete below a configured time threshold. If you want AMS to display this report in its Console, then you must add the SlowQueryReportJmx interceptor to this text field. For example, to add it to the default interceptors, enter this value:

  ConnectionState;StatementFinalizer;SlowQueryReportJmx

The default threshold for the SlowQueryReportJmx interceptor is 5000 milliseconds. If you want to change the default value, include it as a parameter to the interceptor, as shown:

  ConnectionState;StatementFinalizer;SlowQueryReportJmx(threshold=6000)

After you have configured the SlowQueryReportJmx interceptor, AMS creates and auto-discovers a service called "JDBC Query Report" that contains information about slow JDBC queries.