Package org.datanucleus.cache

This package provides classes implementing L1/L2 persistable object caching within DataNucleus. There are 2 caches used internally :-

The Level 1 cache is used within the PersistenceManager/EntityManager, storing objects that are currently managed etc. There are several implementations of Level 1 Cache here :- SoftRefCache, WeakRefCache and HardRefCache. They provide varying degrees of object retention during the garbage collection process.

The Level 2 cache is used across multiple PersistenceManagers/EntityManagers within the same PersistenceManagerFactory/EntityManagerFactory. There are several implementations of a Level 2 Cache here :- JavaxCacheLevel2Cache (using the javax.cache API), SoftLevel2Cache, and WeakLevel2Cache. Alternatively look in the datanucleus-cache plugin for various L2 caches using third party software.

As far as Level 2 caching is concerned each class is configurable via metadata @Cacheable (and equivalent XML) as to whether it is cached. In addition we can define which fields are cacheable using this mechanism, but maybe using @Extension metadata if the persistence API doesn't support field-level restrictions.

At commit of a transaction we check all enlisted objects and have a recursive process that navigates down through all objects to cache (limited by the FetchPlan) and at the end all of these objects will be put in the L2 cache (and logged). Also at this point if any enlisted objects have been deleted during the transaction we remove them from the L2 cache. When an object is to be put in the L2 cache we check if it already has an entry in the L2 cache and, if so, we update that object with the current field values, version, etc. When an object is to be put in the L2 cache and it has relation fields, we don't store the actual objects of those relations instead storing the identities of the related objects in the CachedPC object. When an object is to be taken from the L2 cache we create a copy of that object and copy the field values across for all fields that were loaded when it was originally put in the cache. When a relation field is required to be loaded we use the identities that are stored in the CachedPC, and find the equivalent object for that identity from the L1/L2 caches, reinstating it into the managed object.