All Superinterfaces:

Configurable

All Known Implementing Classes:

PreparedQueryCacheImpl
```
public interface PreparedQueryCache
extends Configurable
```
A cache to create and maintain prepared queries. To cache a PreparedQuery is two-stage process. In the first stage, register(String, Query, FetchConfiguration) register} an identification key and a compiled Query Q to create a hollow PreparedQuery instance P in the cache. In the second stage, after Q executes, initialize(String, Object) initialize} the hollow Prepared Query P from the result of execution such as the target database query PQ and its parameters. After initialization, P can be used with re-parameterization for subsequent execution of the original Query Q. The target database query PQ associated to a cached prepared query P 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 P when the original query Q is executed with context parameters that affect the target query PQ. The user must notify this receiver to invalidate a cached entry P when execution context changes in a way that will modify the resultant database language query PQ. 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_PREPARED_QUERY, This cache allows customization of whether a query can be cached or not via either explicit marking of certain keys as non-cachable (which is irreversible or strong) or addition/removal of exclusion patterns (which is reversible or weak)., #markUncachable(String), addExclusionPattern(String), setExcludes(String), removeExclusionPattern(String)

Nested Class Summary

Nested Classes
Modifier and Type Interface Description

static interface PreparedQueryCache.Exclusion
A structure to describe the strength and reason for excluding a query from the cache.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`void`	`addExclusionPattern(java.lang.String pattern)`	Adds the given pattern to the list of excluded patterns.
`boolean`	`cache(PreparedQuery q)`	Cache the given PreparedQuery.
`void`	`clear()`	Clears all cached queries.
`PreparedQuery`	`get(java.lang.String id)`	Get the PreparedQuery with the given identifier if it exists. null otherwise.
`boolean`	`getEnableStatistics()`	Affirm if statistics is gathered.
`java.util.List<PreparedQueryCache.Exclusion>`	`getExcludes()`	Gets the exclusion patterns.
`java.util.Map<java.lang.String,java.lang.String>`	`getMapView()`	Get a map view of the cached queries indexed by identifier.
`QueryStatistics<java.lang.String>`	`getStatistics()`	Gets the simple statistics for executed queries.
`PreparedQuery`	`initialize(java.lang.String key, java.lang.Object executionResult)`	Initialize the cached Prepared Query registered with the given key earlier by the given execution result.
`boolean`	`invalidate(java.lang.String id)`	Remove the PreparedQuery with the given identifier from this cache.
`java.lang.Boolean`	`isCachable(java.lang.String id)`	Affirms if a PreparedQuery can be cached against the given key.
`PreparedQueryCache.Exclusion`	`isExcluded(java.lang.String id)`	Returns the exclusion status of if the given query key.
`PreparedQuery`	`markUncachable(java.lang.String id, PreparedQueryCache.Exclusion exclusion)`	Marks the given key as not amenable to caching.
`java.lang.Boolean`	`register(java.lang.String key, Query query, FetchConfiguration hints)`	Register the given query for caching against the given key if it has not already been cached.
`void`	`removeExclusionPattern(java.lang.String pattern)`	Removes the given pattern from the list of excluded patterns.
`void`	`setEnableStatistics(boolean enable)`	Enable/disable gathering of statistics.
`void`	`setExcludes(java.lang.String excludes)`	Sets one or more exclusion regular expression patterns separated by semicolon.

Methods inherited from interface org.apache.openjpa.lib.conf.Configurable
endConfiguration, setConfiguration, startConfiguration

- Method Detail
  - register
```
java.lang.Boolean register(java.lang.String key,
                           Query query,
                           FetchConfiguration hints)
```
    Register the given query for caching against the given key if it has not already been cached. If the query can not be cached, then mark it as such to avoid computing for the same key again.
    
    Returns:
    
    TRUE the query is registered in the cache by this call null if the query is already registered in the cache FALSE if can not be registered in the cache, either because it is known not to be cacheable from a previous attempt or a hint is given to ignore the cached version.
  - initialize
```
PreparedQuery initialize(java.lang.String key,
                         java.lang.Object executionResult)
```
    Initialize the cached Prepared Query registered with the given key earlier by the given execution result. If it is not possible to initialize the Prepared Query from the given execution result, then the corresponding key will be marked as invalid for caching.
    
    Parameters:
    
    key - the key used during registration
    
    executionResult - an opaque instance carrying the execution result of the original query.
    
    Returns:
    
    the initialized Prepared Query. If it is not possible to initialize the cached, possibly hollow Prepared Query from the given result, return null.
  - getMapView
```
java.util.Map<java.lang.String,java.lang.String> getMapView()
```
    Get a map view of the cached queries indexed by identifier.
  - cache
```
boolean cache(PreparedQuery q)
```
    Cache the given PreparedQuery. The key is the identifier of the given PreparedQuery itself. The query must not be cached if either the key matches any exclusion pattern or the key has been marked non-cachable.
    
    Returns:
    
    true if the given query is cached. false if it can not be cached due to exclusion.
    
    See Also:
    
    #markUncachable(String), setExcludes(String), addExclusionPattern(String)
  - invalidate
```
boolean invalidate(java.lang.String id)
```
    Remove the PreparedQuery with the given identifier from this cache.
  - get
```
PreparedQuery get(java.lang.String id)
```
    Get the PreparedQuery with the given identifier if it exists. null otherwise.
  - isCachable
```
java.lang.Boolean isCachable(java.lang.String id)
```
    Affirms if a PreparedQuery can be cached against the given key.
    
    Returns:
    
    Boolean.FALSE if the given key is explicitly marked before as not be cached or matches any of the exclusion patterns. Boolean.TRUE if the given key currently exists in the cache. Otherwise, return null implying this receiver can not determine whether this key can be cached on not.
  - markUncachable
```
PreparedQuery markUncachable(java.lang.String id,
                             PreparedQueryCache.Exclusion exclusion)
```
    Marks the given key as not amenable to caching. Explicit marking helps to avoid repeated computational cost of determining whether a query can be cached or not.
    
    Parameters:
    
    id - is the key to be excluded
    
    exclusion - directs whether exclusion is irreversible or not.
    
    Returns:
    
    The value for the given key if it had been cached before. null otherwise.
  - isExcluded
```
PreparedQueryCache.Exclusion isExcluded(java.lang.String id)
```
    Returns the exclusion status of if the given query key.
    
    Returns:
    
    null implies that the key is not excluded.
  - getExcludes
```
java.util.List<PreparedQueryCache.Exclusion> getExcludes()
```
    Gets the exclusion patterns.
  - setExcludes
```
void setExcludes(java.lang.String excludes)
```
    Sets one or more exclusion regular expression patterns separated by semicolon. Any existing cache entry whose key matches any of the given pattern will be marked non-cachable in a reversible manner.
  - addExclusionPattern
```
void addExclusionPattern(java.lang.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(java.lang.String pattern)
```
    Removes the given pattern from the list of excluded patterns. Any excluded key that matches the given pattern can now be cached again, unless it has been marked non-cachable explicitly.
    
    See Also:
    
    markUncachable(String, Exclusion)
  - clear
```
void clear()
```
    Clears all cached queries.
  - setEnableStatistics
```
void setEnableStatistics(boolean enable)
```
    Enable/disable gathering of statistics.
  - getEnableStatistics
```
boolean getEnableStatistics()
```
    Affirm if statistics is gathered.
  - getStatistics
```
QueryStatistics<java.lang.String> getStatistics()
```
    Gets the simple statistics for executed queries. If the statistics gathering is disabled, an empty statistics is returned.

Interface PreparedQueryCache

Nested Class Summary

Method Summary

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

Method Detail

register

initialize

getMapView

cache

invalidate

get

isCachable

markUncachable

isExcluded

getExcludes

setExcludes

addExclusionPattern

removeExclusionPattern

clear

setEnableStatistics

getEnableStatistics

getStatistics