EclipseLink/DesignDocs/232063

Design Specification:
     Relationships between non-Cachable and Cachable Entities

ER 232063

Document History

Date	Author	Version Description & Notes
2010/05/27	Gordon Yorke	Initial creation of this doccumentation
2010/06/23	Gordon Yorke	Update after initial feedback
2010/10/18	Gordon Yorke	Update after additional feedback from Doug Clarke
2010/11/24	Gordon Yorke	IN PROGRESS: Update after additional config feedback from Doug Clarke

Project overview

Goals:

• Relationships between JPA 2.0 Cachable(false) and Cachable(true) Entities should be supported
• Allow for relationships to be configurable as non-cacheable and provide corresponding behaviour
• Support returning query results for cached data that are isolated from the shared cache.

Requirements

1. Support for relationships from entities configured with @Cacheable(true) to entities configured with @Cacheable(false) without any additional configuration required.
2. Change @Cache() and corresponding <cache> element in eclipselink-orm.xml
   • Deprecate the current shared attribute in @Cache as it is redundant.
   • Ensure proper handling and documentation of @Cache(isolation) overriding @Cacheable
3. JPA Configuration
   • Add attribute to @Cache and <cache> to support the notion of a cache isolation.
4. Native Configuration: Separate Isolated configuration from @Cacheable(false)
   Create multi-valued configuration option within Relational Descriptor
   • SHARED
     • Entities are cached within the shared session's IdentityMaps (normal behaviour)
   • PROTECTED
     • Shareable Entity data is cached within the shared session's IdentityMaps (normal behaviour)
     • Other Entity data is not populated.
     • All query results aways return unshared instances of these classes but data is cached in shared cache
   • ISOLATED
     • Data is not cached in shared cache ( @Cacheable(false) )
     • All queries return unshared instances of these classes.
   • When the metadata is processed any SHARED Entities that reference PROTECTED or ISOLATED Entities will be configured as PROTECTED.

• When an entity with @Cacheable(true) has a relationship to an entity with @Cacheable(false) or an @Cacheable(true) entity has a @NonCacheable relationship we will default to and only allow the Entity to have a PROTECTED Cache Isolation.
  • This allows noncacheable relationships to be built at read time while allowing other data/relationships to remain cached.
• Users could force this to avoid populating relationships in the shared cache that may cause cache life-cycle dependencies. This could allow an entity with a FULL cache to have a relationship to an entity with a WEAK cache but since it is not populated in the shared cache the WEAK garbage collection would only be governed by application references to the target.
  • Users wishing to more dynamically customize the queries for relationships could avoid corrupting the shared cache and only have their limited query result populated in the UnitOfWork
  • Users who want this behaviour would mark the relationship as NonCacheable.

EclipseLink JPA Metadata

Cacheable Entities Example

// JPA 2.0 annotations
@Cacheable(false) // indicates that the entity type should not be stored in the cache
                  // "false" equivalent to CacheIsolationType.ISOLATED
                  // "true" equivalent to CacheIsolationType.SHARED
 
// JPA 2.0 orm.xml
<entity cacheable=false/>
 
// EclipseLink Annotation
@Cache(isolation=CacheIsolationType.ISOLATED) // CacheIsolationType.ISOLATED equivalent to @Cacheable(false)
                                              // CacheIsolationType.SHARED equivalent to @Cacheable(true)
                                              // CacheIsolationType.PROTECTED equivalent to @Cacheable(true)
                                              //                    but queries will never return class instances from 
                                              //                    the shared cache
 
// EclipseLinkorm.xml
<cache isolation="ISOLATED"/>

Cacheable Relationships Examples

public class Department {
    ...
    @OneToMany(mappedBy="department")
    @NonCacheable()
    List<Employee> employees;

Background and Concepts

Terminology

Cache : For the purposes of this discussion and to align with JPA 2.0 terminology the shared cache will be considered the Cache.

Persistence Context : The EntityManager/UnitOfWork which has typically called the transactional cache will be referred to as the Persistence Context.

Isolated Cache : The isolated cache within the ClientSession will continue to be called the Isolated Cache referring to its isolation from other users yet still be a cache and not managed instances like the persistence context. The Isolated Cache is not used by default within EclipseLink's JPA implementation. It is only used within the native session API.

Details

Currently EclipseLink supports an entity (persistence object) cache managed in the shared Database or Server session (Server Session for JPA). By default all entity types make use of this shared cache unless configured otherwise @Cacheable(False).

@Cacheable(False) is internally enables through the Isolated Cache functionality. Isolated Caching was created with security as a primary requirement and Isolated Entities were not allowed to reference Shared Cache Entities. Transitioning Isolated Caches to the JPA 2.0 @Cacheable() requirements means this functionality must adapt and be more flexible as @Cacheable(true) Entities must be able to reference @Cacheable(false) Entities.

We must allow for non-cacheable relationships where the relationships are populated in isolation from the shared cache.

High Level Design

• PROTECTED Entity instances will always be re-built when returned
• ISOLATED Entities will not be cached but will be reloaded each time

• ForeignReferenceMappings will track when they reference ISOLATED/PROTECTED Entities
  • This allows the mapping to determine how and when the relationship should be built preventing protected relationships from being built into the cache.

• PROTECTED Entities can still use the cached version when being built.

Design / Functionality

The basics of this implementation is a refactoring of our caching behaviour to allow for an intermediary type of Cache Isolation where Entity instances are isolated to the Persistence Context or to an IsolatedClientSession but are still able to use and maintain cached data. This is useful for scenarios where relationships can not be cached within the shared cache Entity either by user request (@Noncacheable) or because the relationship of a @Cacheable entity references a @Cacheable(false) entity. With the Entity instance isolated to the PersistenceContext the protected relationships can be loaded locally and not in the shared cache.

Individual relationships can be marked as protected and these relationships will not be cached. Having non-cacheable relationships will force and Entity to have Protected Cache Isolation

Shared Cache instances will still have concurrency locks applied as appropriate.

Protected Entities can be "cached" within an IsolatedClientSession if not isolating Entities to a Persistence Context.

Details

When Entities are built/merged into the shared cache their noncacheable relationships are simply not loaded/merged

Minimal FK data will be cached on the CacheKey for any relationship that can not be loaded in the shared cache. When the relationship is populated for a query result the FK data will be used within the relationship query that will be used to load the relationship

When an entity is loaded through a query and is not already present in the cache the cache will be updated with the query result if the cache usage settings allow.

If a query is issued for a Protected or Isolated type that query will be processed within its own temporary session to allow for proper isolation.

Merges will merge shareable data from Protected Entities into both the IsolatedSession and Shared cache if the UOW isolation allows.

Documentation

• Within the cache theory the concept of isolation needs to be explained with the 3 modes
• JPA and EclipseLink JPA configuration using annotations and XML
  • Overriding rules

Open Issues

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

Issue #	Owner	Description / Notes

Decisions

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

Issue #	Description / Notes	Decision

Future Considerations

During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.