Jump to: navigation, search

Difference between revisions of "EclipseLink/DesignDocs/350484"

(New page: <div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div> = Design Specification: Cache Indexes = [http://bugs.eclipse.org/350484 ER 350484] [[Talk:EclipseLi...)
 
(Open Issues)
 
(6 intermediate revisions by the same user not shown)
Line 29: Line 29:
  
 
= Concepts =
 
= Concepts =
 
+
An index allows the quick look-up of an item.
 
+
  
 
= Requirements =
 
= Requirements =
Line 45: Line 44:
  
 
= Functionality =
 
= Functionality =
All caching functions of a descriptor will be moved to a new CachePolicy (still supporting old API).
+
* All caching functions of a descriptor will be moved to a new CachePolicy (still supporting old API).
CachePolicy will also define set of CacheIndexes.  A CacheIndex will contain a set of columns.
+
* CachePolicy will also define set of CacheIndexes.  A CacheIndex will contain a set of columns.
All objects read will be indexed by all of its indexes.
+
* All objects read will be indexed by all of its indexes.
Any object merged will be indexed by all of its indexes (this handles new objects and updates to index fields).
+
* Any object merged will be indexed by all of its indexes (this handles new objects and updates to index fields).
The index cache will be a separate IdentityMap per index stored in the IdentityMapManager.
+
* The index cache will be a separate IdentityMap per index stored in the IdentityMapManager.
The IdentityMap key will be an ObjectId of the index values.  The value will be the CacheKey of the object from the object cache.
+
* The IdentityMap key will be an ObjectId of the index values.  The value will be the CacheKey of the object from the object cache.
All index caches will be weak, this allows them to garbage collect when their indexed object garbage collects.
+
* All index caches will be weak, this allows them to garbage collect when their indexed object garbage collects.
Only ReadObjectQuerys will make use of indexes.
+
* Only ReadObjectQuerys will make use of indexes.
Index hits will not occur on invalidate objects.
+
* Index hits will not occur on invalidate objects.
CacheKeys removed from the object cache will be set as invalid.
+
* CacheKeys removed from the object cache will be set as invalid.
Any query using a indexed field will check the index cache.  The result will always be conformed to the query expression.
+
* Any query using a indexed field will check the index cache.  The result will always be conformed to the query expression (similar to current in-exact pks).
JPQL querys for a singleResult will check the cache by default (be executed as ReadObjectQuerys), perhaps only if they are by an id or indexed field.
+
* JPQL querys for a singleResult will check the cache by default (be executed as ReadObjectQuerys), perhaps only if they are by an id or indexed field.
  
 
= Testing =
 
= Testing =
Line 66: Line 65:
 
* @CacheIndex(columns={@Column})
 
* @CacheIndex(columns={@Column})
 
* @CacheIndexes
 
* @CacheIndexes
 +
 +
= Native API =
 +
 +
* CacheIndex
 +
* CachePolicy
 +
** addCacheIndex()
  
 
= Config files =
 
= Config files =
Line 88: Line 93:
 
|-
 
|-
 
| 1  
 
| 1  
|  
+
| How to allow cache hits on JPA queries by default?
|  
+
| Currently a query hint is required.
 
|-
 
|-
 
| 2  
 
| 2  
|  
+
| Should objects in a unit of work be indexed?
|  
+
| Currently no (not shared, can change).
  
 
|}
 
|}
Line 108: Line 113:
 
= Future Considerations =
 
= Future Considerations =
 
* Support use of non-unique indexes for in-memory querying.
 
* Support use of non-unique indexes for in-memory querying.
 +
* Third party cache index support.

Latest revision as of 10:14, 25 July 2011

Design Specification: Cache Indexes

ER 350484

Feedback

Document History

Date Author Version Description & Notes
2011-07-21 James 0.1 Draft

Project overview

Allow indexes objects in the object cache by non-id fields. This allows for ReadObject/singleResult query to obtain cache hits on non-id fields. This enable cache hits for application that have natural primary keys, or common query keys (ssn, phone#, name, account#, etc.). It is very common for applications to have a generated id, but a natural key used in the domain.

This is desired in part to allow indexes objects by row-id for database change notification support.


Concepts

An index allows the quick look-up of an item.

Requirements

  • Index single and composite fields
  • Obtain cache hit on index
  • Index object read, and new objects inserted or updated
  • Support cache consistency and allow updateable index fields
  • Add minimal overhead, no overhead when not using indexes
  • Index by non-mapped fields
  • JPA annotation and XML support

Design Constraints

Must support indexing of an object by its row-id.

Functionality

  • All caching functions of a descriptor will be moved to a new CachePolicy (still supporting old API).
  • CachePolicy will also define set of CacheIndexes. A CacheIndex will contain a set of columns.
  • All objects read will be indexed by all of its indexes.
  • Any object merged will be indexed by all of its indexes (this handles new objects and updates to index fields).
  • The index cache will be a separate IdentityMap per index stored in the IdentityMapManager.
  • The IdentityMap key will be an ObjectId of the index values. The value will be the CacheKey of the object from the object cache.
  • All index caches will be weak, this allows them to garbage collect when their indexed object garbage collects.
  • Only ReadObjectQuerys will make use of indexes.
  • Index hits will not occur on invalidate objects.
  • CacheKeys removed from the object cache will be set as invalid.
  • Any query using a indexed field will check the index cache. The result will always be conformed to the query expression (similar to current in-exact pks).
  • JPQL querys for a singleResult will check the cache by default (be executed as ReadObjectQuerys), perhaps only if they are by an id or indexed field.

Testing

Add index to existing JPA and core models. Test single and composite field indexes, hits and misses.

API

  • @CacheIndex(columns={@Column})
  • @CacheIndexes

Native API

  • CacheIndex
  • CachePolicy
    • addCacheIndex()

Config files

  • orm.xml
<cache-index>
  <column name="F_NAME"/>
  <column name="L_NAME"/>
</cache-index>

Documentation

Should be documented under caching section.

Open Issues

Issue # Owner Description / Notes
1 How to allow cache hits on JPA queries by default? Currently a query hint is required.
2 Should objects in a unit of work be indexed? Currently no (not shared, can change).

Decisions

Issue Description / Notes Decision

Future Considerations

  • Support use of non-unique indexes for in-memory querying.
  • Third party cache index support.