Pooling and XA support for DataSourceFactory
- Christian Schneider
Deprecated
Since version 1.0.0 pooling and XA works differently. See Pooling and XA support in 1.0.0
| Module | Description |
|---|---|
| pax-jdbc-pool-dbcp | Pooling and JTA support using dbcp2 |
| pax-jdbc-pool-aries | Pooling and JTA support using aries transaction jdbc |
Both modules work basically in the same way and just use a different library for pooling. So make sure you only install one of them.
How it works
When one of the pax-jdbc-pool bundles is installed it will start to track DataSourceFactory services. For each such service it finds it will create an additional service with a pooling and XA wrapper around the original DataSourceFactory.
The pooled service will mostly have the same properties as the original service but it will add "-pool" to the osgi.jdbc.driver.name. If a TransactionManager is available it will also add "-xa" at the end. So it will be easy to select the new Factory instead of the old one.
Keep in mind that the pooled XA DataSource will be published using the javax.sql.DataSource interface. So from the outside it will look like a normal DataSource. Inside it will take care that the connection is added to the TransactionManager as an XA resource.
Additonal / Changed Service Properties
The new pooled DataSourceFactory OSGi service provided by pax-jdbc-pool adds the following properties while keeping the properties of the original DataSourceFactory.
| Key | Value | Description |
|---|---|---|
| osgi.jdbc.driver.name | <orig_value>-pool[-xa] | adds -pool and if TransactionManager is available also -xa |
| pool | true | |
| xa | true | only if TransactionManager is available |
pax-jdbc-pool-dbcp2 configuration
When calling create you should supply the pooled DataSourceFactory with the same properties as the original one. In addition you can also set pooling properties that start with "pool.". These will be forwarded to the pooling library.
See http://commons.apache.org/proper/commons-dbcp/configuration.html.
| Key (pool.) | Type | Description |
|---|---|---|
| blockWhenExhausted | boolean | Sets whether to block when the borrowObject() method is invoked when the pool is exhausted (the maximum number of "active" objects has been reached) |
| lifo | boolean | Sets whether the pool has LIFO (last in, first out) behaviour with respect to idle objects - always returning the most recently used object from the pool, or as a FIFO (first in, first out) queue, where the pool always returns the oldest object in the idle object pool |
| maxIdle | int | Returns the cap on the number of "idle" instances in the pool |
| maxTotal | int | Sets the cap on the number of objects that can be allocated by the pool (checked out to clients, or idle awaiting checkout) at a given time |
| maxWaitMillis | long | Sets the maximum amount of time (in milliseconds) the borrowObject() method should block before throwing an exception when the pool is exhausted and getBlockWhenExhausted() is true |
| minEvictableIdleTimeMillis | long | Sets 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 - see setTimeBetweenEvictionRunsMillis(long)) |
| minIdle | int | Sets the target for the minimum number of idle objects to maintain in the pool |
| numTestsPerEvictionRun | int | Sets the maximum number of objects to examine during each run (if any) of the idle object evictor thread |
| softMinEvictableIdleTimeMillis | long | Sets 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 - see setTimeBetweenEvictionRunsMillis(long)), with the extra condition that at least minIdle object instances remain in the pool |
| testOnBorrow | boolean | Sets whether objects borrowed from the pool will be validated before being returned from the borrowObject() method |
| testOnCreate | boolean | Sets whether objects created for the pool will be validated before being returned from the borrowObject() method |
| testOnReturn | boolean | Sets whether objects borrowed from the pool will be validated when they are returned to the pool via the returnObject() method |
| testWhileIdle | boolean | Returns whether objects sitting idle in the pool will be validated by the idle object evictor (if any - see setTimeBetweenEvictionRunsMillis(long)) |
| timeBetweenEvictionRunsMillis | long | Sets the number of milliseconds to sleep between runs of the idle object evictor thread |
The following properties will only work for pax-jdbc-pool >= 0.6.0
| Key (factory.) | Type | Description | Default |
|---|---|---|---|
| cacheState | boolean | If true, the pooled connection will cache the current readOnly and autoCommit settings when first read or written and on all subsequent writes. This removes the need for additional database queries for any further calls to the getter. If the underlying connection is accessed directly and the readOnly and/or autoCommit settings changed the cached values will not reflect the current state. In this case, caching should be disabled by setting this attribute to false | true |
| defaultAutoCommit | boolean | The default auto-commit state of connections created by this pool. If not set then the setAutoCommit method will not be called | driver default |
| defaultCatalog | String | Sets the default "catalog" setting for borrowed Connections | driver default |
| defaultReadOnly | boolean | The default read-only state of connections created by this pool. If not set then the setReadOnly method will not be called. (Some drivers don't support read only mode, ex: Informix) | driver default |
| defaultTransactionIsolation | int | The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc for int values)
| driver default |
Example config for pax-jdbc-pool-dbcp2 together with pax-jdbc-config
Create config in etc/org.ops4j.datasource-test.cfg:
osgi.jdbc.driver.name=H2-pool-xa databaseName=test user=sa password= dataSourceName=test2 pool.maxTotal=8
Installation in karaf 3
Install the features
feature:repo-add mvn:org.ops4j.pax.jdbc/pax-jdbc-features/0.5.0/xml/features feature:install transaction jndi pax-jdbc-h2 pax-jdbc-config pax-jdbc-pool-dbcp2
The automatically created DataSource service will look like this:
karaf@root()> service:list javax.sql.DataSource [javax.sql.DataSource] ---------------------- dataSourceName = test2 service.factoryPid = org.ops4j.datasource databaseName = test user = sa osgi.jdbc.driver.name = H2-pool-xa osgi.jndi.service.name = test2 felix.fileinstall.filename = file:/.../etc/org.ops4j.datasource-test2.cfg service.pid = org.ops4j.datasource.b1809982-d20a-4b84-b48c-ad23bbafb9ec pool.maxTotal = 8 password = service.id = 743 Provided by : OPS4J Pax JDBC Config (72)
It will have pooling and XA transaction support.