org.apache.lucene.search

## Class LRUFilterCache

- java.lang.Object
- - org.apache.lucene.search.LRUFilterCache

- All Implemented Interfaces:
    FilterCache, Accountable

  Deprecated.
  Use `LRUQueryCache` instead

      @Deprecated
      public class LRUFilterCache
      extends Object
      implements FilterCache, Accountable

  A `FilterCache` that evicts filters using a LRU (least-recently-used) eviction policy in order to remain under a given maximum size and number of bytes used. This class is thread-safe. Note that filter eviction runs in linear time with the total number of segments that have cache entries so this cache works best with `caching policies` that only cache on "large" segments, and it is advised to not share this cache across too many indices. Typical usage looks like this:

         final int maxNumberOfCachedFilters = 256;
         final long maxRamBytesUsed = 50 * 1024L * 1024L; // 50MB
         // these cache and policy instances can be shared across several filters and readers
         // it is fine to eg. store them into static variables
         final FilterCache filterCache = new LRUFilterCache(maxNumberOfCachedFilters, maxRamBytesUsed);
         final FilterCachingPolicy defaultCachingPolicy = new UsageTrackingFilterCachingPolicy();

         // ...

         // Then at search time
         Filter myFilter = ...;
         Filter myCacheFilter = filterCache.doCache(myFilter, defaultCachingPolicy);
         // myCacheFilter is now a wrapper around the original filter that will interact with the cache
         IndexSearcher searcher = ...;
         TopDocs topDocs = searcher.search(new ConstantScoreQuery(myCacheFilter), 10);

  This cache exposes some global statistics (`hit count`, `miss count`, `number of cache entries`, `total number of DocIdSets that have ever been cached`, `number of evicted entries`). In case you would like to have more fine-grained statistics, such as per-index or per-filter-class statistics, it is possible to override various callbacks: `onHit(java.lang.Object, org.apache.lucene.search.Filter)`, `onMiss(java.lang.Object, org.apache.lucene.search.Filter)`, `onFilterCache(org.apache.lucene.search.Filter, long)`, `onFilterEviction(org.apache.lucene.search.Filter, long)`, `onDocIdSetCache(java.lang.Object, long)`, `onDocIdSetEviction(java.lang.Object, int, long)` and `onClear()`. It is better to not perform heavy computations in these methods though since they are called synchronously and under a lock.
  See Also:
    `FilterCachingPolicy`
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `LRUFilterCache(int maxSize, long maxRamBytesUsed)` Deprecated. Create a new instance that will cache at most `maxSize` filters with at most `maxRamBytesUsed` bytes of memory.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected DocIdSet` | `cacheImpl(DocIdSetIterator iterator, LeafReader reader)` Deprecated. Default cache implementation: uses `RoaringDocIdSet`.
    `void` | `clear()` Deprecated. Clear the content of this cache.
    `void` | `clearCoreCacheKey(Object coreKey)` Deprecated. Remove all cache entries for the given core cache key.
    `void` | `clearFilter(Filter filter)` Deprecated. Remove all cache entries for the given filter.
    `Filter` | `doCache(Filter filter, FilterCachingPolicy policy)` Deprecated. Return a wrapper around the provided `filter` that will cache `DocIdSet`s per-segment accordingly to the given `policy`.
    `protected DocIdSet` | `docIdSetToCache(DocIdSet docIdSet, LeafReader reader)` Deprecated. Provide the DocIdSet to be cached, using the DocIdSet provided by the wrapped Filter.
    `long` | `getCacheCount()` Deprecated. Return the total number of cache entries that have been generated and put in the cache.
    `long` | `getCacheSize()` Deprecated. Return the total number of `DocIdSet`s which are currently stored in the cache.
    `Collection<Accountable>` | `getChildResources()` Deprecated. Returns nested resources of this class.
    `long` | `getEvictionCount()` Deprecated. Return the number of cache entries that have been removed from the cache either in order to stay under the maximum configured size/ram usage, or because a segment has been closed.
    `long` | `getHitCount()` Deprecated. Over the `total` number of times that a filter has been looked up, return how many times a cached `DocIdSet` has been found and returned.
    `long` | `getMissCount()` Deprecated. Over the `total` number of times that a filter has been looked up, return how many times this filter was not contained in the cache.
    `long` | `getTotalCount()` Deprecated. Return the total number of times that a `Filter` has been looked up in this `FilterCache`.
    `protected void` | `onClear()` Deprecated. Expert: callback when the cache is completely cleared.
    `protected void` | `onDocIdSetCache(Object readerCoreKey, long ramBytesUsed)` Deprecated. Expert: callback when a `DocIdSet` is added to this cache.
    `protected void` | `onDocIdSetEviction(Object readerCoreKey, int numEntries, long sumRamBytesUsed)` Deprecated. Expert: callback when one or more `DocIdSet`s are removed from this cache.
    `protected void` | `onFilterCache(Filter filter, long ramBytesUsed)` Deprecated. Expert: callback when a filter is added to this cache.
    `protected void` | `onFilterEviction(Filter filter, long ramBytesUsed)` Deprecated. Expert: callback when a filter is evicted from this cache.
    `protected void` | `onHit(Object readerCoreKey, Filter filter)` Deprecated. Expert: callback when there is a cache hit on a given filter.
    `protected void` | `onMiss(Object readerCoreKey, Filter filter)` Deprecated. Expert: callback when there is a cache miss on a given filter.
    `long` | `ramBytesUsed()` Deprecated. Return the memory usage of this object in bytes.
    `protected long` | `ramBytesUsed(Filter filter)` Deprecated. Return the number of bytes used by the given filter.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### LRUFilterCache

          public LRUFilterCache(int maxSize,
                        long maxRamBytesUsed)

      Deprecated.
      Create a new instance that will cache at most `maxSize` filters with at most `maxRamBytesUsed` bytes of memory.

  - ### Method Detail

    - #### onHit

          protected void onHit(Object readerCoreKey,
                   Filter filter)

      Deprecated.
      Expert: callback when there is a cache hit on a given filter. Implementing this method is typically useful in order to compute more fine-grained statistics about the filter cache.
      See Also:
        `onMiss(java.lang.Object, org.apache.lucene.search.Filter)`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### onMiss

          protected void onMiss(Object readerCoreKey,
                    Filter filter)

      Deprecated.
      Expert: callback when there is a cache miss on a given filter.
      See Also:
        `onHit(java.lang.Object, org.apache.lucene.search.Filter)`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### onFilterCache

          protected void onFilterCache(Filter filter,
                           long ramBytesUsed)

      Deprecated.
      Expert: callback when a filter is added to this cache. Implementing this method is typically useful in order to compute more fine-grained statistics about the filter cache.
      See Also:
        `onFilterEviction(org.apache.lucene.search.Filter, long)`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### onFilterEviction

          protected void onFilterEviction(Filter filter,
                              long ramBytesUsed)

      Deprecated.
      Expert: callback when a filter is evicted from this cache.
      See Also:
        `onFilterCache(org.apache.lucene.search.Filter, long)`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### onDocIdSetCache

          protected void onDocIdSetCache(Object readerCoreKey,
                             long ramBytesUsed)

      Deprecated.
      Expert: callback when a `DocIdSet` is added to this cache. Implementing this method is typically useful in order to compute more fine-grained statistics about the filter cache.
      See Also:
        `onDocIdSetEviction(java.lang.Object, int, long)`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### onDocIdSetEviction

          protected void onDocIdSetEviction(Object readerCoreKey,
                                int numEntries,
                                long sumRamBytesUsed)

      Deprecated.
      Expert: callback when one or more `DocIdSet`s are removed from this cache.
      See Also:
        `onDocIdSetCache(java.lang.Object, long)`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### onClear

          protected void onClear()

      Deprecated.
      Expert: callback when the cache is completely cleared.
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### clearCoreCacheKey

          public void clearCoreCacheKey(Object coreKey)

      Deprecated.
      Remove all cache entries for the given core cache key.

    - #### clearFilter

          public void clearFilter(Filter filter)

      Deprecated.
      Remove all cache entries for the given filter.

    - #### clear

          public void clear()

      Deprecated.
      Clear the content of this cache.

    - #### doCache

          public Filter doCache(Filter filter,
                       FilterCachingPolicy policy)

      Deprecated.
      Description copied from interface: `FilterCache`
      Return a wrapper around the provided `filter` that will cache `DocIdSet`s per-segment accordingly to the given `policy`.
      Specified by:
        `doCache` in interface `FilterCache`

    - #### docIdSetToCache

          protected DocIdSet docIdSetToCache(DocIdSet docIdSet,
                                 LeafReader reader)
                                      throws IOException

      Deprecated.
      Provide the DocIdSet to be cached, using the DocIdSet provided by the wrapped Filter.

      This implementation returns the given `DocIdSet`, if `DocIdSet.isCacheable()` returns `true`, else it calls `cacheImpl(DocIdSetIterator, org.apache.lucene.index.LeafReader)`

      Note: This method returns DocIdSet.EMPTY if the given docIdSet is `null` or if `DocIdSet.iterator()` return `null`. The empty instance is use as a placeholder in the cache instead of the `null` value.

      Throws:
        `IOException`

    - #### ramBytesUsed

          public long ramBytesUsed()

      Deprecated.
      Description copied from interface: `Accountable`
      Return the memory usage of this object in bytes. Negative values are illegal.
      Specified by:
        `ramBytesUsed` in interface `Accountable`

    - #### getChildResources

          public Collection<Accountable> getChildResources()

      Deprecated.
      Description copied from interface: `Accountable`
      Returns nested resources of this class. The result should be a point-in-time snapshot (to avoid race conditions).
      Specified by:
        `getChildResources` in interface `Accountable`
      See Also:
        `Accountables`

    - #### ramBytesUsed

          protected long ramBytesUsed(Filter filter)

      Deprecated.
      Return the number of bytes used by the given filter. The default implementation returns `Accountable.ramBytesUsed()` if the filter implements `Accountable` and `1024` otherwise.

    - #### cacheImpl

          protected DocIdSet cacheImpl(DocIdSetIterator iterator,
                           LeafReader reader)
                                throws IOException

      Deprecated.
      Default cache implementation: uses `RoaringDocIdSet`.
      Throws:
        `IOException`

    - #### getTotalCount

          public final long getTotalCount()

      Deprecated.
      Return the total number of times that a `Filter` has been looked up in this `FilterCache`. Note that this number is incremented once per segment so running a cached filter only once will increment this counter by the number of segments that are wrapped by the searcher. Note that by definition, `getTotalCount()` is the sum of `getHitCount()` and `getMissCount()`.
      See Also:
        `getHitCount()`, `getMissCount()`

    - #### getHitCount

          public final long getHitCount()

      Deprecated.
      Over the `total` number of times that a filter has been looked up, return how many times a cached `DocIdSet` has been found and returned.
      See Also:
        `getTotalCount()`, `getMissCount()`

    - #### getMissCount

          public final long getMissCount()

      Deprecated.
      Over the `total` number of times that a filter has been looked up, return how many times this filter was not contained in the cache.
      See Also:
        `getTotalCount()`, `getHitCount()`

    - #### getCacheSize

          public final long getCacheSize()

      Deprecated.
      Return the total number of `DocIdSet`s which are currently stored in the cache.
      See Also:
        `getCacheCount()`, `getEvictionCount()`

    - #### getCacheCount

          public final long getCacheCount()

      Deprecated.
      Return the total number of cache entries that have been generated and put in the cache. It is highly desirable to have a `hit count` that is much higher than the `cache count` as the opposite would indicate that the filter cache makes efforts in order to cache filters but then they do not get reused.
      See Also:
        `getCacheSize()`, `getEvictionCount()`

    - #### getEvictionCount

          public final long getEvictionCount()

      Deprecated.
      Return the number of cache entries that have been removed from the cache either in order to stay under the maximum configured size/ram usage, or because a segment has been closed. High numbers of evictions might mean that filters are not reused or that the `caching policy` caches too aggressively on NRT segments which get merged early.
      See Also:
        `getCacheCount()`, `getCacheSize()`

Copyright © 2000-2017 Apache Software Foundation. All Rights Reserved.