org.apache.openjpa.kernel
Interface FinderCache<K,V,R>

All Superinterfaces:

Configurable

All Known Implementing Classes:

FinderCacheImpl

public interface FinderCache<K,V,R>
extends Configurable

A cache to create and maintain finder queries. A finder query is a query to find instance of a given class by its primary identity. This cache maintains finder queries by generic identifier of parameterized type K. A cached query by an identifier of parameterized type K. A query can be cached by an identifier and value represented by parameterized type V. Caching results in creating a new instance of FinderQuery FQ from the value V such that FQ can be executed to return a result of parameterized type R. A request to cache may not be successful if this cache determines the value V to be not cachable. Both get() and put() operations can be controlled by the hints associated with FetchConfiguration. The target database query FQ associated to a cached finder query F may depend upon query execution context such as fetch plan or lock group. This cache, by design, does not monitor the context or automatically invalidate an entry when the original query F is executed with context parameters that affect the target query FQ. The user must notify this receiver to invalidate a cached entry when execution context changes in a way that will modify the resultant database language query FQ. One of the built-in mechanism (available in JPA facade) is to set query hints to either invalidate the query entirely or ignore the cached version for the current execution.

Since:

2.0.0

Author:

Pinaki Poddar

See Also:

QueryHints.HINT_IGNORE_FINDER, QueryHints.HINT_INVALIDATE_FINDER, This cache allows customization of whether a query can be cached or not via either explicit marking of certain classes as non-cachable (which is irreversible) or addition/removal of exclusion patterns (which is reversible)

Method Summary

void	addExclusionPattern(String pattern) Adds the given pattern to the list of excluded patterns.
FinderQuery<K,V,R>	cache(K key, V value, FetchConfiguration fetch) Cache a FinderQuery for the given key and value.
FinderQuery<K,V,R>	get(K key, FetchConfiguration fetch) Get the FinderQuery for the given key.
List<String>	getExcludes() Gets the excluded stringified keys.
Map<String,String>	getMapView() Get a map view of the cached entries as strings.
QueryStatistics<K>	getStatistics() Gets the simple statistics for executed finder queries.
boolean	invalidate(K key) Remove the FinderQuery for the given key from this cache.
boolean	isExcluded(K key) Affirms if the given key matches any of the exclusion patterns.
FinderQuery<K,V,R>	markUncachable(K key) Marks the given key as not amenable to caching.
void	removeExclusionPattern(String pattern) Removes the given pattern from the list of excluded patterns.

Methods inherited from interface org.apache.openjpa.lib.conf.Configurable

endConfiguration, setConfiguration, startConfiguration

Method Detail

get

FinderQuery<K,V,R> get(K key,
                       FetchConfiguration fetch)

Get the FinderQuery for the given key.

Parameters:

key - for which the finder is looked up

fecth - may contain hints to control lookup operation

Returns:

FinderQuery for the given mapping.

cache

FinderQuery<K,V,R> cache(K key,
                         V value,
                         FetchConfiguration fetch)

Cache a FinderQuery for the given key and value.

Parameters:

key - for which the finder is cached.

value - used to construct the finder query

fetch - may contain hints to control cache operation.

Returns:

the finder query that has been cached. It may be newly constructed or an existing query. If the given key-value can not be cached, then return null.

getMapView

Map<String,String> getMapView()

Get a map view of the cached entries as strings.

invalidate

boolean invalidate(K key)

Remove the FinderQuery for the given key from this cache.

markUncachable

FinderQuery<K,V,R> markUncachable(K key)

Marks the given key as not amenable to caching. Explicit marking helps to avoid repeated computational cost of determining whether finder for a key can be cached or not. Explicit marking can not be reversed by removal of exclusion patterns.

Returns:

finder query for the given class if it had been cached before. null otherwise.

isExcluded

boolean isExcluded(K key)

Affirms if the given key matches any of the exclusion patterns.

getExcludes

List<String> getExcludes()

Gets the excluded stringified keys.

addExclusionPattern

void addExclusionPattern(String pattern)

Adds the given pattern to the list of excluded patterns. Any existing cache entry whose key matches the given pattern will be marked non-cachable in a reversible manner.

removeExclusionPattern

void removeExclusionPattern(String pattern)

Removes the given pattern from the list of excluded patterns. Any excluded entry that matches the given pattern can now be cached again, unless it has been marked non-cachable explicitly.

getStatistics

QueryStatistics<K> getStatistics()

Gets the simple statistics for executed finder queries.