Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseLink/DesignDocs/350484
Design Specification: Cache Indexes
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.