microBean Hikari Connection Pool CDI Extension

The microBean Hikari Connection Pool CDI Extension project integrates the Hikari connection pool into CDI 2.0 SE environments.

Installation

To install the microBean Hikari Connection Pool CDI Extension project, ensure that it and its dependencies are present on the classpath at runtime. In Maven, your dependency stanza should look like this:

<dependency>
  <groupId>org.microbean</groupId>
  <artifactId>microbean-datasource-cdi-hikaricp</artifactId>
  <!-- See http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.microbean%22%20AND%20a%3A%22microbean-datasource-cdi-hikaricp%22 for available releases. -->
  <version>0.1.4</version>
  <type>jar</type>
  <scope>runtime</scope>
</dependency>

Releases are available in Maven Central. Snapshots are available in Sonatype Snapshots.

You will also need a JDBC driver implementation on your classpath as well at runtime.

Usage

The microBean Hikari Connection Pool CDI Extension project works, essentially, by satisfying DataSource injection points. That is, in your CDI 2.0 SE application somewhere, if you do:

@Inject
@Named("test")
private DataSource ds;

...this project will arrange for a DataSource named test backed by the Hikari connection pool to be assigned to this ds field in application scope. If you do:

@Inject
private DataSource orders;

...this project will arrange for a DataSource named orders backed by the Hikari connection pool to be assigned to this orders field in application scope.

For such injection points to be satisfied, the microBean Hikari Connection Pool CDI Extension project needs to understand how to configure any particular named DataSource implementation that will be injected. To do this, it looks for DataSourceDefinition annotations and datasource.properties classpath resources.

Any type-level DataSourceDefinition annotations that are encountered are processed. Then datasource.properties classpath resources are sought and loaded, and their properties are processed in the manner described below.

Properties in each datasource.properties file are inspected if they start with either javax.sql.DataSource. or com.zaxxer.hikari.HikariDataSource., followed by a datasource name that does not contain a period ('.'), followed by a period ('.'), followed by the name of a Hikari connection pool configuration setting.

Properties are not read until all datasource.properties classpath resources have been effectively combined together.

datasource.properties classpath resources override DataSourceDefinition annotation values.

For each distinct data source name, a HikariDataSource is created and made available in application scope with a Named qualifier whose value is set to the data source name. That DataSource implementation will then be configured by applying all the relevant property suffixes after the first .dataSource. string. So, for example, the property javax.sql.DataSource.test.dataSource.url=jdbc:h2:mem:temp will result in a HikariDataSource implementation named test, with the Hikari connection pool setting named dataSource.url set to jdbc:h2:mem:temp.

Here is an example of a datasource.properties file that works with the in-memory variant of the H2 database:

javax.sql.DataSource.test.dataSourceClassName=org.h2.jdbcx.JdbcDataSource
javax.sql.DataSource.test.dataSource.url=jdbc:h2:mem:test
javax.sql.DataSource.test.username=sa
javax.sql.DataSource.test.password=

Here is an example of a similar datasource.properties file that declares two datasources:

javax.sql.DataSource.test.dataSourceClassName=org.h2.jdbcx.JdbcDataSource
javax.sql.DataSource.test.dataSource.url=jdbc:h2:mem:test
javax.sql.DataSource.test.username=sa
javax.sql.DataSource.test.password=

javax.sql.DataSource.prod.dataSourceClassName=org.h2.jdbcx.JdbcDataSource
javax.sql.DataSource.prod.dataSource.url=jdbc:h2:mem:test
javax.sql.DataSource.prod.username=production
javax.sql.DataSource.prod.password=s3kret