org.apache.openjpa.datacache

Interface DataCache

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

Method Summary

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.