Interface Level2Cache

All Superinterfaces:
Serializable
All Known Implementing Classes:
AbstractLevel2Cache, AbstractReferencedLevel2Cache, JavaxCacheLevel2Cache, NullLevel2Cache, SoftLevel2Cache, WeakLevel2Cache

public interface Level2Cache extends Serializable
Interface for any Level 2 Cache used internally. Provides the typical controls required internally and including the JDO/JPA/Jakarta L2 cache methods. JDO/JPA/Jakarta allow the use of a level 2 (L2) cache, with the cache shared between PersistenceManagers/EntityManagers. The objects in the level 2 cache don't pertain to any one manager.

The L2 cache stores an object of type org.datanucleus.cache.CachedPC and is keyed by the identity of the object. The CachedPC contains the values of fields of a persistable object, together with the indicators for which fields are loaded. The relation field values do not store actual objects; they store the identities of the related objects. For example if an object X has a 1-1 relation with another persistable object Y then in the relation field values for X for that field we store the identity of Y. Similarly if the field is a Collection, then the relation field values will be a Collection of identities of the related objects. This provides isolation of each object in the L2 cache (so objects aren't storing references to other objects and so allowing garbage collection etc).

Objects are stored in the L2 cache in the following situations

  • An object is retrieved (from the datastore) within a transaction, and it is stored in the L2 cache if no object with that identity already exists there.
  • At commit() of the transaction any object that has been modified during that transaction will be stored/updated in the L2 cache if its persistable object is still in memory in the PM/EM (could have been garbage collected since flushing)

Each class can be configured to be cacheable or not. The default for a persistable class is to be cacheable. Configuration is performed via annotations or XML metadata. If a class is not cacheable then objects of that type aren't stored in the L2 cache.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Method to close the cache when no longer needed.
    boolean
    Accessor for whether an object with the specified id is in the cache
    void
    Evict the parameter instance from the second-level cache.
    void
    Evict the parameter instances from the second-level cache.
    void
    evictAll(Class pcClass, boolean subclasses)
    Evict the parameter instances from the second-level cache.
    void
    evictAll(Object[] oids)
    Evict the parameter instances from the second-level cache.
    void
    Evict the parameter instances from the second-level cache.
    get(Object oid)
    Accessor for an object from the cache.
    Accessor for a collection of objects from the cache.
    default int
    Accessor for the number of pinned objects in the cache.
    default int
    Accessor for the number of unpinned objects in the cache.
    default int
    Accessor for the total number of objects in the L2 cache.
    default CachedPC
    Method to retrieve the id represented by the specified unique key.
    default boolean
    Accessor for whether the cache is empty.
    default void
    pin(Object oid)
    Pin the parameter instance in the second-level cache.
    default void
    pinAll(Class pcClass, boolean subclasses)
    Pin instances in the second-level cache.
    default void
    pinAll(Object[] oids)
    Pin the parameter instances in the second-level cache.
    default void
    Pin the parameter instances in the second-level cache.
    put(Object oid, CachedPC pc)
    Method to put an object in the cache.
    default void
    Method to put several objects into the cache.
    default CachedPC
    Method to store a persistable object for this unique key.
    default void
    Method to put several objects into the cache.
    default void
    Method to remove any object cached against the provided unique key.
    default void
    Unpin the parameter instance from the second-level cache.
    default void
    unpinAll(Class pcClass, boolean subclasses)
    Unpin instances from the second-level cache.
    default void
    unpinAll(Object[] oids)
    Unpin the parameter instance from the second-level cache.
    default void
    Unpin the parameter instances from the second-level cache.
  • Method Details

    • close

      void close()
      Method to close the cache when no longer needed. Provides a hook to release resources etc.
    • evict

      void evict(Object oid)
      Evict the parameter instance from the second-level cache.
      Parameters:
      oid - the object id of the instance to evict.
    • evictAll

      void evictAll()
      Evict the parameter instances from the second-level cache. All instances in the PersistenceManager's cache are evicted from the second-level cache.
    • evictAll

      void evictAll(Object[] oids)
      Evict the parameter instances from the second-level cache.
      Parameters:
      oids - the object ids of the instance to evict.
    • evictAll

      void evictAll(Collection oids)
      Evict the parameter instances from the second-level cache.
      Parameters:
      oids - the object ids of the instance to evict.
    • evictAll

      void evictAll(Class pcClass, boolean subclasses)
      Evict the parameter instances from the second-level cache.
      Parameters:
      pcClass - the class of instances to evict
      subclasses - if true, evict instances of subclasses also
    • getSize

      default int getSize()
      Accessor for the total number of objects in the L2 cache.
      Returns:
      Number of objects
    • get

      CachedPC get(Object oid)
      Accessor for an object from the cache.
      Parameters:
      oid - The Object ID
      Returns:
      The L2 cacheable object
    • getAll

      default Map<Object,CachedPC> getAll(Collection oids)
      Accessor for a collection of objects from the cache.
      Parameters:
      oids - The Object IDs
      Returns:
      Map of the objects, keyed by the oids that are found
    • put

      CachedPC put(Object oid, CachedPC pc)
      Method to put an object in the cache.
      Parameters:
      oid - The Object id for this object (see StateManager.getInternalObjectId)
      pc - The L2-cacheable persistable object
      Returns:
      The value previously associated with this oid
    • putAll

      default void putAll(Map<Object,CachedPC> objs)
      Method to put several objects into the cache.
      Parameters:
      objs - Map of cacheable object keyed by its oid.
    • isEmpty

      default boolean isEmpty()
      Accessor for whether the cache is empty.
      Returns:
      Whether it is empty.
    • containsOid

      boolean containsOid(Object oid)
      Accessor for whether an object with the specified id is in the cache
      Parameters:
      oid - The object id
      Returns:
      Whether it is in the cache
    • getUnique

      default CachedPC getUnique(CacheUniqueKey key)
      Method to retrieve the id represented by the specified unique key.
      Parameters:
      key - Unique key
      Returns:
      The "identity" of the object that this unique key represents
    • putUnique

      default CachedPC putUnique(CacheUniqueKey key, CachedPC pc)
      Method to store a persistable object for this unique key.
      Parameters:
      key - The unique key
      pc - The representation of the persistable object to cache
      Returns:
      The previous object for this unique key if one was present, otherwise null
    • putUniqueAll

      default void putUniqueAll(Map<CacheUniqueKey,CachedPC> objs)
      Method to put several objects into the cache.
      Parameters:
      objs - Map of cacheable object keyed by the unique keys.
    • removeUnique

      default void removeUnique(CacheUniqueKey key)
      Method to remove any object cached against the provided unique key.
      Parameters:
      key - Unique key
    • pin

      default void pin(Object oid)
      Pin the parameter instance in the second-level cache.
      Parameters:
      oid - the object id of the instance to pin.
    • pinAll

      default void pinAll(Collection oids)
      Pin the parameter instances in the second-level cache.
      Parameters:
      oids - the object ids of the instances to pin.
    • pinAll

      default void pinAll(Object[] oids)
      Pin the parameter instances in the second-level cache.
      Parameters:
      oids - the object ids of the instances to pin.
    • pinAll

      default void pinAll(Class pcClass, boolean subclasses)
      Pin instances in the second-level cache.
      Parameters:
      pcClass - the class of instances to pin
      subclasses - if true, pin instances of subclasses also
    • unpin

      default void unpin(Object oid)
      Unpin the parameter instance from the second-level cache.
      Parameters:
      oid - the object id of the instance to unpin.
    • unpinAll

      default void unpinAll(Collection oids)
      Unpin the parameter instances from the second-level cache.
      Parameters:
      oids - the object ids of the instance to evict.
    • unpinAll

      default void unpinAll(Object[] oids)
      Unpin the parameter instance from the second-level cache.
      Parameters:
      oids - the object id of the instance to evict.
    • unpinAll

      default void unpinAll(Class pcClass, boolean subclasses)
      Unpin instances from the second-level cache.
      Parameters:
      pcClass - the class of instances to unpin
      subclasses - if true, unpin instances of subclasses also
    • getNumberOfPinnedObjects

      default int getNumberOfPinnedObjects()
      Accessor for the number of pinned objects in the cache.
      Returns:
      Number of pinned objects
    • getNumberOfUnpinnedObjects

      default int getNumberOfUnpinnedObjects()
      Accessor for the number of unpinned objects in the cache.
      Returns:
      Number of unpinned objects