Package org.apache.lucene.search

## Class CachingCollector

- java.lang.Object
- - org.apache.lucene.search.FilterCollector
  - - org.apache.lucene.search.CachingCollector

- All Implemented Interfaces:
    `Collector`

      public abstract class CachingCollector
      extends FilterCollector

  Caches all docs, and optionally also scores, coming from a search, and is then able to replay them to another collector. You specify the max RAM this class may use. Once the collection is done, call `isCached()`. If this returns true, you can use `replay(Collector)` against a new collector. If it returns false, this means too much RAM was required and you must instead re-run the original search.

  NOTE: this class consumes 4 (or 8 bytes, if scoring is cached) per collected document. If the result set is large this can easily be a very substantial amount of RAM!

  See the Lucene `modules/grouping` module for more details including a full code example.

  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Field Summary

    - ### Fields inherited from class org.apache.lucene.search.FilterCollector

      `in`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static CachingCollector` | `create​(boolean cacheScores, double maxRAMMB)` | Creates a `CachingCollector` which does not wrap another collector.
    `static CachingCollector` | `create​(Collector other, boolean cacheScores, double maxRAMMB)` | Create a new `CachingCollector` that wraps the given collector and caches documents and scores up to the specified RAM threshold.
    `static CachingCollector` | `create​(Collector other, boolean cacheScores, int maxDocsToCache)` | Create a new `CachingCollector` that wraps the given collector and caches documents and scores up to the specified max docs threshold.
    `boolean` | `isCached()` | Return true is this collector is able to replay collection.
    `abstract void` | `replay​(Collector other)` | Replays the cached doc IDs (and scores) to the given Collector.

    - ### Methods inherited from class org.apache.lucene.search.FilterCollector

      `getLeafCollector, scoreMode, setWeight, toString`

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

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

- - ### Method Detail

    - #### create

          public static CachingCollector create​(boolean cacheScores,
                                                double maxRAMMB)

      Creates a `CachingCollector` which does not wrap another collector. The cached documents and scores can later be `replayed`.

    - #### create

          public static CachingCollector create​(Collector other,
                                                boolean cacheScores,
                                                double maxRAMMB)

      Create a new `CachingCollector` that wraps the given collector and caches documents and scores up to the specified RAM threshold.
      Parameters:
        `other` - the Collector to wrap and delegate calls to.
        `cacheScores` - whether to cache scores in addition to document IDs. Note that this increases the RAM consumed per doc
        `maxRAMMB` - the maximum RAM in MB to consume for caching the documents and scores. If the collector exceeds the threshold, no documents and scores are cached.

    - #### create

          public static CachingCollector create​(Collector other,
                                                boolean cacheScores,
                                                int maxDocsToCache)

      Create a new `CachingCollector` that wraps the given collector and caches documents and scores up to the specified max docs threshold.
      Parameters:
        `other` - the Collector to wrap and delegate calls to.
        `cacheScores` - whether to cache scores in addition to document IDs. Note that this increases the RAM consumed per doc
        `maxDocsToCache` - the maximum number of documents for caching the documents and possible the scores. If the collector exceeds the threshold, no documents and scores are cached.

    - #### isCached

          public final boolean isCached()

      Return true is this collector is able to replay collection.

    - #### replay

          public abstract void replay​(Collector other)
                               throws IOException

      Replays the cached doc IDs (and scores) to the given Collector. If this instance does not cache scores, then Scorer is not set on `other.setScorer` as well as scores are not replayed.
      Throws:
        `IllegalStateException` - if this collector is not cached (i.e., if the RAM limits were too low for the number of documents + scores to cache).
        `IllegalArgumentException` - if the given Collect's does not support out-of-order collection, while the collector passed to the ctor does.
        `IOException`