As an alternative to a simple and easy-to-use DataSource bundled with Cayenne, it is possible to configure a more feature-rich DataSource based on Apache Jakarta commons-dbcp. To enable commons-dbcp pool, select DBCPDataSourceFactory in the Modeler for a DataNode:
Configuration is done in a properties file that has to be edited in a text editor outside CayenneModeler. The name of this file is specified in the Modeler (with path relative to cayenne.xml location):
Here is an example of such properties file contents:
sample-dbcp.properties
cayenne.dbcp.driverClassName=com.mysql.jdbc.Driver
cayenne.dbcp.url=jdbc:mysql://localhost/cayenne
cayenne.dbcp.username=john
cayenne.dbcp.password=secret
cayenne.dbcp.maxActive=20
cayenne.dbcp.minIdle=5
cayenne.dbcp.maxIdle=8
cayenne.dbcp.maxWait=10000
Supported Properties
Below is a full list of supported properties, that fall into three categories - DataSource properties, connection pool properties and prepared statement pool properties. Only DataSource properties are required.
DataSource Properties
| Property | Description |
|---|---|
| cayenne.dbcp.driverClassName | JDBC driver class |
| cayenne.dbcp.url | Database JDBC URL |
| cayenne.dbcp.username | Database login user name |
| cayenne.dbcp.password | Database login password |
Connection Pool Properties
| Property | Description |
|---|---|
| cayenne.dbcp.maxActive | Maximum number of active connections in the pool |
| cayenne.dbcp.minIdle | Minimum number of idle connections to keep in the pool |
| cayenne.dbcp.maxIdle | Maximum number of idle connections to keep in the pool |
| cayenne.dbcp.maxWait | A maximum time in milliseconds a caller should wait for a connection to be returned from the pool. -1 for indefinite. |
| cayenne.dbcp.validationQuery | A SQL query used to validate a connection, before returning it to the user. Must return at least one row. E.g. "select 1 from dual" |
| cayenne.dbcp.testOnBorrow | A boolean specifying whether connection should be validated before being returned from the pool to the caller. |
| cayenne.dbcp.testOnReturn | A boolean specifying whether connection should be validated before being returned back to the pool. |
| cayenne.dbcp.testWhileIdle | A boolean specifying whether connection should be validated while it is idle. |
| cayenne.dbcp.timeBetweenEvictionRunsMillis | A number of milliseconds an eviction thread should sleep between the runs. |
| cayenne.dbcp.numTestsPerEvictionRun | A number of objects that an idle objects evictor should inspect on each run |
| cayenne.dbcp.minEvictableIdleTimeMillis | Minimum time an object should sit in the pool, before it can be considered for eviction. |
| cayenne.dbcp.whenExhaustedAction | Specifies a pool behavior when the pool is exhausted and more connections are requested. Possible values are strings that follow the constant names defined in org.apache.commons.pool.impl.GenericObjectPool}: {{WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_GROW, WHEN_EXHAUSTED_FAIL. If ommitted, WHEN_EXHAUSTED_BLOCK is assumed. |
| caynne.dbcp.defaultAutoCommit | Auto-commit policy for connections returned from the pool |
| cayenne.dbcp.defaultReadOnly | Read-only policy for connections returned from the pool |
| cayenne.dbcp.defaultTransactionIsolation | Specifies transaction isolation for connections returned from the pool. Possible values are strings that follow the constant names defined in the java.sql.Connection interface: TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE |
| cayenne.dbcp.accessToUnderlyingConnectionAllowed | If set to true the application will be able to get access to the actual connection object which is normally wrapped by a poolable connections |
| cayenne.dbcp.defaultCatalog | Default catalog of connections created by the pool |
PreparedStatement Pool Properties
| Property | Description |
|---|---|
| cayenne.dbcp.poolPreparedStatements | Specifies whether PreparedStatements should be pooled |
| cayenne.dbcp.ps.maxActive | Specifies the maximum number of PreparedStatements that can be borrowed from the pool at one time |
| cayenne.dbcp.ps.maxIdle | Maximum number of idle PreparedStatements in the pool |
| cayenne.dbcp.ps.maxTotal | Maximum number of PreparedStatements that can exist in the pool at one time |
| cayenne.dbcp.ps.maxWait | A maximum time in milliseconds a caller should wait for a PreparedStatement to be returned from the pool. -1 for indefinite. |
| cayenne.dbcp.ps.minEvictableIdleTimeMillis | Number of milliseconds a PreparedStatement can sit idle in the pool before it is elegible for eviction |
| cayenne.dbcp.ps.numTestsPerEvictionRun | Number of idle PreparedStatements that should be examined per eviction run |
| cayenne.dbcp.ps.testOnBorrow | Specifies whether a PreparedStatement should be validated before being borrowed from this pool |
| cayenne.dbcp.ps.testOnReturn | Specifies whether a PreparedStatement should be validated before being returne to this pool |
| cayenne.dbcp.ps.testWhileIdle | Specifies whether PreparedStatements should be validated in the idle eviction thread |
| cayenne.dbcp.ps.timeBetweenEvictionRunsMillis | Specifies the time between the runs of the eviction thread |
| cayenne.dbcp.ps.whenExhaustedAction | Specifies a pool behavior when the pool is exhausted and more PreparedStatements are requested. Possible values are strings that follow the constant names defined in org.apache.commons.pool.impl.GenericObjectPool}: {{WHEN_EXHAUSTED_BLOCK, WHEN_EXHAUSTED_GROW, WHEN_EXHAUSTED_FAIL. If ommitted, WHEN_EXHAUSTED_BLOCK is assumed. |