Level2Cache (DataNucleus Core 5.1.13-SNAPSHOT API)

All Superinterfaces:

Serializable

All Known Implementing Classes:

AbstractLevel2Cache, 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 L2 cache methods. JDO and JPA 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

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`void`	`close()` Method to close the cache when no longer needed.
`boolean`	`containsOid(Object oid)` Accessor for whether an object with the specified id is in the cache
`void`	`evict(Object oid)` Evict the parameter instance from the second-level cache.
`void`	`evictAll()` 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(Collection oids)` Evict the parameter instances from the second-level cache.
`void`	`evictAll(Object[] oids)` Evict the parameter instances from the second-level cache.
`<T> CachedPC<T>`	`get(Object oid)` Accessor for an object from the cache.
`default Map<Object,CachedPC>`	`getAll(Collection oids)` Accessor for a collection of objects from the cache.
`default int`	`getNumberOfPinnedObjects()` Accessor for the number of pinned objects in the cache.
`default int`	`getNumberOfUnpinnedObjects()` Accessor for the number of unpinned objects in the cache.
`default int`	`getSize()` Accessor for the total number of objects in the L2 cache.
`default CachedPC`	`getUnique(CacheUniqueKey key)` Method to retrieve the id represented by the specified unique key.
`default boolean`	`isEmpty()` 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(Collection oids)` Pin the parameter instances in the second-level cache.
`default void`	`pinAll(Object[] oids)` Pin the parameter instances in the second-level cache.
`<T> CachedPC<T>`	`put(Object oid, CachedPC<T> pc)` Method to put an object in the cache.
`default void`	`putAll(Map<Object,CachedPC> objs)` Method to put several objects into the cache.
`default CachedPC`	`putUnique(CacheUniqueKey key, CachedPC pc)` Method to store a persistable object for this unique key.
`default void`	`putUniqueAll(Map<CacheUniqueKey,CachedPC> objs)` Method to put several objects into the cache.
`default void`	`removeUnique(CacheUniqueKey key)` Method to remove any object cached against the provided unique key.
`default void`	`unpin(Object oid)` 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(Collection oids)` Unpin the parameter instances from the second-level cache.
`default void`	`unpinAll(Object[] oids)` Unpin the parameter instance from the second-level cache.

- Method Detail
  - 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
```
<T> CachedPC<T> get(Object oid)
```
    Accessor for an object from the cache.
    
    Type Parameters:
    
    T - Type of the object represented
    
    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
```
<T> CachedPC<T> put(Object oid,
                    CachedPC<T> pc)
```
    Method to put an object in the cache.
    
    Type Parameters:
    
    T - Type of the object represented
    
    Parameters:
    
    oid - The Object id for this object
    
    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

Interface Level2Cache

Method Summary

Method Detail

close

evict

evictAll

evictAll

evictAll

evictAll

getSize

get

getAll

put

putAll

isEmpty

containsOid

getUnique

putUnique

putUniqueAll

removeUnique

pin

pinAll

pinAll

pinAll

unpin

unpinAll

unpinAll

unpinAll

getNumberOfPinnedObjects

getNumberOfUnpinnedObjects