2 JPA on the Grid Configurations

This chapter contains the following sections:

2.1 Understanding JPA on the Grid

The expression JPA on the Grid refers to using JPA and the power of the data grid to build applications with improved scalability and performance. In the JPA on the Grid approach, TopLink Grid provides a set of cache and query configuration options that allow you to control how EclipseLink JPA uses Coherence.

You can configure Coherence as a distributed shared (L2) cache or use Coherence as the primary data store. You can also configure entities to execute queries in the Coherence data grid instead of the database. This allows clustered application deployments to scale beyond database-bound operations.

Figure 2-1 illustrates the relationship between an application, TopLink, Coherence, and the database.

Figure 2-1 JPA on the Grid Approach

JPA on the Grid approach.
Description of "Figure 2-1 JPA on the Grid Approach"

2.2 JPA on the Grid API

The API used by JPA on the Grid configurations are shipped in the toplink-grid.jar file. Table 2-1 lists some of the key classes in the oracle.eclipselink.coherence.integrated package that are used in JPA on the Grid configurations.

Table 2-1 TopLink Grid Classes to Build JPA on the Grid Applications

Class Name Description

oracle.eclipseLink.coherence.integrated.EclipseLinkJPACacheLoader

Provides JPA-aware versions of the Coherence CacheLoader interface.

oracle.eclipseLink.coherence.integrated.EclipseLinkJPACacheStore

Provides JPA-aware versions of the Coherence CacheStore interface.

oracle.eclipselink.coherence.integrated.config.CoherenceReadCustomizer

Enables a Coherence read configuration.

oracle.eclipselink.coherence.integrated.config.CoherenceReadWriteCustomizer

Enables a Coherence read/write configuration.

oracle.eclipselink.coherence.integrated.config.GridCacheCustomizer

Enables cache instances to be cached in Coherence instead of in the internal EclipseLink shared cache. All calls to the internal TopLink L2 cache are redirected to Coherence.

oracle.eclipselink.coherence.integrated.querying.IgnoreDefaultRedirector

Allows queries to bypass the Coherence cache and be sent directly to the database.


The configuration also uses the standard JPA run-time configuration file persistence.xml and the JPA mapping file orm.xml. You must also use the Coherence cache configuration file coherence-cache-config.xml to override the default Coherence settings and define the cache store caching scheme.

2.3 Grid Cache Configuration

The Grid Cache configuration can be considered as the base configuration for TopLink Grid. In this configuration, Coherence acts as the TopLink shared (L2) cache. This brings the power of the Coherence data grid to JPA applications that rely on database-hosted data that cannot be entirely preloaded into a Coherence cache. Some reasons why the data might not be able to be preloaded include extremely complex queries that exceed the abilities of Coherence Filters, third-party database updates that create stale caches, and reliance on native SQL queries, stored procedures, or triggers.

By using Coherence as the TopLink Grid cache, you can scale TopLink up into large clusters while avoiding the need to coordinate local shared caches. Updates made to entities are available in all Coherence cluster members immediately, upon committing a transaction.

In general, read and write operations in a Grid Cache configuration have the following characteristics:

  • A primary key query will attempt to get entities first from the Coherence cache. If the attempt is unsuccessful, the database will be queried and the Coherence cache will be updated with the query results. See the following section, "Reading Objects in Grid Cache Configuration".

  • A nonprimary key query will be executed against the database and the results will be checked against the Coherence cache. This is to avoid the negative performance impact of constructing entities that are already cached. Newly queried entities are put into the Coherence cache.

  • A write operation will update the database and, if successfully committed, will put updated entities into the Coherence cache. See "Writing Objects in Grid Cache Configuration".

See "Grid Cache Configuration Examples" for detailed examples.

To use Coherence as a distributed cache for an entity, you must enable shared caching in EclipseLink. Shared caching is enabled by default for all entities, but the default can be explicitly set to true or false by setting the eclipselink.cache.shared.default property in the persistence.xml file. Specific entities can override the default using the @Cache annotation or by specifying the corresponding XML <cache> element in the eclipselink-orm.xml file. For more information, see:

http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_(ELUG)#How_to_Use_the_.40Cache_Annotation

2.3.1 Reading Objects in Grid Cache Configuration

In the Grid Cache configuration, all read queries are directed to the database except primary key queries, which are directed to the Coherence cache first. Any cache misses will result in a database query.

All entities queried from the database are placed in the Coherence cache. This makes the entities immediately available to all members of the cluster. This is valuable because, by default, TopLink uses the cache to avoid constructing new entities from database results.

For each row resulting from a query, TopLink uses the primary key of the result row to query the corresponding entity from the cache. If the cache contains the entity then the entity is used and a new entity is not built. This approach can greatly improve application performance, especially with a warmed cache, because it reduces the cost of a query by eliminating the cost associated with object building.

Figure 2-2 illustrates the path of a read query in the Grid Cache configuration:

  1. The application issues a find query.

  2. For primary key queries, TopLink queries the Coherence cache first.

  3. If the object does not exist in the Coherence cache, TopLink queries the database.

    For all read queries except primary key queries, TopLink queries the database first.

  4. Read objects are put into the Coherence cache.

Figure 2-2 Reading Objects in Grid Cache Configuration

Reading objects.
Description of "Figure 2-2 Reading Objects in Grid Cache Configuration"

2.3.2 Writing Objects in Grid Cache Configuration

In the Grid Cache configuration, TopLink performs all database write operations (insert, update, delete). The Coherence cache is then updated to reflect the changes made to the database. TopLink offers a number of performance features when writing large amounts of data including batch writing, parameter binding, stored procedure support, and statement ordering to ensure that database constraints are satisfied.

Figure 2-3 illustrates the path for writing and persisting objects in the Grid Cache configuration:

  1. The application issues a commit query.

  2. TopLink updates the database.

  3. After a successful transaction, TopLink updates the Coherence cache.

Figure 2-3 Writing and Persisting Objects in grid Cache Configuration

Writing and Persisting Objects
Description of "Figure 2-3 Writing and Persisting Objects in grid Cache Configuration"

2.3.3 Grid Cache Configuration Examples

You can obtain the code in these examples at the following URL:

https://toplinkgrid-examples.samplecode.oracle.com/source/browse/*checkout*/toplinkgrid-examples/trunk/downloads/TLG%20JPA%20Example-Grid%20Cache.zip

2.3.3.1 Configuring the Cache for the Grid Cache Configuration

The cache configuration file (coherence-cache-config.xml) in Example 2-1 defines the cache and configures a wrapper serializer to support serialization of relationships.

Example 2-1 Configuring the Cache in Grid Cache Configuration

<cache-config>
  <caching-scheme-mapping>
    <cache-mapping>
      <cache-name>*</cache-name>
      <scheme-name>eclipselink-distributed</scheme-name>
    </cache-mapping>
  </caching-scheme-mapping>
  <caching-schemes>
    <distributed-scheme>
      <scheme-name>eclipselink-distributed</scheme-name>
      <service-name>EclipseLinkJPA</service-name>
      <!--
        Configure a wrapper serializer to support serialization of relationships.
      -->
      <serializer>
        <class-name>oracle.eclipselink.coherence.integrated.cache.WrapperSerializer</class-name>
      </serializer>
      <backing-map-scheme>
      <!-- 
        Backing map scheme with no eviction policy. 
      -->
        <local-scheme>
          <scheme-name>unlimited-backing-map</scheme-name>
        </local-scheme>
      </backing-map-scheme>
      </backing-map-scheme>
      <autostart>true</autostart>
    </distributed-scheme>
  </caching-schemes></cache-config>

2.3.3.2 Configuring an Entity for the Grid Cache Configuration

To configure an entity to use Grid Cache, use the @Customizer annotation and the GridCacheCustomizer class as shown in Example 2-2. This class intercepts all TopLink calls to the internal TopLink Grid cache and redirects them to the Coherence cache.

Example 2-2 Configuring the Entity in Grid Cache Configuration

import oracle.eclipselink.coherence.integrated.config.GridCacheCustomizer;
import org.eclipse.persistence.annotations.Customizer;

@Entity
@Customizer(GridCacheCustomizer.class)
public class Employee {
...

2.3.3.3 Inserting Objects for the Grid Cache Configuration

In Example 2-3, TopLink performs the insert to create a new employee. Entities are persisted through the EntityManager and placed in the database. After a successful transaction, the Coherence cache is updated.

Example 2-3 Inserting Objects in Grid Cache Configuration

EntityManagerFactory emf = Persistence.createEntityManagerFactory("employee-pu");

// Create an employee with an address and telephone number.
EntityManager em = emf.createEntityManager();
em.getTransaction().begin();
Employee employee = createEmployee();
em.persist(employee);
em.getTransaction().commit();           
em.close();

2.3.3.4 Querying Objects for the Grid Cache Configuration

In Example 2-4, the named JPQL query is directed to the database. Query results are resolved against the Coherence cache to avoid the cost of building objects that have previously been cached.

Example 2-4 Querying Objects in Grid Cache Configuration

EntityManagerFactory emf = Persistence.createEntityManagerFactory("employee-pu");

EntityManager em = emf.createEntityManager();
List<Employee> employees = em.createQuery("select e from Employee e where e.lastName = :lastName").setParameter("lastName", "Smith").getResultList();

for (Employee employee : employees) {
   System.err.println(employee);
   for (PhoneNumber phone : employee.getPhoneNumbers()) {
      System.err.println("\t" + phone);
   }
}

emf.close();

2.4 Grid Read Configuration

Use the Grid Read configuration for entities that require fast access to large amounts of (fairly stable) data and write changes synchronously to the database. For these entities, cache warming would typically be used to populate the Coherence cache, but individual queries could be directed to the database if necessary.

In general, read and write operations in a Grid Read configuration have the following characteristics:

See "Grid Read Configuration Examples" for detailed examples.

2.4.1 Reading Objects in Grid Read Configuration

In the Grid Read configuration, all primary key and non-primary key queries are directed to the Coherence cache. To reduce query processing time, TopLink Grid supports parallel processing of queries across the data grid. Coherence contains data already in object form, avoiding the performance impact of database communication and object construction.

With the Grid Read configuration, if Coherence does not contain the entity requested by the find(...) method, then null is returned. However, if a cache loader is configured for the entity's cache, Coherence will attempt to load the object from the database. This is true only for primary key queries.

Configuring a cache loader has no impact on JPQL queries translated to Coherence filters. When searching with a filter, Coherence will operate only on the set of entities in the caches; the database will not be queried. However, it is possible to direct a query, on a query-by-query basis, to the database instead of to Coherence by using the oracle.eclipselink.coherence.integrated.querying.IgnoreDefaultRedirector class, as shown in following example:

query.setHint(QueryHints.QUERY_REDIRECTOR, new IgnoreDefaultRedirector());

Any objects retrieved by a database query will be added to the Coherence cache so that they are available for subsequent queries. Because this configuration resolves all queries for an entity through Coherence by default, the Coherence cache should be warmed with all of the data that is to be queried.

In the Grid Read configuration, projection queries (reports) that extract data from a single entity type will also be directed to Coherence. For example, the following JPQL query will return the first and last names of all employees contained in the Coherence cache.

select e.firstName, e.lastName from Employee e

This type of query is useful when the entire entity is not required, for example when populating a drop-down list in a user interface.

A cache store is not compatible with the Grid Read configuration because the EclipseLink JPA will perform all database updates and then propagate the updated objects into Coherence. If you use a cache store, Coherence will attempt to write the objects again.

For complete information on using EclipseLink JPA query hints, see the EclipseLink documentation at this URL:

http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_(ELUG)#How_to_Use_EclipseLink_JPA_Query_Hints

Figure 2-4 illustrates the path for a query in the Grid Read configuration:

  1. The application issues a JPQL query.

  2. TopLink executes a Filter on the Coherence cache.

  3. TopLink returns results from the Coherence cache only; the database is not queried.

Figure 2-4 Reading Objects with a Query

Reading Objects
Description of "Figure 2-4 Reading Objects with a Query"

2.4.2 Writing Objects in Grid Read Configuration

In the Grid Read configuration, TopLink performs all database write operations (insert, update, delete) directly. The Coherence caches are then updated to reflect the changes made to the database. TopLink offers a number of performance features when writing large amounts of data. These include batch writing, parameter binding, stored procedure support, and statement ordering to ensure that database constraints are satisfied.

This approach offers the best possibilities: database updates are performed efficiently and queries continue to be executed in parallel across the Coherence data grid, with the option of directing individual queries to the database.

Figure 2-5 illustrates the path for writing and persisting objects in the Grid Read configuration:

  1. The application issues a commit query.

  2. TopLink updates the database.

  3. After a successful transaction, TopLink updates the Coherence cache.

Figure 2-5 Writing and Persisting Objects in Grid Read Configuration

Writing and Persisting Objects
Description of "Figure 2-5 Writing and Persisting Objects in Grid Read Configuration"

2.4.3 Grid Read Configuration Examples

You can obtain the code in these examples at the following URL:

https://toplinkgrid-examples.samplecode.oracle.com/source/browse/*checkout*/toplinkgrid-examples/trunk/downloads/TLG%20JPA%20Example-Grid%20Read.zip

2.4.3.1 Configuring the Cache in Grid Read Configuration

The cache configuration file (coherence-cache-config.xml) in Example 2-5 defines the cache and configures a wrapper serializer to support serialization of relationships. The oracle.eclipselink.coherence.integrated.EclipseLinkJPACacheLoader class defines the cache store scheme.

Example 2-5 Configuring the Cache in Grid Read Configuration

<cache-config>
  <caching-scheme-mapping>
    <cache-mapping>
      <cache-name>*</cache-name>
      <scheme-name>eclipselink-distributed-readonly</scheme-name>
    </cache-mapping>
  </caching-scheme-mapping>
  <caching-schemes>
    <distributed-scheme>
      <scheme-name>eclipselink-distributed-readonly</scheme-name>
      <service-name>EclipseLinkJPAReadOnly</service-name>
      <!--
        Configure a wrapper serializer to support serialization of relationships.
      -->
      <serializer>
        <class-name>oracle.eclipselink.coherence.integrated.cache.WrapperSerializer</class-name>
      </serializer>
      <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>oracle.eclipselink.coherence.integrated.EclipseLinkJPACacheLoader</class-name>
              <init-params>
                <param-type>java.lang.String</param-type>
                <param-value>{cache-name}</param-value>
              </init-param>
                <init-param>
                  <param-type>java.lang.String</param-type>
                  <param-value>employee-pu</param-value>
                </init-param>
              </init-params>
            </class-scheme>
          </cachestore-scheme>
          <read-only>true</readonly>
        </read-write-backing-map-scheme>
      </backing-map-scheme>
      <autostart>true</autostart>
    </distributed-scheme>
  </caching-schemes></cache-config>

2.4.3.2 Reading Objects for the Grid Read Configuration

To configure an entity to read through a Coherence cache, use the @Customizer annotation and the CoherenceReadCustomizer class as shown in Example 2-6:

Example 2-6 Configuring the Entity in Grid Read Configuration

import oracle.eclipselink.coherence.integrated.config.CoherenceReadCustomizer;
import org.eclipse.persistence.annotations.Customizer;

@Entity
@Customizer(CoherenceReadCustomizer.class)
public class Employee {
...
}

2.4.3.3 Inserting Objects for the Grid Read Configuration

In Example 2-7, TopLink performs an insert to create a new employee. If the transaction is successful, the new object is placed into the Coherence cache under its primary key.

Example 2-7 Inserting Objects in Grid Read Configuration

EntityManagerFactory emf = Persistence.createEntityManagerFactory("employee-pu");
// Create an employee with an address and telephone number
EntityManager em = emf.createEntityManager();
em.getTransaction().begin();
Employee employee = createEmployee();
em.persist(employee);
em.getTransaction().commit();
em.close();

emf.close();

2.4.3.4 Querying Objects for the Grid Read Configuration

When finding an employee, the read query is directed to the Coherence cache. The JPQL query is translated to Coherence filters, as shown in Example 2-8.

Example 2-8 Querying Objects in Grid Read Configuration

EntityManagerFactory emf = Persistence.createEntityManagerFactory("employee-pu");
EntityManager em = emf.createEntityManager();
List<Employee> employees = em.createQuery("select e from Employee e where e.lastName = :lastName").setParameter("lastName", "Smith").getResultList();
  for (Employee employee : employees) {
    System.err.println(employee);
      for (PhoneNumber phone : employee.getPhoneNumbers()) {
        System.err.println("\t" + phone);
      }
  }emf.close();

To retrieve an object from the Coherence cache with a specific ID (key), use the em.find(Entity.class, ID) method. You can also configure a Coherence cache loader to query the database to find the object, if the cache does not contain the object with the specified ID.

2.5 Grid Entity Configuration

The Grid Entity configuration should be used by applications that require fast access to large amounts of (fairly stable) data, but perform relatively few updates. This configuration can be combined with a Coherence cache store using write-behind to improve application response time by performing database updates asynchronously.

In general, read and write operations in a Grid Entity configuration have the following characteristics:

See "Grid Entity Configuration Examples" for detailed examples.

2.5.1 Reading Objects in Grid Entity Configuration

In the Grid Entity configuration, querying objects is identical to the Grid Read configuration. See "Reading Objects in Grid Cache Configuration" for more information.

2.5.2 Writing Objects in Grid Entity Configuration

In the Grid Entity configuration, all objects that are persisted, updated, or merged through an EntityManager instance will be put in the appropriate Coherence cache. To persist objects in a Coherence cache to the database, an EclipseLink JPA cache store (oracle.eclipselink.coherence.integrated.EclipseLinkJPACacheStore) must be configured for each cache.

You can also configure the cache store to use write-behind to asynchronously batch-write updated objects. See Coherence Developer's Guide for more information.

Figure 2-6 illustrates the path for writing and persisting objects in the Grid Entity configuration.

  1. The application issues a commit call.

  2. TopLink directs all queries to update the Coherence cache.

  3. By configuring a Coherence cache store (optional), TopLink will also update the database.

Figure 2-6 Writing and Persisting Objects in Grid Entity Configuration

Writing and persisting objects.
Description of "Figure 2-6 Writing and Persisting Objects in Grid Entity Configuration"

2.5.3 Limitations on Writing Objects in Grid Entity Configuration

When using a cache store, Coherence assumes that all write operations succeed and will not inform TopLink of a failure. This could result in the Coherence cache differing from the database. You cannot use optimistic locking to protect against data corruption that may occur if the database is concurrently modified by Coherence and a third-party application.

Because the order in which Coherence cache members write updates to the database is unpredictable, referential integrity cannot be guaranteed. Referential integrity constraints must be removed from the database. If they are not, write operations could fail with the following error:

org.eclipse.persistence.exceptions.DatabaseException
Internal Exception: java.sql.BatchUpdateException: ORA-02292: integrity constraint violated - child record found
Error Code: 2292

2.5.4 Grid Entity Configuration Examples

You can obtain the code in these examples at the following URL:

https://toplinkgrid-examples.samplecode.oracle.com/source/browse/*checkout*/toplinkgrid-examples/trunk/downloads/TLG%20JPA%20Example-Grid%20Entity.zip

2.5.4.1 Configuring the Cache for the Grid Entity Configuration

The cache configuration file (coherence-cache-config.xml) in Example 2-9 configures a wrapper serializer to support serialization of relationships. The oracle.eclipselink.coherence.integrated.EclipseLinkJPACacheStore class defines the cache store scheme.

Example 2-9 Configuring the Cache in Grid Entity Configuration

<cache-config>
  <caching-scheme-mapping>
    <cache-mapping>
      <cache-name>*</cache-name>
      <scheme-name>eclipselink-distributed-readwrite</scheme-name>
    </cache-mapping>
  </caching-scheme-mapping>
  <caching-schemes>
    <distributed-scheme>
      <scheme-name>eclipselink-distributed-readwrite</scheme-name>
      <service-name>EclipseLinkJPAReadWrite</service-name>
      <!--
        Configure a wrapper serializer to support serialization of relationships.
      -->
      <serializer>
        <class-name>oracle.eclipselink.coherence.integrated.cache.WrapperSerializer</class-name>
      </serializer>
      <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>oracle.eclipselink.coherence.integrated.EclipseLinkJPACacheStore</class-name>
                <init-params>
                  <init-param>
                    <param-type>java.lang.String</param-type>
                    <param-value>{cache-name}</param-value>
                  </init-param>
                  <init-param>
                    <param-type>java.lang.String</param-type>
                    <param-value>employee-pu</param-value>
                  </init-param>
                </init-params>
              </class-scheme>
            </cachestore-scheme>
        </read-write-backing-map-scheme>
      </backing-map-scheme>
      <autostart>true</autostart>
    </distributed-scheme>
  </caching-schemes>
</cache-config>

2.5.4.2 Configuring an Entity for the Grid Entity Configuration

To configure an entity to read through Coherence, use the @Customizer annotation and the CoherenceReadWriteCustomizer class as shown Example 2-10:

Example 2-10 Configuring an Entity in Grid Entity Configuration

import oracle.eclipselink.coherence.integrated.config.CoherenceReadWriteCustomizer;
import org.eclipse.persistence.annotations.Customizer;

@Entity
@Customizer(CoherenceReadWriteCustomizer.class)
public class Employee {
...
}

2.5.4.3 Persisting Objects for the Grid Entity Configuration

In Example 2-11, TopLink performs the insert to create a new employee. Entities persist through the EntityManager instance and are placed in the appropriate Coherence cache.

Example 2-11 Persisting Objects in Grid Entity Configuration

EntityManagerFactory emf = Persistence.createEntityManagerFactory("employee-pu");

// Create an employee with an address and telephone number.
EntityManager em = emf.createEntityManager();
em.getTransaction().begin();
Employee employee = createEmployee();
em.persist(employee);
em.getTransaction().commit();           
em.close();

2.5.4.4 Querying Objects for the Grid Entity Configuration

When finding an employee, the read query is directed to the Coherence cache, as shown in Example 2-12.

Example 2-12 Querying Objects in Grid Entity Configuration

EntityManagerFactory emf = Persistence.createEntityManagerFactory("employee-pu");

EntityManager em = emf.createEntityManager();
List<Employee> employees = em.createQuery("select e from Employee e where e.lastName = :lastName").setParameter("lastName", "Smith").getResultList();

for (Employee employee : employees) {
   System.err.println(employee);
   for (PhoneNumber phone : employee.getPhoneNumbers()) {
      System.err.println("\t" + phone);
   }
}

emf.close();

To get an object from the Coherence cache with a specific ID (key), use the em.find(Entity.class, ID) method. You can also configure a Coherence cache store to query the database to find the object, if the cache does not contain the object with the specified ID.

2.6 Handling Grid Read and Grid Entity Failovers

In the Grid Read and Grid Entity configurations, TopLink Grid will attempt to translate JPQL queries into Coherence Filters and execute the query in the grid. However some queries cannot be translated into filters. When TopLink Grid encounters such a query, it automatically fails over to the database to execute the query. In TopLink, you can specify a user-defined translation failure delegate object that will be called if the JPQL-to-filter translation fails. You configure the translation failure delegate by declaring the eclipselink.coherence.query.translation-failure-delegate persistence unit property. For example:

<property name="eclipselink.coherence.query.translation-failure-delegate" value="org.example.ExceptionFailoverPolicy"/>

A translation failure delegate must implement oracle.eclipselink.coherence.integrated.querying.TranslationFailureDelegate class which defines the single method translationFailed(DatabaseQuery query, Record arguments, Session session).

2.7 Wrapping and Unwrapping Entity Relationships

When storing entities with relationships in the Coherence cache, TopLink Grid generates a wrapper class that maintains the relationship information. In this way, when the object is read from the Coherence cache (eager or lazy), the relationships can be resolved.

If you read entities directly from the Coherence cache using the Coherence API, the wrappers are not automatically removed. You can configure automatic unwrapping programatically by calling the setNotEclipseLink(true) method on the serializer, as shown in Example 2-13. You can also set the system property as eclipselink.coherence.not-eclipselink to automatically unwrap an entity.

When configured properly, a cache get operation will return the unwrapped entity.

Example 2-13 Unwrapping an Entity

WrapperSerializer wrapperSerializer = (WrapperSerializer)myCache.getCacheService().getSerializer();
wrapperSerializer.setNotEclipseLink(true); // So the Serializer will unwrap an Entity when clients use a get() call from the cache.

2.8 Working with Queries

This section includes information on the following topics:

2.8.1 Querying Objects by ID

To get an entity from the Coherence cache with a specific ID (key), use the em.find(Entity.class, ID) method. For example, the following code will get the entity with key 8, from the Coherence Employee cache.

em.find(Employee.class, 8) 

If the entity is not found in the Coherence cache, TopLink executes a SELECT statement against the database. If a result is found, then the entity is constructed and placed into the Coherence cache. The query's specific behavior will depend on your Coherence cache configuration:

  • calling the find method with a Grid Cache Configuration performs a SELECT statement against the database on a cache miss and then updates the cache.

  • calling the find method with a Grid Read Configuration or a Grid Entity Configuration performs a get operation on the Coherence cache. A cache miss results in a SELECT statement against the database by using a CacheLoader instance, if it is configured.

2.8.2 Querying Objects with Criteria

To retrieve an entity that matches a specific selection criterion, use the em.createQuery("...") method. The query's specific behavior will depend on your Coherence cache configuration:

  • For the Grid Cache Configuration, the query will always execute a SELECT statement against the database. For example, the following code will execute a SELECT statement to find employees named John.

    em.createQuery("select e from Employee e where e.name='John'")
    
  • For the Grid Read Configuration and Grid Entity Configuration, the query will be executed against the Coherence cache. If the cache does not contain any entities that match the selection criteria, then nothing will be returned. This is an example of why the cache should be warmed before performing the query.

  • For the cache store and cache loader, queries are performed only on primary keys

2.8.3 Using Indexes in Queries

Indexes allow values (or attributes of those values) and corresponding keys to be correlated within a cache to improve query performance. TopLink Grid allows you to declare indexes with the @Property annotation. The IntegrationProperties class provides the INDEXED property.

In Example 2-14, the @Property annotation declares that the name attribute is to be indexed. TopLink Grid will define an index for that attribute in the Publisher cache.

Example 2-14 Exposing a Coherence Query Index to TopLink Grid

import static oracle.eclipselink.coherence.IntegrationProperties.INDEXED;
import oracle.eclipselink.coherence.integrated.config.CoherenceReadCustomizer;
 
@Customizer(CoherenceReadCustomizer.class)
public class Publisher implements Serializable {
...
    @Property(name=INDEXED, value="true")
    private String name;
 ...

With an index in place, you can issue a JPQL query, such as the following, to return all the Publishers in the cache with a name beginning with S.

SELECT Publisher p WHERE p.name like 'S%' 

Internally, Coherence will process the query by consulting the name index to find matches rather than by deserializing and examining every Publisher object stored in the grid. By avoiding deserialization, you achieve a significant positive improvement on query execution time, eliminate garbage collection of the temporarily deserialized objects, and reduce CPU usage.

2.8.4 Limitations on Queries

The following are limitations on querying Coherence caches:

  • Because the Coherence Filter framework is limited to a single cache, JPQL join queries cannot be translated to Filters. All join queries will execute on the database.

  • This release of TopLink Grid does not provide support for JPQL bulk updates and deletions.