Helidon MP’s named data source integration requires a connection pool implementation.

Helidon MP comes with support for two connection pools:

1. HikariCP
2. Oracle Universal Connection Pool

You can choose to use either, but not both.

Details concerning each connection pool’s setup are described below.

Maven Coordinates (HikariCP)

Maven Coordinates (Oracle Universal Connection Pool)

Regardless of which connection pool you use, at the lowest level JDBC database driver classes are responsible for making any connections to a relational database. JDBC database driver classes are database-product-specific.

Once you have decided upon a relational database product to use, and JDBC driver classes to use to connect to it, ensure your dependencies are managed, and then ensure that a runtime-scoped <dependency> element describing your JDBC driver classes is present as a child element of your project’s pom.xml file’s <dependencies> element.

See the JDBC 4.3 Specification for more information about JDBC.

Representative setups are described below. The list of such setups is not exhaustive.

Maven Coordinates (H2)

Maven Coordinates (Oracle JDBC)

Here is an example of some named data source configuration as might be found in a src/main/resources/META-INF/microprofile-config.properties configuration source:

javax.sql.DataSource.yourDataSourceName.somePropertyOfYourConnectionPoolAndDataSource = itsValue
javax.sql.DataSource.yourDataSourceName.someOtherPropertyOfYourConnectionPoolAndDataSource = anotherValue

Here is an example of some named data source configuration using system properties on the command line instead:

java \
  -Djavax.sql.DataSource.yourDataSourceName.somePropertyOfYourConnectionPoolAndDataSource=itsValue \
  -Djavax.sql.DataSource.yourDataSourceName.someOtherPropertyOfYourConnectionPoolAndDataSource=anotherValue \
  # ...

Here is an example of some named data source configuration using environment variables as typed directly into a command line shell, relying on MicroProfile Config’s mapping rules, since many shells will not understand environment variable names with periods (.) in them:

JAVAX_SQL_DATASOURCE_YOURDATASOURCENAME_SOMEPROPERTYOFYOURCONNECTIONPOOLANDDATASOURCE=itsValue \
JAVAX_SQL_DATASOURCE_YOURDATASOURCENAME_SOMEOTHERPROPERTYOFYOURCONNECTIONPOOLANDDATASOURCE=anotherValue \
java # ...

Here is an example of some named data source configuration using environment variables as supplied via the env shell command, thus removing the need for MicroProfile Config’s mapping rules:

env 'javax.sql.DataSource.yourDataSourceName.somePropertyOfYourConnectionPoolAndDataSource=itsValue' \
  'javax.sql.DataSource.yourDataSourceName.someOtherPropertyOfYourConnectionPoolAndDataSource=anotherValue' \
  java # ...

Here is an example of some named data source configuration as might be found in a src/main/resources/application.yaml classpath resource:

javax:
  sql:
    DataSource:
      yourDataSourceName:
        somePropertyOfYourConnectionPoolAndDataSource: itsValue
        someOtherPropertyOfYourConnectionPoolAndDataSource: anotherValue

This example presumes you have:

• Set up the Oracle Universal Connection Pool

• Set up Oracle JDBC

This example, in Java properties file format, configures an Oracle Universal Connection Pool-managed data source named main to connect to an Oracle Database on localhost port 1521, using the oracle.jdbc.poolOracleDataSource vendor-supplied DataSource, with a service name of XE, a user of scott, and a password of tiger:

javax.sql.DataSource.main.connectionFactoryClassName = oracle.jdbc.pool.OracleDataSource 
javax.sql.DataSource.main.url = jdbc:oracle:thin://@localhost:1521/XE 
javax.sql.DataSource.main.user = scott
javax.sql.DataSource.main.password = tiger

• Why connectionFactoryClassName? See PoolDataSourceImpl#setConnectionFactoryClassName(String).
• See Thin-style Service Name Syntax.

In general, the properties that can be set on the Oracle Universal Connection Pool can be inferred from the "setter" methods found in the javadoc for the PoolDataSourceImpl class.

In general, the properties that can be set on the oracle.jdbc.pool.OracleDataSource DataSource implementation can be inferred from the "setter" methods found in its javadoc.

This example presumes you have:

• Set up the HikariCP connection pool

• Set up H2

This example, in Java properties file format, configures a HikariCP-managed data source named test to connect to an in-memory H2 database named unit-testing with a user of sa and an empty password:

javax.sql.DataSource.test.dataSourceClassName = org.h2.jdbcx.JdbcDataSource 
javax.sql.DataSource.test.dataSource.url = jdbc:h2:mem:unit-testing;DB_CLOSE_DELAY=-1  
javax.sql.DataSource.test.dataSource.user = sa
javax.sql.DataSource.test.dataSource.password =

• Why dataSourceClassName? See HikariCP’s configuration documentation for information about how HikariCP separates configuration of the connection pool itself from configuration of the vendor-supplied DataSource.
• Why dataSource.? See PropertyElf.java, lines 47–49.
• See the H2 database’s documentation about its URL format.

HikariCP’s configuration properties are described on its Github repository. Properties that should be forwarded on to the vendor-supplied DataSource are prefixed with dataSource. as seen in the example above.

In general, the properties that can be set on the org.h2.jdbcx.JdbcDataSource vendor-supplied DataSource can be inferred from the "setter" methods found in its javadoc.

While the Jakarta Persistence specification standardizes many aspects around programming and usage, it deliberately leaves many required setup and configuration aspects up to the JPA provider. You will need to set up your project differently depending on which JPA provider you choose.

To set up Helidon MP’s Jakarta Persistence integration in your application to work with your chosen JPA provider, you must:

1. Set up and configure named data sources as appropriate
2. Set up and configure Helidon MP’s Jakarta Transactions support
3. Include the proper Jakarta Persistence-related dependencies
4. Set up your project to generate and compile the static metamodel
5. Set up your project for static weaving

Details and examples for each supported JPA provider are below.

To include the Jakarta Persistence APIs that you will need and to include the core of Helidon’s Jakarta Persistence integration:

• Ensure your dependencies are managed

• Ensure you have set up and configured named data sources as appropriate

• Ensure you have set up and configured Helidon MP’s Jakarta Transactions support

• Ensure the following <dependency> elements are present as child elements of your project’s pom.xml file’s <dependencies> element:

  <dependency>
      <groupId>jakarta.persistence</groupId>
      <artifactId>jakarta.persistence-api</artifactId>
      <scope>provided</scope> 
  </dependency>
  <dependency>
      <groupId>io.helidon.integrations.cdi</groupId>
      <artifactId>helidon-integrations-cdi-jpa</artifactId>
      <scope>runtime</scope> 
  </dependency>

  content_copy Copied
  • The scope is provided, which ensures that the JPA classes required for compilation are available at compile time.
  • The scope is runtime, which ensures that Helidon’s core, provider-independent Jakarta Persistence integration is available at runtime.

These <dependency> elements do not set up a JPA provider. See details below for the JPA provider you have chosen to use.

To generate and compile the Jakarta Persistence static metamodel for your application, regardless of whether you are using Hibernate ORM or Eclipselink, make sure the <plugin> element in the following code snippet is present as a child element of the <pluginManagement><plugins> element sequence as shown below:

<pluginManagement>
    <plugins>

        <!-- ... -->

        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <executions>
                <execution>
                    <id>default-compile</id>
                    <configuration>
                        <annotationProcessorPaths>
                            <annotationProcessorPath>
                                <groupId>org.hibernate.orm</groupId>
                                <artifactId>hibernate-jpamodelgen</artifactId> 
                                <version>6.1.1.Final</version> 
                            </annotationProcessorPath>
                        </annotationProcessorPaths>
                    </configuration>
                </execution>
            </executions>
        </plugin>

        <!-- ... -->

    </plugins>
</pluginManagement>

• This adds the hibernate-jpamodelgen jar, which contains a Java annotation processor that generates the static metamodel source code, to the Java compiler’s annotation processor path so that it is active at compile time.
• Always check Maven Central for up to date versions and make sure the version used is that of Hibernate ORM itself.

For more on the Hibernate ORM hibernate-jpamodelgen annotation processor, see Hibernate Metamodel Generator in Hibernate ORM’s documentation.

To include Helidon’s Jakarta Persistence-related integration for Hibernate ORM:

• Ensure your dependencies are managed

• Ensure the basics of your JPA project are set up properly

• Ensure the following <dependency> elements are present as child elements of your project’s pom.xml file’s <dependencies> element:

  <dependency>
      <groupId>io.helidon.integrations.cdi</groupId>
      <artifactId>helidon-integrations-cdi-hibernate</artifactId>
      <scope>runtime</scope> 
  </dependency>

  content_copy Copied
  • The scope is runtime, which ensures that Helidon MP’s Hibernate ORM integration is available at runtime.

Hibernate ORM can alter your classes' bytecode at build time to keep track of changes made to objects participating in Jakarta Persistence workflows.

To set up this required static weaving for Hibernate ORM, ensure that the following <plugin> element is present as a child element of your project’s pom.xml file’s <plugins> element:

<plugin>
    <groupId>org.hibernate.orm.tooling</groupId>
    <artifactId>hibernate-enhance-maven-plugin</artifactId>
    <!--
        Ideally, your plugin versions are managed via a
        <pluginManagement> element, which is why the <version> element
        is commented out below.  If, nevertheless, you opt for the
        explicit version, check
        https://search.maven.org/artifact/org.hibernate.orm/hibernate-enhance-maven-plugin
        for up-to-date versions, and make sure the version is the same
        as that of Hibernate ORM itself.
    -->
    <!-- <version>6.1.1.Final</version> -->
    <executions>
        <execution>
            <id>Statically enhance JPA entities for Hibernate</id>
            <phase>compile</phase>
            <goals>
                <goal>enhance</goal>
            </goals>
            <configuration>
                <failOnError>true</failOnError>
                <enableDirtyTracking>true</enableDirtyTracking>
                <enableLazyInitialization>true</enableLazyInitialization>
            </configuration>
        </execution>
    </executions>
</plugin>

You must also add a file named src/main/resources/META-INF/hibernate.properties with the following line as its sole contents:

hibernate.bytecode.provider=none 

• The value of none instructs Hibernate ORM to not attempt to perform weaving at runtime.

For more on the hibernate-enhance-maven-plugin in particular, see its documentation.

For more on Hibernate ORM’s bytecode enhancement (weaving) in general, see Bytecode Enhancement in Hibernate ORM’s documentation.

For more on bytecode enhancement properties, see Bytecode Enhancement Properties in Hibernate ORM’s documentation.

To include Helidon’s Jakarta Persistence-related integration for Eclipselink:

• Ensure your dependencies are managed

• Ensure the basics of your JPA project are set up properly

• Ensure the following <dependency> elements are present as child elements of your project’s pom.xml file’s <dependencies> element:

  <dependency>
      <groupId>io.helidon.integrations.cdi</groupId>
      <artifactId>helidon-integrations-cdi-eclipselink</artifactId>
      <scope>runtime</scope> 
  </dependency>

  content_copy Copied
  • The scope is runtime, which ensures that Helidon MP’s Eclipselink integration is available at runtime.

Eclipselink can alter your classes' bytecode at build time to keep track of changes made to objects participating in Jakarta Persistence workflows.

To set up this required static weaving for Eclipselink, ensure that the following <plugin> element is present as a child element of your project’s pom.xml file’s <plugins> element:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <version>3.1.0</version> 
    <executions>
        <execution>
            <id>weave</id>
            <phase>process-classes</phase>
            <goals>
                <goal>java</goal>
            </goals>
            <configuration combine.self="override">
                <classpathScope>compile</classpathScope>
                <mainClass>org.eclipse.persistence.tools.weaving.jpa.StaticWeave</mainClass>
                <arguments>
                    <argument>-loglevel</argument>
                    <argument>INFO</argument>
                    <argument>-persistenceinfo</argument>
                    <argument>${project.build.outputDirectory}</argument>
                    <argument>${project.build.outputDirectory}</argument>
                    <argument>${project.build.outputDirectory}</argument>
                </arguments>
            </configuration>
        </execution>
    </executions>
</plugin>

• Always check Maven Central for up-to-date versions.

For more on the Eclipselink static weaving command-line utility, see Static Weaving in the Eclipselink documentation.

Here is a partial example of a persistence unit named prod with a helpful description:

<!-- ... -->

<persistence-unit name="prod" transaction-type="JTA"> 
    <description>The production database</description>

    

</persistence-unit>

<!-- ... -->

• Because Helidon MP’s JPA integration is for container-managed JPA, the transaction-type attribute must in practice always be set to JTA.
• The order of subsequent child elements is significant and governed by the XML schema.

A persistence unit is always associated with exactly one named data source.

Because Helidon MP’s Jakarta Persistence integration provides support for container-managed JPA, and because container-managed JPA requires Jakarta Transactions (JTA), the kind of named data source a persistence unit is associated with is always a JTA data source. The <jta-data-source> element, a child of the <persistence-unit> element, is how you link a persistence unit to a named data source you previously configured.

Example: Persistence Unit with JTA Data Source

<!-- ... --->

<persistence-unit name="prod" transaction-type="JTA">
    <description>The production database</description>
    <jta-data-source>main</jta-data-source>  

</persistence-unit>

<!-- ... -->

A persistence unit lists the classes that should be managed and that will take part in Jakarta Persistence workflows. You must list:

1. Entity classes
2. Embeddable classes
3. Mapped superclasses
4. Converter classes

You use a sequence of <class> elements to do this. Each <class> element contains the fully-qualified class name of one of the types of managed classes listed above.

Example: Persistence Unit with Class Elements

<!-- ... --->

<persistence-unit name="prod" transaction-type="JTA">
    <description>The production database</description>
    <jta-data-source>main</jta-data-source>
    <class>com.example.ExampleEntity0</class> 
    <class>com.example.ExampleEntity1</class>

    

</persistence-unit>

<!-- ... -->

Persistence units can have simple properties attached to them to further configure the backing JPA provider. You use the <properties> element to specify them.

Example: Persistence Unit with Properties

<!-- ... --->

<persistence-unit name="prod" transaction-type="JTA">
    <description>The production database</description>
    <jta-data-source>main</jta-data-source> 
    <class>com.example.ExampleEntity0</class>
    <class>com.example.ExampleEntity1</class>
    <properties>
        <property name="hibernate.show_sql" value="true"/> 
        <property name="eclipselink.weaving" value="false"/> 
    </properties>
</persistence-unit>

<!-- ... -->