Difference between revisions of "EclipseLink/DesignDocs/356812"

From Eclipsepedia

Jump to: navigation, search
(Native API)
 
(12 intermediate revisions by one user not shown)
Line 16: Line 16:
 
| James
 
| James
 
| 0.1 Draft
 
| 0.1 Draft
 +
|-
 +
| 2011-09-13
 +
| James
 +
| 0.2 Updated API
 
|-  
 
|-  
 
|}
 
|}
Line 42: Line 46:
  
 
= Functionality =
 
= Functionality =
* Add a DatabaseEventNotificationListener interface and to DatabaseSessionImpl (Database and Server sessions).
+
* Add a DatabaseEventListener interface and to DatabaseSessionImpl (Database and Server sessions).
 
** Give register/remove callbacks on login/logout.
 
** Give register/remove callbacks on login/logout.
* Add OracleDCNListener to Oracle with Oracle JDBC dependencies.
+
* Add OracleChangeNotificationListener to Oracle with Oracle JDBC dependencies.
 
** Register with database on login, remove on logout.  Register all tracked tables.
 
** Register with database on login, remove on logout.  Register all tracked tables.
 
** Oracle DCN only gives table name and ROWID, no primary key, so need to match ROWID with ID.
 
** Oracle DCN only gives table name and ROWID, no primary key, so need to match ROWID with ID.
Line 53: Line 57:
 
** On merge for updates include the transaction id in the CacheKey
 
** On merge for updates include the transaction id in the CacheKey
 
** When a DCN event is received find the CacheKey for the ROWID, and invalidate unless its transaction id matches the events transaction id.
 
** When a DCN event is received find the CacheKey for the ROWID, and invalidate unless its transaction id matches the events transaction id.
* Add a DatabaseCacheInvalidationPolicy to allow a descriptor to be configured to receive change events.
+
* Add a DatabaseChangeNotificationType to CachePolicy to allow a descriptor to be configured to receive change events.
** Add a persistence unit default property for cache invalidation type.
+
** Add a persistence unit default property for databaseChangeNotificationType.
 
* Only the primary table is supported.  For secondary tables, or relationships usage of optimistic locking is required to ensure the primary table is always updated.
 
* Only the primary table is supported.  For secondary tables, or relationships usage of optimistic locking is required to ensure the primary table is always updated.
  
Line 70: Line 74:
  
 
* @Cache
 
* @Cache
** invalidationType
+
** databaseChangeNotificationType
* CacheInvalidationType (TimeToLive, Database, Daily, None)
+
* DatabaseChangeNotificationType (NONE, INVALIDATE)
  
 
= Native API =
 
= Native API =
  
 
* DatabaseSession
 
* DatabaseSession
** setDatabaseEventListener(DatabaseEventNotificationListener )
+
** setDatabaseEventListener(DatabaseEventListener )
* DatabaseEventNotificationListener (org.eclipse.persistence.platform.database.events)
+
* DatabaseEventListener (org.eclipse.persistence.platform.database.events)
 
* OracleChangeNotificationListener (org.eclipse.persistence.platform.oracle.dcn)
 
* OracleChangeNotificationListener (org.eclipse.persistence.platform.oracle.dcn)
  
Line 83: Line 87:
 
* persistence.xml - property
 
* persistence.xml - property
 
** "eclipselink.cache.database-event-listener"="<class-name>"
 
** "eclipselink.cache.database-event-listener"="<class-name>"
** "eclipselink.cache.invalidation.default"=CacheInvalidationType
 
 
* orm.xml
 
* orm.xml
 
<source lang="xml">
 
<source lang="xml">
<cache invalidation-type="Database"/>
+
<cache database-change-notification-type="Invalidate"/>
 
</source>
 
</source>
  
 
= Documentation =
 
= Documentation =
 
Should be documented under caching section, and Oracle section.
 
Should be documented under caching section, and Oracle section.
 +
 +
Need to document limitations is secondary table and relationship support.
 +
Warnings should be logged if version locking is not used.
  
 
= Open Issues  =
 
= Open Issues  =
Line 107: Line 113:
 
|
 
|
 
| How to integrate with third party cache support?
 
| How to integrate with third party cache support?
 +
|-
 +
| 3
 +
|
 +
| How should a descriptor be configured to use database change notification?
 
|}
 
|}
  
Line 120: Line 130:
 
| How to handle secondary tables and relationships?
 
| How to handle secondary tables and relationships?
 
| Require usage of optimistic locking, so the primary table is always updated.
 
| Require usage of optimistic locking, so the primary table is always updated.
 +
|-
 +
| 2
 +
| Oracle DCN was renamed QCN?
 +
| Change name of listener from OracleDCNListener to OracleChangeNotificationListener.
 +
|-
 +
| 3
 +
| How should a descriptor be configured to use database change notification?
 +
| New databaseChangeNotificationType on CachePolicy and @Cache.
 
|}
 
|}
  
 
= Future Considerations =
 
= Future Considerations =
 
* Other databases and event mechanisms.
 
* Other databases and event mechanisms.
* Show examples the uses triggers and Oracle AQ.
+
* Show example the uses triggers and Oracle AQ.

Latest revision as of 14:02, 13 September 2011

[edit] Design Specification: Database Change Event Cache Invalidation

ER 356812

Feedback

[edit] Document History

Date Author Version Description & Notes
2011-09-06 James 0.1 Draft
2011-09-13 James 0.2 Updated API

[edit] Project overview

Some databases support raising change events when tables are updated or changed. It is also possible in some databases to raise events from triggers, and some third party products support raising database change events.

When a share cache is used in EclipseLink it can become stale if other applications (or other nodes) update the database directly.

This project will provide an infrastructure for supporting database change events to invalidate the changed objects in the EclipseLink shared cache.

Oracle's Database Change event Notification will be supported for Oracle databases.


[edit] Concepts

Oracle DCN : The Oracle database Database Change event Notification feature available since Oracle 10.2.

[edit] Requirements

  • Support generic database change event listener.
  • Support Oracle DCN
  • Support cache invalidation of change objects.

[edit] Design Constraints

  • Must support database events with limited information, such as only the table ROWID.

[edit] Functionality

  • Add a DatabaseEventListener interface and to DatabaseSessionImpl (Database and Server sessions).
    • Give register/remove callbacks on login/logout.
  • Add OracleChangeNotificationListener to Oracle with Oracle JDBC dependencies.
    • Register with database on login, remove on logout. Register all tracked tables.
    • Oracle DCN only gives table name and ROWID, no primary key, so need to match ROWID with ID.
    • Adds ROWID and a cache index on ROWID to all tracked descriptors.
    • All objects read will be indexed by ROWID from cache index.
    • Add insert callback to select ROWID and index in cache.
    • On any update or delete get the transaction id and store in the unit of work properties.
    • On merge for updates include the transaction id in the CacheKey
    • When a DCN event is received find the CacheKey for the ROWID, and invalidate unless its transaction id matches the events transaction id.
  • Add a DatabaseChangeNotificationType to CachePolicy to allow a descriptor to be configured to receive change events.
    • Add a persistence unit default property for databaseChangeNotificationType.
  • Only the primary table is supported. For secondary tables, or relationships usage of optimistic locking is required to ensure the primary table is always updated.

[edit] Testing

Add a JPA test model for DCN testing to the Oracle tests. Test:

  • multiple tables (with versioning)
  • inheritance
  • relationships (with versioning)
  • ensure objects invalidated in other session
  • test native SQL queries
  • test update-all queries

[edit] API

  • @Cache
    • databaseChangeNotificationType
  • DatabaseChangeNotificationType (NONE, INVALIDATE)

[edit] Native API

  • DatabaseSession
    • setDatabaseEventListener(DatabaseEventListener )
  • DatabaseEventListener (org.eclipse.persistence.platform.database.events)
  • OracleChangeNotificationListener (org.eclipse.persistence.platform.oracle.dcn)

[edit] Config files

  • persistence.xml - property
    • "eclipselink.cache.database-event-listener"="<class-name>"
  • orm.xml
<cache database-change-notification-type="Invalidate"/>

[edit] Documentation

Should be documented under caching section, and Oracle section.

Need to document limitations is secondary table and relationship support. Warnings should be logged if version locking is not used.

[edit] Open Issues

Issue # Owner Description / Notes
1 How to handle secondary tables and relationships?
2 How to integrate with third party cache support?
3 How should a descriptor be configured to use database change notification?

[edit] Decisions

Issue Description / Notes Decision
1 How to handle secondary tables and relationships? Require usage of optimistic locking, so the primary table is always updated.
2 Oracle DCN was renamed QCN? Change name of listener from OracleDCNListener to OracleChangeNotificationListener.
3 How should a descriptor be configured to use database change notification? New databaseChangeNotificationType on CachePolicy and @Cache.

[edit] Future Considerations

  • Other databases and event mechanisms.
  • Show example the uses triggers and Oracle AQ.