Revision as of 12:02, 24 November 2010

Design Specification:
     Relationships between non-Cachable and Cachable Entities

ER 232063

Document History

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.

Background and Concepts

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.

The solution to this is two fold. First we must be able to create copies of the shared cache instances to allow for mixing cachable data with non cachable relationships. Second we must allow for non-cacheable relationships where the relationships are populated in an isolation from the shared cache.

Terminology

'Cache: For the purposes of this discussion and to align with JPA 2.0 terminology the shared cachewill 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.

Configuration

// JPA 2.0 annotations
@Cacheable(false) // indicates that the entity type should not be stored in the cache
 
// JPA 2.0 orm.xml
<entity cacheable=true/>
 
// EclipseLink Annotation
@Cache(cacheable=true, copyReadOnly = true)
 
// EclipseLinkorm.xml
<cache cacheable="true" copyReadOnly="true"/>

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 eclispelink-orm.xml to have a boolean 'cacheable' attribute so that the name aligns better with JPA 2.0's @Cacheable.
   • Deprecate the current shared attribute in @Cache as it is redundant. shared=true == cacheable=true and shared=false == cacheable=false
   • Ensure proper handling and documentation of @Cache(cacheable) overriding @Cacheable as well as conflicts between shared and cacheable attributes.
3. JPA Configuration
   • Add attribute to @Cache and <cache> to support the notion of a 'protected' entity type. This will be an optional boolean flag.
4. Native Configuration: Separate Isolated configuration from @Cacheable(false)
   Create multi-valued configuration option within RelationalDescriptor
   • SHARED
     • Entities are cached within the shared session's IdentityMaps (normal behaviour)
   • PROTECTED
     • Entities are cached within the shared session's IdentityMaps (normal behaviour)
     • All query results aways return cloned versions of these classes but data is cached in shared cache
   • ISOLATED
     • Data is not cached in shared cache ( @Cacheable(false) ) has same isolated behaviour as today
   • 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) we would default to and only allow the relationship to @Cacheable(false)
• When an entity has a relationship to another entity (shared or isolated caching) and there is @AdditionalCriteria configured on the target we would default to only populating the relationship when read into the UnitOfWork
• 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

Cacheable Relationships Examples

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

EclipseLink JPA Metadata

Cacheable Entities Example

• @Cache(cacheable=true, protected=false)

• <cache cacheable=true, protected=false/>

Cacheable Relationships Examples

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

High Level Design

• PROTECTED Entities will always be cloned 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/ISOLATED Entities can still use the cached version when being built.

Design / Functionality

Design Notes

Testing

API

Config files

Documentation

Open Issues

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

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.

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.