A datasource defines a pool of JDBC connections which in turn connect to a specific database using a specified URL, username, and so on. JDBC datasources make it easy for a user to access data in a database server.
In a tc Runtime instance, you can create the following two types of JDBC datasources:
Database connection pool (DBCP) datasource
tc Runtime datasource
The DBCP datasource is the
standard datasource provided by tc Runtime; it uses the
package. Although this datasource is adequate for simple applications,
it is single-threaded, which means that in order to be thread-safe, the
tc Runtime instance 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 Runtime 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 Runtime datasource typically performs much better than the DBCP datasource. Additional features include:
Dynamic implementation of the interfaces, which means that the
datasource supports the
javax.sql interfaces for your runtime environment (as
long as your JDBC driver supports it), even when compiled with a
lower version of the JDK.
Validation intervals so that tc Runtime doesn't have to validate every single time the application uses the connection, which improves performance.
Run-Once query, which is a configurable query that tc Runtime runs only once when the connection to the database is established. This is very useful to set up session settings that you want to exist during the entire time the connection is established.
Ability to configure custom interceptors to enhance the
functionality of the datasource. You can use interceptors to gather
query stats, cache session states, reconnect the connection upon
failures, retry queries, cache query results, and so on. The
interceptors are dynamic and not tied to a JDK version of a
Asynchronous connection retrieval - you can queue your request for a connection and receive a Future<Connection> back.
As with any tc Runtime resource, you configure the
high-concurrency datasource (that is, the tc Runtime datasource) using a
<Resource> child element of
<GlobalNamingResource>. Most attributes are common to
the standard DBCP and the tc Runtime datasources; however, the following
new attributes apply only to the new tc Runtime datasource.
factory attribute of the
<Resource> element to specify the type of
factory attribute to
org.apache.tomcat.jdbc.pool.DataSourceFactory to use
the tc Runtime high-concurrency datasource. This is also the default
value of the
factory attribute for tc Runtime, so you
will automatically use the high-concurrency datasource if you do not
specify this attribute at all, as shown in the example below.
factory attribute to
use the standard DBCP datasource.
IBM JVM USERS ONLY: If you are using an IBM JVM, see useEquals for important information.
The following table lists the attributes for configuring either the high-concurrency datasource or the standard DBCP datasource. Most attributes are valid for both of the datasources, but some are only valid for one datasource. These exceptions are noted in the table. The default values shown are for the high-concurrency datasource, which is the default datasource for tc Server. Default values for the DBCP datasource may be different. See the Apache DBCP documentation for details.
Table 4.1. Connection Pool Configuration Attributes
|username (required)||The username to pass to the JDBC driver to establish a connection with the database.|
|password (required)||The password to pass to the JDBC driver to establish a connection with the database.|
|url (required)||The connection URL to pass to the JDBC driver to establish a connection.|
|driverClassName (required)||The fully qualified Java class name of the JDBC driver to
use. The driver must be accessible from the same classloader as
|connectionProperties||Connection properties to send to the JDBC driver when
establishing a new database connection. The syntax for this
string is [propertyName=value;]* |
The "user" and "password" properties are passed explicitly, so do not include them here.
|defaultAutoCommit||The default auto-commit state of connections created by this pool. If it is not set, the JDBC driver's default setting is active.|
|defaultReadOnly||driver default||The default read-only state of connections created by
this pool. If not set, the |
|defaultTransactionIsolation||driver default||The default TransactionIsolation state of connections
created by this pool. One of the following: |
(see Javadoc). If not set, the default is the JDBC driver's default.
|defaultCatalog||The default catalog of connections created by this pool.|
|initialSize||The initial number of connections to create when the pool is started.|
|maxActive||The maximum number of active connections that can be allocated from this pool at the same time, or negative for no limit.|
|maxIdle||The maximum number of connections that should be kept in
the pool at all times. Idle connections are checked periodically
(if enabled) and connections that have been idle for longer than
|minIdle||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. The default value
is derived from |
|maxWait||The maximum milliseconds a pool with no available
connections will wait for a connection to be returned before
throwing an exception, or |
|validationQuery||The SQL query to use to validate connections from this pool before returning them to the caller. If specified, the query must be an SQL SELECT statement that returns at least one row.|
|testOnBorrow||Indicates whether objects are validated before borrowed
from the pool. If the object fails to validate, it is dropped
from the pool, and an attempt is made to borrow another. |
|testOnReturn||Indicates if objects are validated before they are
returned to the pool. |
A true value has no effect unless
|testWhileIdle||Indicates whether objects are validated by the idle
object evictor (if any). If an object fails to validate, it is
dropped from the pool. |
|timeBetweenEvictionRunsMillis||The number of milliseconds to sleep between runs of the idle object evictor thread. The thread checks for idle, abandoned connections and validates idle connections. The value should not be set below 1 second (1000).|
|numTestsPerEvictionRun||Not used by the Tomcat JDBC pool. The number of objects to examine during each run of the idle object evictor thread, if any.|
|minEvictableIdleTimeMillis||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.|
|connectionInitSqls||A Collection of SQL statements used to initialize
physical connections when they are first created. These
statements are executed only once, when the connection factory
creates the connection. |
DBCP Versions 1.3 and 1.4 of
incorrectly use "
|poolPreparedStatements||This property is not used.|
|maxOpenPreparedStatements||This property is not used.|
|accessToUnderlyingConnectionAllowed||Not used. Access can be achieved by calling
|removeAbandoned||Set to |
|removeAbandonedTimeout||Timeout in seconds before an abandoned connection can be removed. The value should be set to the longest running query your applications might have.|
|logAbandoned||Set to |
|initSQL (high concurrency JDBC datasource only)||Initial SQL statement that is run only when a connection is first created. Use this feature to set up session settings that should exist during the entire time the connection is established.|
|jdbcInterceptors (high concurrency JDBC datasource only)||Semicolon-separated list of classnames extending
Warning: Be sure you do not include any white space (such as spaces or tabs) in the value of this attribute, or the classes will not be found.
|validationInterval (high concurrency JDBC datasource only)||Number of milliseconds tc Runtime waits before running a validation check to ensure that the JDBC connection is still valid. A connection that has been validated within this interval is not revalidated. Running validation checks too frequently can slow performance.|
|jmxEnabled (high concurrency JDBC datasource only)||Specifies whether the connection pool is registered with the JMX server.|
|fairQueue (high concurrency JDBC datasource only)||Specifies whether calls to |
|abandonWhenPercentageFull||Connections that have been abandoned (timed out) are not
closed and reported up unless the number of connections in use
is above the percentage defined by this parameter. The value
should be between 0 and 100. The default value is 0, which
implies that connections are eligible for closure as soon as
|maxAge||Time in milliseconds to keep this connection. When a
connection is returned to the pool, the pool checks to see if
|useEquals (high concurrency JDBC 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
NOTE FOR IBM JVM
USERS: If you are running tc Runtime on a platform
that uses the IBM JVM (such as AIX), always set the
|suspectTimeout||Timeout value in seconds. Similar to
|alternateUsernameAllowed||For performance reasons, by default the JDBC pool ignores
server.xml snippet shows how to
configure the high-concurrency JDBC datasource for your tc Runtime
instance. For an explanation of the following example, see Description of the High Concurrency JDBC
<?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>
In the preceding sample
<Resource> element does not include a
factory attribute, which means that the resource is using
the default value
org.apache.tomcat.jdbc.pool.DataSourceFactory), which in
turn enables the tc Runtime high-concurrency datasource. The
<Resource> element attributes in the example function
name. JNDI name
of this JDBC resource is
container signs on to the resource manager on behalf of the
resource is a JDBC datasource.
password. Name and password of the database
user who connects to the database.
tc Runtime should use the
driver to connect to the database, in this case a MySQL
url. URL that
the JDBC driver uses to connect to a MySQL database. The format of
this URL is specified by JDBC.
attributes. tc Runtime validates objects before it
borrows them from the connection pool and those objects are
validated by the idle object evictor, but that tc Runtime does
not validate objects when it returns them to
tc Runtime runs the very simple SQL query
SELECT 1 when
it validates connections from the pool before returning a connection
to a user upon request. Because this query should always return a
value, if it returns an exception then tc Runtime knows there is a
problem with the connection.
validationInterval. tc Runtime
waits at least 30 seconds before running a validation query.
tc Runtime sleeps 5000 milliseconds between runs of the idle
connection validation/cleaner thread.
Runtime allocates a maximum of 100 active connections from this pool
at the same time
Runtime keeps a minimum of 10 established connections in the pool at
no connections are available, tc Runtime waits a maximum of 10,000
milliseconds for a connection to be returned before throwing an
Runtime creates 10 connections when it initially starts the
Runtime waits 60 seconds before it removes an abandoned, but still
in use, connection.
tc Runtime removes abandoned connections after they have been idle
removeAbandonedTimeout amount of time.
Runtime flags to log stack traces for application code that
abandoned a Connection.
Minimum amount of time an object may sit idle in the pool before it
is eligible for eviction on this tc Runtime is 30,000
tc Runtime can be monitored using JMX. You must set this attribute
to true if you want HQ to monitor the resource.
jdbcInterceptors. List of
interceptor classes associated with this datasource.
For complete documentation about the tc Runtime
server.xml file and all the possible XML elements you can
include, see Apache
Tomcat Configuration Reference.