Oracle TopLink 11g Release 1 (11.1.1) enables you to scale out JPA applications using Oracle Coherence. TopLink Grid provides applications with a number of options on how they can scale, ranging from using Coherence as a distributed shared (L2) cache up to directing JP QL queries to Coherence for parallel execution across the grid to reduce database load. With TopLink Grid, you do not have to rewrite your applications to scale out. You can use your investment in JPA, and still take advantage of the scalability of Coherence.
TopLink Grid provides the following benefits:
Simple application configuration using annotations or XML configurations that align with standard JPA.
The ability to store complex object graphs with relationships in Coherence.
The ability to selectively choose which entities are stored in the grid and which are stored directly in the backing database.
Allows you to execute JP QL queries in the Grid or directly against the database.
Allows you to store entities with both eager and lazy relationships into Coherence.
This document describes how to:
Configure TopLink Grid to use the Coherence data grid as the primary data store for entities
Use Coherence as a distributed shared cache
Employ Coherence parallel processing to perform Java Persistence Query Language (JPQL) queries on cached entities
Use the cache store and cache loader interfaces, which have been optimized for EclipseLink JPA, in Coherence applications that run on the grid
This chapter contains the following sections:
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 special cache loader and cache store interfaces which have been implemented for JPA.
In this traditional Coherence approach, TopLink Grid provides the CacheLoader and CacheStore implementations in the oracle.eclipselink.coherence.standalone package that are optimized for EclipseLink JPA. This technique is described in the Integration Guide for Oracle Coherence.
You can build applications using JPA and transparently use 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. These implementations reside in the oracle.eclipselink.coherence.integrated package. See Chapter 2, "JPA on the Grid Configurations" for more information.
You can build applications with the EclipseLink Native Object Relational Mapping (ORM) framework to take advantage of extended capabilities such as advanced database-specific capabilities, and performance tuning and management options.
The Native ORM approach is very similar to JPA on the Grid, however, it does not use annotations to configure how the cache is used. Instead, this approach employs an amendment method that defines the appropriate cache behavior. See Chapter 3, "EclipseLink Native ORM Configurations" for more information.
When integrating JPA applications with the Coherence data grid, note the potential benefits and restrictions. You must understand how the grid works and how it relates to your JPA configurations to realize the full potential.
See the following sections for information about TopLink Grid configuration options:
By default, EclipseLink provides an EntityManagerFactory managed shared entity cache. This shared cache improves performance for multithreaded and Java EE server hosted applications running in a single JVM.
With TopLink Grid, you can replace the default EclipseLink shared (L2) cache with Oracle Coherence. This is known as Grid Cache configuration: the base configuration for TopLink Grid. This configuration applies the Coherence data grid to JPA applications that rely on database hosted data that cannot be entirely pre-loaded into a Coherence cache. You can define very large, shared grid caches that span cluster nodes. You do not have to add special configuration to ensure individual shared caches are coordinated. By defining a Grid Cache configuration for an entity in Coherence, all EntityManager.find() calls for that entity will result in a get call on the associated Coherence cache. If the Coherence cache does not contain the object, then the database is queried.
See "Grid Cache Configuration" for more information.
In addition to Grid Cache configuration, you can configure TopLink Grid to direct read queries to Coherence. By configuring a TopLink JPA cache loader, 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. By managing very large numbers of objects, Coherence increases the likelihood of a cache hit, because read operations in one cluster member immediately make the object available to other members.
While using Coherence to spread an entity cache across the grid is useful, support for nonprimary key queries is especially beneficial. When you configure an entity in a Grid Read configuration, all read operations 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. See "Grid Read Configuration" for more information.
Because filters apply only to objects in the Coherence cache, the configuration of a cache store or cache loader has no impact on ad hoc query processing. By default, queries are not executed against the database with this configuration. However, you can override this behavior by using the oracle.eclipselink.coherence.integrated.querying.IgnoreDefaultRedirector class to issue query hints. For example, the following hint directs the query to the database instead of to the Coherence cache:
query.setHint(QueryHints.QUERY_REDIRECTOR, new IgnoreDefaultRedirector());
For information about using EclipseLink JPA query hints, see the EclipseLink documentation at this URL:
Another key configuration option is specifying how to write entities to the database. You can configure EclipseLink to do either of the following:
Directly write entities to the database, then put them in Coherence (so that it reflects the database state). See "Writing Objects in Grid Cache Configuration" and "Writing Objects in Grid Read Configuration" for more information.
Put entities into Coherence, then have Coherence write to the database using a cache store.
The cache store method, also known as the Grid Entity configuration, lets you use the Coherence write-behind feature to enable asynchronous database write operations, which means 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 Java Transaction API (JTA) integration.
See "Grid Entity Configuration" for more information.