Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: for the plan.

Jump to: navigation, search


Design Specification: Cache Indexes

ER 350484


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.


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


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


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


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


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

Native API

  • CacheIndex
  • CachePolicy
    • addCacheIndex()

Config files

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


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


Issue Description / Notes Decision

Future Considerations

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

Back to the top