Understanding the TopLink Grid Integration

TopLink Grid integrates the TopLink JPA implementation (EclipseLink) with Oracle Coherence and provides two development approaches:

  • You can use the Coherence API with caches backed by TopLink Grid to access relational data with JPA CacheLoader and CacheStore implementations. In this "traditional" Coherence approach, TopLink Grid provides CacheLoader and CacheStore implementations that are optimized for EclipseLink JPA.

    Figure 1 "Traditional" Coherence Approach

    Traditional Coherence approach.
    Description of "Figure 1 "Traditional" Coherence Approach"

    Refer to ""Traditional Coherence" Configuration" and the Coherence Integration Guide for details on this approach.

  • You can also build applications using JPA and transparently leverage the power of the data grid for improved scalability and performance. In this "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.

    Figure 2 "JPA on the Grid" Approach

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

    You can configure Coherence as a distributed shared 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.

    Refer to ""JPA on the Grid" Configurations" and the Coherence Integration Guide for details on this approach.

When integrating JPA applications with the Coherence Data Grid, you should be aware of potential benefits and restrictions. You must understand how the grid works and how it relates to your JPA configurations in order to realize the full potential.

This section includes information on the following configuration options:

Entity Caching

By default, EclipseLink provides an EntityManagerFactory managed shared Entity cache. This shared cache improves performance for multi-threaded and Java EE server hosted applications running in a single JVM.

With TopLink Grid, you can replace the default EclipseLink Shared (L2) cache with Coherence. This provides support for very large shared grid caches that span cluster nodes, and removes the need for additional configuration to ensure individual shared caches are coordinated. By configuring an Entity as Grid cached in Coherence, all EntityManager.find() calls for that Entity will result in a get on the associated Coherence cache. If Coherence doesn't contain the object the database is queried.

See "Grid Cache" for more information.

Reading and Querying

In addition to Grid cache configuration, you can configure TopLink Grid to direct read queries to Coherence. By configuring a TopLink JPA CacheLoader, even when there is no cache hit, the object can be read from the database and then placed in the cache, thereby making it available for subsequent queries. Coherence's ability to manage very large numbers of objects increases the likelihood of a cache hit as reads in one cluster member become immediately available to others.

While using Coherence to spread an Entity Grid cache across the grid is useful, support for non-primary key queries is especially beneficial. When you configure an Entity as "Grid Read" all reads are directed to Coherence. JPQL queries are automatically translated into Coherence filters and objects that match the filter are retrieved from the grid. Coherence executes all filters in parallel on each member of a cluster. This results in significantly faster processing for a query, compared to if all the objects resided in a single member.

Because filters only apply to objects in the Coherence cache, the configuration of a CacheStore or CacheLoader has no impact on ad-hoc query processing. By default, with this configuration queries are not executed against the database. However, you can override this behavior and with query hints by using the oracle.eclipselink.coherence.integrated.querying.IgnoreDefaultRedirector class as shown in the following example:

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

This directs the query to the database instead of the Coherence cache.

For complete information on using EclipseLink JPA query hints, refer to the EclipseLink documentation.


Another key configuration option is specifying how to write Entities to the database. You can configure EclipseLink to:

  • Directly write Entities to the database, then put them in Coherence (so that it reflects the database state)


  • Put entities into Coherence, then have Coherence write to the database using a CacheStore.

The CacheStore method supports the Coherence write-behind feature to enable asynchronous database writes. By using this applications do not have to wait for the database to return in order to proceed.

However, this configuration contains some restrictions, such as the inability to use JTA integration or other EclipseLink performance features (including batch writing, parameter binding, stored procedures, and statement ordering).