DataCache (OpenJPA Parent POM 3.2.0 API)

All Superinterfaces:

Clearable, Closeable

All Known Implementing Classes:

AbstractDataCache, ConcurrentDataCache, DelegatingDataCache, PartitionedDataCache
```
public interface DataCache
extends Closeable, Clearable
```
Interface that must be implemented by any level 2 cache used by OpenJPA. Most data caches will choose to implement the Configurable interface as well so that they will be given the system configuration just after construction. Implementations should take care not to return timed out data.

Author:

Patrick Linskey, Abe White, Pinaki Poddar

See Also:

AbstractDataCache, DataCachePCData.isTimedOut()

Field Summary

Fields
Modifier and Type Field and Description

static String NAME_DEFAULT
The name of the default data cache: default

Fields
Modifier and Type	Field and Description
`static String`	`NAME_DEFAULT` The name of the default data cache: `default`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addExpirationListener(ExpirationListener listen)` Add a new expiration event listener to this cache.
`void`	`clear()` Remove all data from this cache.
`void`	`close()` Free the resources used by this cache.
`void`	`commit(Collection<DataCachePCData> additions, Collection<DataCachePCData> newUpdates, Collection<DataCachePCData> existingUpdates, Collection<Object> deletes)` Perform a batch update of the cache.
`boolean`	`contains(Object oid)` Returns `true` if this cache contains data corresponding to `oid`; otherwise returns `false`.
`BitSet`	`containsAll(Collection<Object> oids)` Returns the indexes of the oids in this cache.
`DataCachePCData`	`get(Object oid)` Return the cached object for the given oid.
`Map<Object,DataCachePCData>`	`getAll(List<Object> keys)` Gets objects from the caches for a given list of keys.
`boolean`	`getEvictOnBulkUpdate()` Returns whether the the cache needs to be updated when bulk updates as executed.
`String`	`getName()` Returns a string name that can be used by end-user-visible code to identify this cache.
`DataCache`	`getPartition(String name, boolean create)` Gets the named partition.
`Set<String>`	`getPartitionNames()` Gets the name of the known partitions.
`CacheStatistics`	`getStatistics()` Returns number of read/write request and cache hit ratio data.
`void`	`initialize(DataCacheManager manager)` Initialize any resources associated with the given `DataCacheManager`.
`boolean`	`isPartitioned()` Affirms if this cache maintains partitions.
`boolean`	`pin(Object oid)` Pin the value stored under `oid` into the cache.
`void`	`pinAll(Class<?> cls, boolean subs)` Pin all oids for the given type.
`BitSet`	`pinAll(Collection<Object> oids)` Pin all oids to the cache.
`DataCachePCData`	`put(DataCachePCData value)` Set the cached value for the given instance.
`DataCachePCData`	`remove(Object oid)` Remove the value stored under the given oid.
`void`	`removeAll(Class<?> cls, boolean subclasses)` Evict all values of a specified type.
`BitSet`	`removeAll(Collection<Object> oids)` Remove the values stored under the given oids.
`boolean`	`removeExpirationListener(ExpirationListener listen)` Remove an expiration event listener from this cache.
`void`	`setName(String name)` Sets a string name to be used to identify this cache to end-user needs.
`boolean`	`unpin(Object oid)` Unpin the value stored under `oid` from the cache.
`void`	`unpinAll(Class<?> cls, boolean subs)` Unpin all oids associaed with the given type from the cache.
`BitSet`	`unpinAll(Collection<Object> oids)` Unpin all oids from the cache.
`void`	`update(DataCachePCData value)` Update the cached value for the given instance.
`void`	`writeLock()` Obtain a write lock on the cache.
`void`	`writeUnlock()` Release the write lock on the cache.

- Field Detail
  - NAME_DEFAULT
```
static final String NAME_DEFAULT
```
    The name of the default data cache: default
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getName
```
String getName()
```
    Returns a string name that can be used by end-user-visible code to identify this cache.
    
    Since:
    
    0.2.5.0
  - setName
```
void setName(String name)
```
    Sets a string name to be used to identify this cache to end-user needs.
    
    Since:
    
    0.2.5.0
  - initialize
```
void initialize(DataCacheManager manager)
```
    Initialize any resources associated with the given DataCacheManager.
  - commit
```
void commit(Collection<DataCachePCData> additions,
            Collection<DataCachePCData> newUpdates,
            Collection<DataCachePCData> existingUpdates,
            Collection<Object> deletes)
```
    Perform a batch update of the cache. Add all DataCachePCData objects in additions and in newUpdates, make the appropriate modifications to all DataCachePCDatas in existingUpdates, and delete all OIDs in deletes. All changes made to cached data must be made via this method. It is this method that is responsible for performing any side-effects that should happen on meaningful cache changes. Implementations should bear in mind that the deletes collection may contain oids that are also in the additions map. This is possible because it is valid for a user to delete an object with a particular oid and then add that object in the same batch.
    
    Parameters:
    
    additions - A collection of DataCachePCData objects. These represent data that have been newly created, and thus must be added to the cache.
    
    newUpdates - A collection of DataCachePCData objects. These represent data that have been modified but were not originally in the cache, and thus must be added to the cache.
    
    existingUpdates - A collection of DataCachePCData objects. These represent data that have been modified and were originally loaded from the cache. It is up to the cache implementation to decide if these values must be re-enlisted in the cache. Some caches may return live data from get(java.lang.Object) invocations, in which case these values need not be re-enlisted.
    
    deletes - A collection of object IDs that have been deleted and must therefore be dropped from the cache.
  - contains
```
boolean contains(Object oid)
```
    Returns true if this cache contains data corresponding to oid; otherwise returns false.
  - containsAll
```
BitSet containsAll(Collection<Object> oids)
```
    Returns the indexes of the oids in this cache.
  - get
```
DataCachePCData get(Object oid)
```
    Return the cached object for the given oid. Modifying the returned object may or may not change the cached value; the update(org.apache.openjpa.datacache.DataCachePCData) method should be used to re-cache any changed objects.
    
    Returns:
    
    the object matching the given oid, or null if none
  - put
```
DataCachePCData put(DataCachePCData value)
```
    Set the cached value for the given instance. This does not result in an update of other caches. Rather, it should only be used for loading clean data into the cache. Meaningful changes to the state of the cache should be made via the commit(java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<java.lang.Object>) method.
    
    Returns:
    
    The previously cached value, or null if the value was not previously cached. See Map.put(K, V) for more information.
  - update
```
void update(DataCachePCData value)
```
    Update the cached value for the given instance. This does not result in an update of other caches. Rather, it should only be used for loading clean data into the cache. Meaningful changes to the state of the cache should be made via the commit(java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<java.lang.Object>) method. A cache implementation may or may not return a live object from get(java.lang.Object) invocations. If an object retrieved from a get(java.lang.Object) operation needs to be updated, this method can be invoked instead of invoking put(org.apache.openjpa.datacache.DataCachePCData). The DataCache implementation can then make optimizations based on how its get(java.lang.Object) method works.
  - remove
```
DataCachePCData remove(Object oid)
```
    Remove the value stored under the given oid. This does not result in an update of other caches. Rather, it should only be used for removing data in the cache. Meaningful changes to the state of the cache should be made via the commit(java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<java.lang.Object>) method.
    
    Returns:
    
    The previously cached value, or null if the oid was not previously cached. See Map.remove(java.lang.Object) for more information.
  - removeAll
```
BitSet removeAll(Collection<Object> oids)
```
    Remove the values stored under the given oids.
    
    Returns:
    
    the indexes of the removed oids
    
    See Also:
    
    remove(java.lang.Object)
  - removeAll
```
void removeAll(Class<?> cls,
               boolean subclasses)
```
    Evict all values of a specified type.
  - clear
```
void clear()
```
    Remove all data from this cache. This does not result in an update of other caches. Rather, it should only be used for clearing the cache. Meaningful changes to the state of the cache should be made via the commit(java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<org.apache.openjpa.datacache.DataCachePCData>, java.util.Collection<java.lang.Object>) method.
    
    Specified by:
    
    clear in interface Clearable
  - pin
```
boolean pin(Object oid)
```
    Pin the value stored under oid into the cache. This method guarantees that oid's value will not be dropped by the caching algorithm. This method does not affect the behavior of remove(java.lang.Object).
    
    Returns:
    
    true if oid's value was pinned into the cache; false if the oid is not in the cache.
  - pinAll
```
BitSet pinAll(Collection<Object> oids)
```
    Pin all oids to the cache.
    
    Returns:
    
    the indexes of the pinned oids
    
    See Also:
    
    pin(java.lang.Object)
  - pinAll
```
void pinAll(Class<?> cls,
            boolean subs)
```
    Pin all oids for the given type.
    
    Parameters:
    
    subs - Whether to include subclasses.
  - unpin
```
boolean unpin(Object oid)
```
    Unpin the value stored under oid from the cache. This method reverses a previous invocation of pin(java.lang.Object). This method does not remove anything from the cache; it merely makes oid's value a candidate for flushing from the cache.
    
    Returns:
    
    true if oid's value was unpinned from the cache; false if the oid is not in the cache.
  - unpinAll
```
BitSet unpinAll(Collection<Object> oids)
```
    Unpin all oids from the cache.
    
    Returns:
    
    the indexes of the unpinned oids
    
    See Also:
    
    unpin(java.lang.Object)
  - unpinAll
```
void unpinAll(Class<?> cls,
              boolean subs)
```
    Unpin all oids associaed with the given type from the cache.
    
    Parameters:
    
    subs - Whether to include subclasses.
  - writeLock
```
void writeLock()
```
    Obtain a write lock on the cache.
  - writeUnlock
```
void writeUnlock()
```
    Release the write lock on the cache.
  - addExpirationListener
```
void addExpirationListener(ExpirationListener listen)
```
    Add a new expiration event listener to this cache.
    
    Since:
    
    0.2.5.0
  - removeExpirationListener
```
boolean removeExpirationListener(ExpirationListener listen)
```
    Remove an expiration event listener from this cache.
    
    Since:
    
    0.2.5.0
  - close
```
void close()
```
    Free the resources used by this cache.
    
    Specified by:
    
    close in interface Closeable
  - getAll
```
Map<Object,DataCachePCData> getAll(List<Object> keys)
```
    Gets objects from the caches for a given list of keys. The returned map has the same keys as the given keys. If the cache does not contain data for a specific key, the returned map still contains the key with a null value.
  - getPartition
```
DataCache getPartition(String name,
                       boolean create)
```
    Gets the named partition. Note that a partition itself is another cache.
    
    Parameters:
    
    name - name of the given partition.
    
    create - if true optionally create a new partition.
    
    Returns:
    
    a partition of the given name. Or null, if either no such partition exists or can not be created.
    
    Since:
    
    2.0.0
  - getPartitionNames
```
Set<String> getPartitionNames()
```
    Gets the name of the known partitions.
    
    Returns:
    
    empty set if no partition exists.
    
    Since:
    
    2.0.0
  - isPartitioned
```
boolean isPartitioned()
```
    Affirms if this cache maintains partitions.
    
    Since:
    
    2.0.0
  - getStatistics
```
CacheStatistics getStatistics()
```
    Returns number of read/write request and cache hit ratio data.
  - getEvictOnBulkUpdate
```
boolean getEvictOnBulkUpdate()
```
    Returns whether the the cache needs to be updated when bulk updates as executed. Defaults to true.

Interface DataCache

Field Summary

Method Summary

Field Detail

NAME_DEFAULT

Method Detail

getName

setName

initialize

commit

contains

containsAll

get

put

update

remove

removeAll

removeAll

clear

pin

pinAll

pinAll

unpin

unpinAll

unpinAll

writeLock

writeUnlock

addExpirationListener

removeExpirationListener

close

getAll

getPartition

getPartitionNames

isPartitioned

getStatistics

getEvictOnBulkUpdate