1 Introduction to Toplink Grid with Oracle Coherence

1.1 Understanding 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 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:

• Entity Caching

• Reading and Querying Coherence Caches

• Writing Entities to the Database

1.2 Entity Caching

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.

1.3 Reading and Querying Coherence Caches

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:

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

1.4 Writing Entities to the Database

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.