A basic <database> configuration specifies the following:
This <database> will configure a javax.sql.DataSource and store it in JNDI at java:comp/env/jdbc/test_mysql. To use the data source, follow the database use pattern in the DataSource tutorial.
Sample <database> configurations are available in the thirdparty driver page.
Although some deployments will specify driver and connection pool parameters, the default values will be fine for most applications.
An established channel of communication between a client and a server. The client and the server may be on separate machines, on the same machine, or even running in the same JVM. Often the connection is established using TCP/IP as the transport of communication.
A database connection is used to allow the Java program, running in a JVM, to communicate with a database server.
A set of connections maintained so that the connections can be reused when there is a future need for the conneciton.
Connection pools are used to reduce the overhead of using a database. Establishing a connection to the database is a costly operation. A connection pool keeps a pool of open connections, each connection can be used for a time as needed, and then released back to the pool. A connection that has been released back to the pool can then be reused.
Connection pooling is especially important in server applications. The overhead of opening a new connection for each new client request is too costly. Instead, the database pool allows for a connection to be opened once and then reused for many requests.
A JDBC term (and interface name) used for a factory that is used to obtain connections.
Resin provides an implementation of
An implemetation of a defined interface that hides the details of communication with a device or other resource, such as a database.
A Driver provides an interface and is responsible for the communication with the database. Every different database (i.e Oracle, MySQL) has their own means of enabling communication from the client (in this case Resin and you applications) and the database. The Driver provides a common interface that hides the details of that communication.
A transaction is used to mark a group of operations and provide a guarantee that all of the operations happen, or none of them happen. Transactions protect the integrity of the database.
Transactions are especially important in server applications where many threads of processing may be interacting with the database at the same time.
For a simple example, imagine a set of operations that reads a value,
calculates a new value, and then updates the database.
Imagine if one thread is performing this operation, and in the middle of this read/calculate/update, another thread performs an update. The data that the first thread obtained from the read and is using for the calculation and update is no longer valid.
Placing the read/calculate/update operations in a transactions guarantees that only one thread can perform those operations at a time, if a second thread comes along and tries to perform the operation, it will have to wait for the first thread to finish before it can begin.
A distributed transaction is a transaction that involves more than one connection.
If the guarantees that transactions apply need to apply to operations that occur on two databases within the same transaction, distributed transactions are needed.
Distributed transactions are rarely needed, and few databases really support them.
Configure a database resource, which is a database pool that manages and provides connections to a database.
|jndi-name||JNDI name to store the pool under. Servlets, jsp, and
other java code use this name. The path is relative to
||driver||Configure the database driver.||backup-driver||Configure a backup driver.||max-connections||Pooling parameter - maximum number of allowed connections||20
||max-idle-time||Pooling parameter - maximum time an idle connection is kept in
the pool||30 sec
||max-active-time||Pooling parameter - maximum time a connection allowed to be active
||max-pool-time||Pooling parameter - maximum time a connection is kept in the pool||24 hours
||connection-wait-time||Pooling parameter - how long to wait for an idle connection (Resin 1.2.3)||10 minutes
||max-overflow-connections||Pooling parameter - how many "overflow" connection are allowed if the connection wait times out.||0
||ping-table||Reliability parameter - The database table used to "ping", checking that the connection is still live.||n/a
||ping||Reliability parameter - test for live connections before allocating them from the pool.||false
||ping-interval||Reliability parameter - how often to ping for ping-on-idle||60s
||prepared-statement-cache-size||A cache that holds prepared statements, a reused prepared statement avoids the overhead of the driver making the prepared statement||0
||spy||A debugging aid, if true, generate ||false
All times default to seconds, but can use longer time periods:
Configure a database driver. The driver is a class provided by the database vendor, it is responsible for the communication with the database.
The jar file with the driver in it can be placed in
Examples of common driver configurations are in Third-party Database Configuration.
|type||The Java class name of the database driver.||url||The driver specific database url.||user||The username to give the database driver.||password||The password to give the database driver.||init-param||Set driver specific properties not known to Resin.|
Database vendors usually provide many different classes that are potential candidates for type. The JDBC api has developed over time, and is now being replaced by the more general JCA architecture. The driver you choose depends on the options the vendor offers, and whether or not you need distributed transactions.
JCA is replacing JDBC as the API for database drivers. JCA is a much more flexible approach that defines an API that can be used for any kind of connection, not just a connection to a database. If a database vendor provides a JCA interface, it is the best one to use.
A JCA driver implements
The same JCA driver is used for both non-distributed and distributed transactions
JDBC 2.0 defined the interface ConnectionPoolDataSource. A
A driver that implements ConnectionPoolDataSource is better than a JDBC 1.0 driver that implements Driver.
JDBC 2.0 defined the interface XADataSource for connections that can participate in distributed transactions. A distributed transaction is needed when transactions involve multiple connections. For example, with two different database backends, if the guarantees that transactions apply need to apply to operations that occur on both databases within the same transaction, distributed transactions are needed.
Distributed transactions are rarely needed, and few databases really support
them. Some vendors will provide
Driver is the original JDBC interface, and is the least desirable kind of driver to use. Resin can still pool database connections using these drivers, but it will not be as efficient as the newer drivers.
init-param is used to set properties of the database driver that are specific to the driver and are not generic enough for resin to provide a named configuration tag.
For example, MySQL drivers accept the
Pooling configuration controls the behaviour of Resin's pooling of database connections. For most applications and databases the only needed change is to increase the max-connections value to meet high demand. Other pooling parameters have defaults that are based on our years of experience with many different databases in many different applications. Changes from the defaults should only be done in response to specific problems, and with a good understanding of how pooling works.
Resin's database pool can test if the pooled database connection is still alive by configuring a ping query. This is typically only necessary if the pooling parameters are changed from their default values.
If the pool is configured with a long max-idle-time the database connection may become stale if the database is restarted, or if the database is configured with a shorter connection timeout value than the configuration of the Resin pool. Normally when a database connection is returned to the pool it will wait there until the next request or the idle-time expires. If the database goes down in the meantime or closes the connection, the connection will become stale. The ping configuration can test the database connection.
When pinging, Resin's DBPool will test a table specified with the ping-table parameter before returning the connection to the application. If the ping fails, the connection is assumed to be no good and a different connection from the pool is returned. For a ping-table of my_table, Resin will use a query like the following:
You can test the database reliability using the following steps:
Ideally, the JNDI lookup of
A connection is obtained from the
It is very important that the
Always put a
The following example shows the use of a
Copyright (c) 1998-2009 Caucho Technology, Inc. All rights reserved.
caucho® , resin® and quercus® are registered trademarks of Caucho Technology, Inc.