Package 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 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

        java.util.Map<java.lang.String,​java.lang.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

        java.util.List<java.lang.String> getExcludes()
        Gets the excluded stringified keys.

      • 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 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.