2 Integrating TopLink Grid and Oracle Coherence

Oracle TopLink Grid is a feature of Oracle TopLink that provides integration between the EclipseLink JPA and Coherence. TopLink Grid enables you to combine the simplicity of application development using the Java Persistence API (JPA) with the scalability and distributed processing power of Oracle Coherence Data Grid. Standard JPA applications interact directly with their primary data store, typically a relational database; however, with TopLink Grid you can store some or all of your domain model in the Coherence data grid.

2.1 Using TopLink Grid as the CacheStore for Coherence

TopLink Grid provides a default entity-based CacheStore implementation, EclipseLinkJPACacheStore, and a corresponding CacheLoader implementation, EclipseLinkJPACacheLoader in the oracle.eclipselink.coherence.standalone package. These are optimized implementations for use with EclipseLink JPA. The classes and their Javadoc can be found in the toplink-grid.jar file.

Note:

Before the Oracle Release 11gR1, the API for TopLink Grid/Coherence integration was shipped in a JAR named coherence-eclipselink.jar.

Table 2-1 TopLink Grid Classes for EclipseLink JPA

Class Name	Description
oracle.eclipselink.coherence.standalone.CacheStore	An optimized implementation of `CacheStore` for use with EclipseLink JPA
oracle.eclipselink.coherence.standalone.CacheLoader	An optimized implementation of `CacheLoader` for use with EclipseLink JPA

2.1.1 Configuring an EclipseLinkJPACacheStore

This section illustrates a simple EclipseLinkJPACacheStore constructor, which requires the name of the cache (which is the unqualified name of the entity) and the name of the persistence unit. It configures Toplink Grid using the default configuration path, which looks for the configuration files persistence.xml and orm.xml in the classpath. There is also the ability to pass in a resource name or file specification for the EclipseLink configuration file as the third <init-param> (set the <param-type> element to java.lang.String for a resource name and java.io.File for a file specification).

Example 2-1 illustrates a simple coherence-cache-config.xml file used to define a NamedCache named Publisher which caches instances of the entity (novels). To add additional entity caches, add additional <cache-mapping> elements.

Example 2-1 Sample coherence-cache-config.xml File for EclipseLink

<?xml version="1.0"?>
<!DOCTYPE cache-config SYSTEM "cache-config.dtd">
 
<cache-config>
  <caching-scheme-mapping>
    <cache-mapping>
      <cache-name>Publisher</cache-name>
      <scheme-name>distributed-eclipselink</scheme-name>
    </cache-mapping>
  </caching-scheme-mapping>

  <caching-schemes>
    <distributed-scheme>
      <scheme-name>distributed-eclipselink</scheme-name>
      <service-name>EclipseLinkJPA</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>
              oracle.eclipselink.coherence.standalone.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>novels</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.2 Using Coherence as the Toplink Cache

You can easily configure Toplink Grid to use Coherence as the primary data store, execute queries against the grid, and allow Coherence to manage the persistence of new and modified data. Coherence provides the layer between JPA and the datastore, where direct database calls can be off-loaded from every application instance. This makes it possible for clustered application deployments to scale beyond the bounds of normal database operations.

There are three typical TopLink Grid configurations that applications can use:

Coherence Shared L2 Cache—this configuration uses Coherence as the TopLink L2 (Shared) cache. This configuration applies Coherence data grid to JPA applications that rely on database hosted data that cannot be entirely pre-loaded into a Coherence cache. Some reasons why it might not be able to pre-loaded include extremely complex queries that exceed the feature set of Coherence Filters, third party database updates that create stale caches, reliance on native SQL queries, stored procedures or triggers, and so on.

In this configuration, you can scale TopLink up into large clusters while avoiding the requirement to coordinate local L2 caches. Updates made to entities are available in all Coherence cluster members immediately, upon a transaction commit.
Coherence Read—this configuration is optimal for entities that require fast access to large amounts of (fairly stable) data and must write changes synchronously to the database. In these entities, cache warming would be used to populate the Coherence cache, but individual queries could be directed to the database if necessary.
Coherence Read/Write—this configuration is optimal for applications that require fast access to large amounts of (fairly stable) data and that perform relatively few updates. This configuration can be combined with a Coherence CacheStore using write-behind to improve application response time by performing database updates asynchronously.

See the Oracle TopLink Grid page on the Oracle Technology Network for more information on configuring Coherence for Toplink Grid.

2.2.1 Coherence and TopLink Grid API and Files

The API for TopLink Grid/Coherence integration are shipped in the toplink-grid.jar. The integration also uses the standard JPA run-time configuration file persistence.xml and the JPA mapping file orm.xml (the default name). The Coherence cache configuration file coherence-cache-config.xml (the default name) must be specified to override the default Coherence settings and define the CacheStore caching scheme.

Table 2-2 lists several noteworthy EclipseLink classes which are typically used in a TopLink Grid/Coherence integration. The classes and their Javadoc can be found in the toplink-grid.jar file.

Table 2-2 EclipseLink Classes Typically used in a Toplink Grid/Coherence Integration

Class Name	Description
oracle.eclipseLink.coherence.integrated.EclipseLinkJPACacheLoader	Provides JPA-aware versions of the Coherence `CacheLoader`.
oracle.eclipseLink.coherence.integrated.EclipseLinkJPACacheStore	Provides JPA-aware versions of the Coherence `CacheStore`.
oracle.eclipselink.coherence.integrated.cache.CoherenceInterceptor	Intercepts all TopLink calls to the internal TopLink L2 cache and redirects them to Coherence.
oracle.eclipselink.coherence.integrated.config.CoherenceReadCustomizer	Used to program a Coherence read configuration.
oracle.eclipselink.coherence.integrated.config.CoherenceReadWriteCustomizer	Used to program a Coherence read/write configuration.
oracle.eclipselink.coherence.integrated.querying.IgnoreDefaultRedirector	Allows queries to bypass the Coherence cache and be directly sent to the database.