1 Using JPA with Coherence

Coherence provides native, entity-based implementations of the CacheStore and CacheLoader interfaces that use the Jakarta Persistence (JPA) to load and store objects to a database. Before using JPA with Coherence, you should be familiar with the CacheStore and CacheLoader interfaces. These interfaces are used to cache data sources. See Caching Data Sources.

Note:

Only resource-local and bootstrapped entity managers can be used with Coherence and JPA. Container-managed entity managers and those that use Jakarta Transactions (JTA) are not currently supported.

Note:

Coherence 26.1 uses Jakarta Persistence 3.2 APIs in the jakarta.persistence namespace. Use a matching provider and dependency set. Review persistence-specific property renames when migrating from javax.persistence; do not rename unrelated Java SE javax packages.

This chapter includes the following sections:

• Overview of the JPA CacheStore and CacheLoader Implementations
  Oracle Coherence provides two implementations of the CacheStore and CacheLoader interfaces which can be used with JPA: a generic JPA implementation and an EclipseLink-specific implementation.
• Obtaining a JPA Provider Implementation
  A JPA provider allows you to work directly with Java objects, rather than with SQL statements. You map, store, update and retrieve data, and the provider performs the translation between database entities and Java objects.
• Configuring a Coherence JPA Cache Store
  Using JPA with Coherence requires configuring persistence properties and defining a cache that uses the JpaCacheStore implementation.
• Preparing a Current JPA Integration
  Align the persistence API, provider, cache-store semantics and application trust metadata.

Overview of the JPA CacheStore and CacheLoader Implementations

Oracle Coherence provides two implementations of the CacheStore and CacheLoader interfaces which can be used with JPA: a generic JPA implementation and an EclipseLink-specific implementation. For both implementations, the entities must be mapped to the data store and a JPA persistence unit configuration must exist. A JPA persistence unit is defined as a logical grouping of user-defined entity classes that can be persisted and their settings. The JPA run-time configuration file, persistence.xml, and the default JPA Object-Relational mapping file, orm.xml, are typically provided as part of a JPA solution.

Note:

As of Coherence 15.1.1.0, classes JpaCacheStore and JpaCacheLoader are moved from the package com.oracle.toplink.jpa to com.oracle.coherence.jpa.

Table 1-1 describes the JPA implementations provided by Coherence.

Table 1-1 JPA-Related CacheStore and CacheLoader API Included with Coherence

Class Name	Location	Description
JpaCacheStore	COHERENCE_HOME\lib\coherence-jpa.jar	A JPA implementation of the Coherence CacheStore interface. Use this class as a full load and store implementation. It can use any JPA implementation to load and store entities to and from a data store. Note: The persistence unit is assumed to be set to use RESOURCE_LOCAL transactions.
JpaCacheLoader		A JPA implementation of the Coherence CacheLoader interface. Use this class as a load-only implementation. It can use any JPA implementation to load entities from a data store. Use the JpaCacheStore class for a full load and store implementation.
EclipseLinkJPACacheStore	ORACLE_HOME\oracle_common\modules\oracle.toplink\toplink-grid.jar	An EclipseLink specific JPA implementation of the Coherence CacheStore interface. This implementation is intended to be used where the application uses Coherence directly and the cache store and loader is used behind the scene to persist and load data. Note: To use this implementation, make sure no cache interceptors or query redirectors from the EclipseLink-Coherence integration are set within the persistence unit for the specific class.
EclipseLinkJPACacheLoader		An EclipseLink specific JPA implementation of the Coherence CacheLoader interface. Note: To use this implementation, make sure no cache interceptors or query redirectors from the EclipseLink-Coherence integration are set within the persistence unit for the specific class.

Obtaining a JPA Provider Implementation

A JPA provider allows you to work directly with Java objects, rather than with SQL statements. You map, store, update and retrieve data, and the provider performs the translation between database entities and Java objects.

Oracle recommends using EclipseLink JPA– the reference implementation for the Jakarta Persistence 3.2 specification and also the JPA provider used in Oracle TopLink. EclipseLink provides a high-performance JPA implementation with many advanced features for caching, threading, and overall performance.

The EclipseLink JAR file (eclipselink.jar) is included in the Coherence installation and can be found in the ORACLE_HOME\oracle_common\modules\oracle.toplink folder.

Configuring a Coherence JPA Cache Store

Using JPA with Coherence requires configuring persistence properties and defining a cache that uses the JpaCacheStore implementation.

This section includes the following topics:

• Mapping the Persistent Classes
  
• Configuring JPA
  
• Configuring a Coherence Cache for JPA
  
• Configuring the Persistence Unit
  

Mapping the Persistent Classes

Map the entity classes to the database. This will allow you to load and store objects through the JPA cache store. JPA mappings are standard, and can be specified in the same way for all JPA providers.

You can map entities either by annotating the entity classes or by adding an orm.xml or other XML mapping file. See the JPA provider documentation for more information about how to map JPA entities.

Configuring JPA

Edit the persistence.xml file to create the JPA configuration. This file contains the properties that dictate run-time operation.

Set the transaction type to RESOURCE_LOCAL and provide the required JDBC properties for your JPA provider (such as driver, url, user, and password) with the appropriate values for connecting and logging into your database. List the classes that are mapped using JPA annotations in <class> elements. Example 1-1 illustrates a sample persistence.xml file with the typical properties that you can set.

Example 1-1 Sample persistence.xml File for JPA

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="https://jakarta.ee/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_2.xsd"
             version="3.2">
  <persistence-unit name="EmpUnit" transaction-type="RESOURCE_LOCAL">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <class>com.oracle.coherence.handson.Employee</class>
    <properties>
      <property name="eclipselink.cache.shared.default" value="false"/>
    </properties>
  </persistence-unit>
</persistence>

Application requirements

Place this file at META-INF/persistence.xml and provide the compatible entity class, provider and JDBC driver. Configure the database URL, user and secret through the deployment/provider mechanism rather than source-controlled credentials. This descriptor intentionally omits connection credentials; it is not a runnable database setup without those deployment inputs. The JpaCacheStore creates resource-local entity managers; it does not consume a container-managed JTA entity manager.

Configuring a Coherence Cache for JPA

Create a coherence-cache-config.xml file to override the default Coherence settings and define a caching scheme. The caching scheme includes a <cachestore-scheme> element that lists the JPA implementation class and includes the following parameters.

• The entity name of the entity being stored. Unless it is explicitly overridden in JPA, this is the unqualified name of the entity class. Example 1-2 uses the built-in Coherence macro {cache-name} that translates to the name of the cache that is constructing and using the cache store. This works because a separate cache must be used for each type of persistent entity and Coherence ensures that the name of each cache is set to the name of the entity that is being stored in it.

• The fully qualified name of the entity class. If the classes are all in the same package and use the default JPA entity names, then you can again use the {cache-name} macro for the part that is variable across the different entity types. In this way, the same caching scheme can be used for all of the entities that are cached within the same persistence unit.

• The persistence unit name. This should be the same as the name specified in the persistence.xml file.

The various named caches are then directed to use the JPA caching scheme. Example 1-2 is a sample coherence-cache-config.xml file that defines a cache named Employee that caches instances of the Employee class. The cache is configured to use the JpaCacheStore implementation. To define additional entity caches for more classes, add more <cache-mapping> elements to the file.

Example 1-2 Assigning Named Caches to a JPA Caching Scheme

<cache-config>
  <caching-scheme-mapping>
    <cache-mapping>
      <!-- Set the name of the cache to be the entity name.  -->
      <cache-name>Employee</cache-name>
      <!-- Configure this cache to use the following defined scheme. -->
      <scheme-name>jpa-distributed</scheme-name>
    </cache-mapping>
  </caching-scheme-mapping>
  <caching-schemes>
    <distributed-scheme>
      <scheme-name>jpa-distributed</scheme-name>
      <service-name>JpaDistributedCache</service-name>
      <backing-map-scheme>
        <read-write-backing-map-scheme>
          <internal-cache-scheme>
            <local-scheme/>
          </internal-cache-scheme>
          <!-- Define the cache scheme. -->
          <cachestore-scheme>
            <class-scheme>
              <class-name>
                com.oracle.coherence.jpa.JpaCacheStore
              </class-name>
              <init-params>

                <!-- This param is the entity name. -->
                <init-param>
                  <param-type>java.lang.String</param-type>
                  <param-value>{cache-name}</param-value>
                </init-param>

                <!-- This param is the fully qualified entity class. -->
                <init-param>
                  <param-type>java.lang.String</param-type>
                  <param-value>com.acme.{cache-name}</param-value>
                </init-param>

                <!-- This param should match the value of the -->
                <!-- persistence unit name in persistence.xml. -->
                <init-param>
                  <param-type>java.lang.String</param-type>
                  <param-value>EmpUnit</param-value>
                </init-param>
              </init-params>
            </class-scheme>
          </cachestore-scheme>
        </read-write-backing-map-scheme>
      </backing-map-scheme>
    </distributed-scheme>
  </caching-schemes>
</cache-config>

Configuring the Persistence Unit

When using a JPA cache store or loader implementation, configure the persistence unit to ensure that no changes are made to entities when they are inserted or updated. Any changes made to entities by the JPA provider are not reflected in the Coherence cache. This means that the entity in the cache will not match the database contents. In particular, entities should not use ID generation, for example, @GeneratedValue, to obtain an ID. IDs should be assigned in application code before an object is put into Coherence. The ID is typically the key under which the entity is stored in Coherence.

Optimistic locking (for example, @Version) should not be used because it might lead to the failure of a database transaction commit.

When using a JPA cache store or loader implementation, L2 (shared) caching should be disabled in your persistence unit. See the documentation for your provider. In EclipseLink, this can be specified on an individual entity with @Cache(shared=false) or as the default in the persistence.xml file with the following property:

<property name="eclipselink.cache.shared.default" value="false"/>

Preparing a Current JPA Integration

Align the persistence API, provider, cache-store semantics and application trust metadata.

Use the matching coherence-jpa module with Jakarta Persistence 3.2 APIs and a provider certified for your application/database runtime. Keep one compatible persistence API/provider set in the class loader. Do not package an older javax.persistence API next to a jakarta.persistence implementation.

• Map entities and assign identifiers before putting them into Coherence. Database/provider-generated changes are not automatically reflected in the cached object.
• Use resource-local persistence units for JpaCacheStore/JpaCacheLoader; these implementations do not support container-managed/JTA entity managers.
• Disable the provider shared second-level cache for this store/loader configuration to avoid an additional stale copy.
• Package the model classes, serializer/POF registrations and generated security metadata on storage members and adapters that consume them. Persistence annotations do not register types or executables with Coherence trust controls.
• Test load/store/erase, rollback and failure/retry semantics with the chosen write-through or write-behind configuration. Coherence cache mutation and a database transaction are not a general cross-system atomic transaction.

Complete the class/metadata workflow in Building Examples with Application Security Metadata and the database/cache consistency review in Configuring the Persistence Unit.