Kodo JDO uses a relational database for object persistence. It communicates with the database using the Java DataBase Connectivity (JDBC) APIs. This chapter describes how to configure Kodo to work with the JDBC driver for your database, and how to access JDBC functionality at runtime.
Kodo JDO includes its own javax.sql.DataSource implementation, complete with configurable connection pooling, SQL logging, and prepared statement caching. If you choose to use Kodo JDO's DataSource, then you must specify the properties below.
Required properties:
javax.jdo.option.ConnectionUserName: The JDBC user name for connecting to the database.
javax.jdo.option.ConnectionPassword: The JDBC password for the above user.
javax.jdo.option.ConnectionURL: The JDBC URL for the database.
javax.jdo.option.ConnectionDriverName: The JDBC driver.
To configure advanced features such as connection pooling and prepared statement caching, or to configure the underlying JDBC driver, use the following optional properties. The syntax of these property strings follows the syntax of Kodo plugin parameters described in Section 2.4, “Plugin Configuration”.
kodo.ConnectionProperties: If the listed driver is an instance of java.sql.Driver, this string will be parsed into a Properties instance, which will then be used to obtain database connections through the java.sql.Driver.connect(String url, Properties props) method. If, on the other hand, the driver is a javax.sql.DataSource, the string will be treated as a plugin properties string, and matched to the bean setter methods of the DataSource instance.
kodo.ConnectionFactoryProperties: Kodo JDO's built-in DataSource has the following configuration options you can set via this plugin string:
MaxActive: The maximum number of database connections in use at one time. Defaults to 8.
MaxIdle: The maximum number of idle database connections to keep in the pool. Defaults to 8.
MaxWait: The maximum number of milliseconds to wait for a free database connection to become available before giving up. Defaults to 3000.
MinEvictableIdleTimeMillis: The minimum number of milliseconds that a database connection can sit idle before it becomes a candidate for eviction from the pool. Defaults to 30 minutes. Set to 0 to never evict a connection based on idle time alone.
TestOnBorrow: Whether to to validate database connections before obtaining them from the pool. Note that validation only consists of a call to the connection's isClosed method unless you specify a ValidationSQL string to use to send a quick query. Defaults to true.
TestOnReturn: Set to true to validate database connections when they are returned to the pool. Note that validation only consists of a call to the connection's isClosed method unless you specify a ValidationSQL string to use to send a quick query.
TestWhileIdle: Set to true to periodically validate idle database connections.
TimeBetweenEvictionRunsMillis: The number of milliseconds between runs of the eviction thread. Defaults to -1, meaning the eviction thread will never run.
ValidationSQL: A simple SQL query to issue to validate a database connection. If this property is not set, then the only validation performed is to use the Connection.isClosed method. The following table shows the default settings for different databases. If a database is not shown, this property defaults to null.
Table 4.1. Validation SQL Defaults
| Database | SQL |
|---|---|
| DB2 | SELECT DISTINCT(CURRENT TIMESTAMP) FROM SYSIBM.SYSTABLES |
| Informix | SELECT DISTINCT CURRENT TIMESTAMP FROM INFORMIX.SYSTABLES |
| MySQL | SELECT NOW() |
| Oracle | SELECT SYSDATE FROM DUAL |
| Postgres | SELECT NOW() |
| SQLServer | SELECT GETDATE() |
| Sybase | SELECT GETDATE() |
To disable validation SQL, set this property to an empty string, as in Example 4.1, “Properties File for the Kodo JDO DataSource”
ValidationTimeout: The minimum number of milliseconds that must elapse before a connection will ever be re-validated. This property is usually used with TestOnBorrow or TestOnReturn to reduce the number of validations performed, because the same connection is often borrowed and returned many times in short periods of time. Defaults to 300000 (5 minutes).
WhenExhaustedAction: The action to take when there are no available database connections in the pool. Set to 0 to immediately throw an exception. Set to 1 to block until a connection is available or the maximum wait time is exceeded. Set to 2 to automatically grow the pool. Defaults to 1 (block).
RollbackOnReturn: Force all connections to be rolled back when they are retuned to the pool. If false, the datasource will only roll back connections when it detects that there has been any transactional activity on the connection.
Additionally, the following properties are available whether you use Kodo JDO's built-in DataSource or a third-party's:
MaxCachedStatements: The maximum number of java.sql.PreparedStatements to cache. Statement caching can dramatically speed up some databases. Defaults to 70 for Kodo's data source, and 0 for third-party data sources. Most third-party data sources do not benefit from Kodo's prepared statement cache, because each returned connection has a unique hash code, making it impossible for Kodo to match connections to their cached statements.
QueryTimeout: The maximum number of seconds the JDBC driver will wait for a statement to execute.
Example 4.1. Properties File for the Kodo JDO DataSource
javax.jdo.option.ConnectionUserName: user
javax.jdo.option.ConnectionPassword: pass
javax.jdo.option.ConnectionURL: jdbc:hsqldb:db-hypersonic
javax.jdo.option.ConnectionDriverName: org.hsqldb.jdbcDriver
kodo.ConnectionFactoryProperties: MaxActive=50, MaxIdle=10, \
ValidationTimeout=50000, MaxCachedStatements=100, ValidationSQL=""