Oracle TopLink Grid: Using Coherence as a Shared L2 Cache

How-To Document

11 g (


May 2009

After reading this How-To document, you will be able to:

  • Understand the purpose of the TopLink Grid with Coherence as a Shared L2 Cache configuration.

  • Configure your TopLink JPA entity to direct all read queries to the database and place the results in the Coherence cache.

  • Configure your TopLink JPA entity to direct all write queries to the database, and then update the Coherence cache.

2 Introduction

The TopLink Grid Coherence Shared L2 Cache configuration uses Coherence as the TopLink L2 (Shared) 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 for reasons including: 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, etc.

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

2.1 Reading Objects

In the Coherence Shared L2 Cache configuration, all read queries are directed to the database except primary key queries, which are performed against 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 them immediately available to all members of the cluster which is valuable because, by default, TopLink leverages the L2 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 L2 cache. If the cache contains the entity then the entity is used and a new entity isn't built. This approach can greatly improve application performance, especially with a warmed cache, as it greatly reduces the cost of a query.

2.2 Writing Objects

In the Coherence Shared L2 Cache configuration, TopLink performs all database writes (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.

3 Examples

You can configure an entity with a Coherence L2 Cache with the CoherencInterceptor. This class intercepts all TopLink calls to the internal TopLink L2 cache and redirects them to Coherence.

import oracle.eclipselink.coherence.integrated.cache.CoherenceInterceptor;
import org.eclipse.persistence.annotations.Customizer;

@CacheInterceptor(value = CoherenceInterceptor.class)
public class Employee {

The following examples illustrate the ways to use the Coherence Shared L2 Cache configuration:

3.1 Querying Objects by ID

To get an entity from the Coherence cache with a specific ID (key), use: em.find(Entity.class, ID). This example will find the employee with a particular ID.

private Employee employeeFind(EntityManager em, int id) {
  Employee employee =  null;
    employee = em.find(Employee.class, id);
  return employee;}

For example, em.find(Employee.class, 8) will get the entity with key 8, from the Coherence Employee cache.

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 Coherence.

3.2 Querying Objects with Criteria

To get an entity that matches a specific selection criteria, use: em.createQuery("..."). This example will find the employee with a particular name:

private Employee employeeFind(EntityManager em, String name) {
  Employee employee = (Employee)em
  createQuery("select e from Employee e where = :name")
  setParameter("name", name)
return employee;

For example, em.createQuery("select e from Employee e where'John'") will execute a SELECT statement against the database to find employees with the name of John.

If the SELECT returns a database result, it's primary key is extracted to see if Coherence already holds the corresponding entity.

  • By default, if the entity is found in Coherence, the database result is discarded and the cached entity is used.

  • If Coherence does not contain the entity, then a new one is constructed from the database result and placed into Coherence.

3.3 Inserting Objects

To persist an entity into the Coherence cache, use: em.persist(Object). This example will add a new employee.

private void EmployeeAdd(EntityManager em, String name) {
  Employee employee = new Employee(name);

For example, calling the example method employeeAdd with the parameter John ( employeeAdd(em, "John")) will, at commit time, cause TopLink to execute an INSERT statement to add the entity John to the database.

If the database transaction is successful, the new entity will be placed in the Coherence Employee cache under its primary key.

3.4 Updating Objects

To update an entity and place the updated entity in the Coherence cache, use: em.merge(Object). This example will find an employee with a particular ID, then change the employee's name (error checking is omitted for brevity in this example).

private void employeeRename(EntityManager em, int id, String newName) {
  Employee employee = em.find(Employee.class, id);

For example, calling the example method employeeRename(em, 8, "John") will, cause TopLink to execute an UPDATE statement against the database for the entity with the ID of 8, changing the employee's name to John.

If the database transaction is successful, the entity will be placed into the Coherence cache under its primary key, replacing the old entity.

5 Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at .

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

TTY Access to Oracle Support Services

Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the United States of America 24 hours a day, 7 days a week. For TTY support, call 800.446.2398. Outside the United States, call +1.407.458.2479.

Oracle TopLink How-To Document, 11 g (

Copyright © 2007, 2008 Oracle. All rights reserved.

The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.