Level2Cache (DataNucleus Core 4.1.17-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 JDO2/JPA1 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 in DataNucleus is as follows :-

The L2 cache stores an object of type org.datanucleus.cache.CachedPC and is keyed by the identity of the object. The CachedPC contains a persistable object (not connected to an ObjectProvider), together with the indicators for which fields are loaded, as well as values for any relation fields. The persistable object will have values as null for any relation fields, and it is these relation field values stored in the CachedPC that provide linkage to other objects.

The relation field values also 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.

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class Level2Cache.PinnedClass
Representation of a class whose objects will be pinned when put into the L2 cache.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`Level2Cache.PinnedClass` Representation of a class whose objects will be pinned when put into the L2 cache.

Method Summary

All Methods Instance Methods Abstract 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.
`CachedPC`	`get(Object oid)` Accessor for an object from the cache.
`Map<Object,CachedPC>`	`getAll(Collection oids)` Accessor for a collection of objects from the cache.
`int`	`getNumberOfPinnedObjects()` Accessor for the number of pinned objects in the cache.
`int`	`getNumberOfUnpinnedObjects()` Accessor for the number of unpinned objects in the cache.
`int`	`getSize()` Accessor for the total number of objects in the L2 cache.
`boolean`	`isEmpty()` Accessor for whether the cache is empty.
`void`	`pin(Object oid)` Pin the parameter instance in the second-level cache.
`void`	`pinAll(Class pcClass, boolean subclasses)` Pin instances in the second-level cache.
`void`	`pinAll(Collection oids)` Pin the parameter instances in the second-level cache.
`void`	`pinAll(Object[] oids)` Pin the parameter instances in the second-level cache.
`CachedPC`	`put(Object oid, CachedPC pc)` Method to put an object in the cache.
`void`	`putAll(Map<Object,CachedPC> objs)` Method to put several objects into the cache.
`void`	`unpin(Object oid)` Unpin the parameter instance from the second-level cache.
`void`	`unpinAll(Class pcClass, boolean subclasses)` Unpin instances from the second-level cache.
`void`	`unpinAll(Collection oids)` Unpin the parameter instances from the second-level cache.
`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
  - pin
```
void pin(Object oid)
```
    Pin the parameter instance in the second-level cache.
    
    Parameters:
    
    oid - the object id of the instance to pin.
  - pinAll
```
void pinAll(Collection oids)
```
    Pin the parameter instances in the second-level cache.
    
    Parameters:
    
    oids - the object ids of the instances to pin.
  - pinAll
```
void pinAll(Object[] oids)
```
    Pin the parameter instances in the second-level cache.
    
    Parameters:
    
    oids - the object ids of the instances to pin.
  - pinAll
```
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
```
void unpin(Object oid)
```
    Unpin the parameter instance from the second-level cache.
    
    Parameters:
    
    oid - the object id of the instance to unpin.
  - unpinAll
```
void unpinAll(Collection oids)
```
    Unpin the parameter instances from the second-level cache.
    
    Parameters:
    
    oids - the object ids of the instance to evict.
  - unpinAll
```
void unpinAll(Object[] oids)
```
    Unpin the parameter instance from the second-level cache.
    
    Parameters:
    
    oids - the object id of the instance to evict.
  - unpinAll
```
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
```
int getNumberOfPinnedObjects()
```
    Accessor for the number of pinned objects in the cache.
    
    Returns:
    
    Number of pinned objects
  - getNumberOfUnpinnedObjects
```
int getNumberOfUnpinnedObjects()
```
    Accessor for the number of unpinned objects in the cache.
    
    Returns:
    
    Number of unpinned objects
  - getSize
```
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
```
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
    
    pc - The L2 cacheable persistable object
    
    Returns:
    
    The value previously associated with this oid
  - putAll
```
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
```
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

Interface Level2Cache

Nested Class Summary

Method Summary

Method Detail

close

evict

evictAll

evictAll

evictAll

evictAll

pin

pinAll

pinAll

pinAll

unpin

unpinAll

unpinAll

unpinAll

getNumberOfPinnedObjects

getNumberOfUnpinnedObjects

getSize

get

getAll

put

putAll

isEmpty

containsOid