Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Caching/DatabaseEvents"

(Database Event Driven Cache Invalidation)
(Oracle DCN/QCN)
Line 35: Line 35:
 
The Oracle database released a Database Change Notification (DCN) feature in the 10.2 release.  DCN allows for database events to be raised when the rows in a table are modified.  The JDBC API for DCN was not complete until 11.2, so 11.2 is required for EclipseLink's integration.  DCN is also now referred to as QCN (Query Change Notification).
 
The Oracle database released a Database Change Notification (DCN) feature in the 10.2 release.  DCN allows for database events to be raised when the rows in a table are modified.  The JDBC API for DCN was not complete until 11.2, so 11.2 is required for EclipseLink's integration.  DCN is also now referred to as QCN (Query Change Notification).
  
EclipseLink DCN support is enabled through the <tt>OracleChangeNotificationListener</tt> listener which integrates with Oracle JDBC to received database change events.  By default all tables in the persistence unit are registered for change notification, but this can be configured using the <tt>databaseChangeNotificationType<tt> attribute of the <tt>@Cache</tt> annotation to selectively disable change notification for certain classes.
+
EclipseLink DCN support is enabled through the <tt>OracleChangeNotificationListener</tt> listener which integrates with Oracle JDBC to received database change events.  By default all tables in the persistence unit are registered for change notification, but this can be configured using the <tt>databaseChangeNotificationType</tt> attribute of the <tt>@Cache</tt> annotation to selectively disable change notification for certain classes.
  
 
Oracle DCN uses the ROWID to inform of row level changes.  This requires EclipseLink to include the ROWID is all queries for a DCN enabled class, as well as after an insert, EclipseLink will require to select the object's ROWID.  EclipseLink must maintain a cache index on the ROWID, in addition to the object's Id.  EclipseLink will also selects the database transaction id once each transaction to avoid invalidating the cache on the server that is processing the transaction.
 
Oracle DCN uses the ROWID to inform of row level changes.  This requires EclipseLink to include the ROWID is all queries for a DCN enabled class, as well as after an insert, EclipseLink will require to select the object's ROWID.  EclipseLink must maintain a cache index on the ROWID, in addition to the object's Id.  EclipseLink will also selects the database transaction id once each transaction to avoid invalidating the cache on the server that is processing the transaction.

Revision as of 14:51, 23 May 2012

EclipseLink JPA

Database Event Driven Cache Invalidation

Some databases and database products allow events to be raised from the database when rows are updated or deleted in the database.

EclipseLink supports an API to allow the database to notify EclipseLink of database changes, so the changed objects can be invalidated in the EclipseLink shared cache. This allows a shared cache to be used, and stale data to be avoided, even if other applications access the same data in the database. EclipseLink supports integration with the Oracle Database feature for Database Change Notification (DCN, QCN). A custom DatabaseEventListener may be provided for other databases and products that support database events.

There are also other solutions to caching in a shared environment, including:

  • Disable the shared cache (through setting @Cacheable(false), or @Cache(isolation=ISOLATED)).
  • Only cache read-only objects.
  • Set a cache invalidation timeout to reduce stale data.
  • Use refreshing on objects/queries when fresh data is required.
  • Use optimistic locking to ensure write consistency (writes on stale data will fail, and will automatically invalidate the cache).

The JPA Cache API and the EclipseLink JpaCache API can also be used directly to invalidate objects in the shared cache by the application. EclipseLink cache coordination could also be used to send invalidation messages to a cluster of EclipseLink persistence units.

Database events can reduce the chance of an application getting stale data, but do not eliminate the possibility. Optimistic locking should still be used to ensure data integrity. Even in a single server application stale data is still possible within a persistence context unless pessimistic locking is used. Optimistic (or pessimistic) locking is always required to ensure data integrity in any multi-user system.

Oracle DCN/QCN

The Oracle database released a Database Change Notification (DCN) feature in the 10.2 release. DCN allows for database events to be raised when the rows in a table are modified. The JDBC API for DCN was not complete until 11.2, so 11.2 is required for EclipseLink's integration. DCN is also now referred to as QCN (Query Change Notification).

EclipseLink DCN support is enabled through the OracleChangeNotificationListener listener which integrates with Oracle JDBC to received database change events. By default all tables in the persistence unit are registered for change notification, but this can be configured using the databaseChangeNotificationType attribute of the @Cache annotation to selectively disable change notification for certain classes.

Oracle DCN uses the ROWID to inform of row level changes. This requires EclipseLink to include the ROWID is all queries for a DCN enabled class, as well as after an insert, EclipseLink will require to select the object's ROWID. EclipseLink must maintain a cache index on the ROWID, in addition to the object's Id. EclipseLink will also selects the database transaction id once each transaction to avoid invalidating the cache on the server that is processing the transaction.

EclipseLink's DCN integration has the following limitations:

  • Changes to an object's secondary tables will not trigger it to be invalidate unless a version is used and updated in the primary table.
  • Changes to an object's OneToMany, ManyToMany, and ElementCollection relationships will not trigger it to be invalidate unless a version is used and updated in the primary table.

Configuring a Database Event Listener

Database change events are configured using the persistence unit property eclipselink.cache.database-event-listener. The full class name of the listener class must be provided, DCN or QCN can also be used to configure Oracle DCN.

EclipseLink persistence.xml Oracle DCN example
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_2_0.xsd"
                version="2.0">
    <persistence-unit name="acme" transaction-type="RESOURCE_LOCAL">
        <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.cache.database-event-listener" value="org.eclipse.persistence.platform.database.oracle.dcn.OracleChangeNotificationListener"/>
        </properties>
    </persistence-unit>
</persistence>

Eclipselink-logo.gif
Version: 2.4 DRAFT
Other versions...

Copyright © Eclipse Foundation, Inc. All Rights Reserved.