SearcherManager (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.search, class: SearcherManager

Package org.apache.lucene.search

# Class SearcherManager

java.lang.Object
org.apache.lucene.search.ReferenceManager<IndexSearcher>
org.apache.lucene.search.SearcherManager

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public final class SearcherManager extends ReferenceManager<IndexSearcher>
Utility class to safely share `IndexSearcher` instances across multiple threads, while periodically reopening. This class ensures each searcher is closed only once all threads have finished using it.

Use `ReferenceManager.acquire()` to obtain the current searcher, and `ReferenceManager.release(G)` to release it, like this:

     IndexSearcher s = manager.acquire();
     try {
       // Do searching, doc retrieval, etc. with s
     } finally {
       manager.release(s);
     }
     // Do not use s after this!
     s = null;

In addition you should periodically call `ReferenceManager.maybeRefresh()`. While it's possible to call this just before running each query, this is discouraged since it penalizes the unlucky queries that need to refresh. It's better to use a separate background thread, that periodically calls `ReferenceManager.maybeRefresh()`. Finally, be sure to call `ReferenceManager.close()` once you are done.

See Also:
  - `SearcherFactory`
WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.search.ReferenceManager

  `ReferenceManager.RefreshListener`

- ## Field Summary

  ### Fields inherited from class org.apache.lucene.search.ReferenceManager

  `current`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SearcherManager(DirectoryReader reader, SearcherFactory searcherFactory)`
  Creates and returns a new SearcherManager from an existing `DirectoryReader`.
  `SearcherManager(DirectoryReader reader, SearcherFactory searcherFactory, RefreshCommitSupplier refreshCommitSupplier)`
  Creates and returns a new SearcherManager from an existing `DirectoryReader`.
  `SearcherManager(IndexWriter writer, boolean applyAllDeletes, boolean writeAllDeletes, SearcherFactory searcherFactory)`
  Expert: creates and returns a new SearcherManager from the given `IndexWriter`, controlling whether past deletions should be applied.
  `SearcherManager(IndexWriter writer, boolean applyAllDeletes, boolean writeAllDeletes, SearcherFactory searcherFactory, RefreshCommitSupplier refreshCommitSupplier)`
  Expert: creates and returns a new SearcherManager from the given `IndexWriter`, controlling whether past deletions should be applied.
  `SearcherManager(IndexWriter writer, SearcherFactory searcherFactory)`
  Creates and returns a new SearcherManager from the given `IndexWriter`.
  `SearcherManager(Directory dir, SearcherFactory searcherFactory)`
  Creates and returns a new SearcherManager from the given `Directory`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `decRef(IndexSearcher reference)`
  Decrement reference counting on the given reference.
  `protected int`
  `getRefCount(IndexSearcher reference)`
  Returns the current reference count of the given reference.
  `static IndexSearcher`
  `getSearcher(SearcherFactory searcherFactory, IndexReader reader, IndexReader previousReader)`
  Expert: creates a searcher from the provided `IndexReader` using the provided `SearcherFactory`.
  `protected IndexSearcher`
  `refreshIfNeeded(IndexSearcher referenceToRefresh)`
  Refresh the given reference if needed.
  `protected boolean`
  `tryIncRef(IndexSearcher reference)`
  Try to increment reference counting on the given reference.

  ### Methods inherited from class org.apache.lucene.search.ReferenceManager

  `acquire, addListener, afterClose, afterMaybeRefresh, close, maybeRefresh, maybeRefreshBlocking, release, removeListener`

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

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

- ## Constructor Details

  - ### SearcherManager

    public SearcherManager(IndexWriter writer, SearcherFactory searcherFactory) throws IOException
    Creates and returns a new SearcherManager from the given `IndexWriter`.
    Parameters:
      `writer` - the IndexWriter to open the IndexReader from.
      `searcherFactory` - An optional `SearcherFactory`. Pass `null` if you don't require the searcher to be warmed before going live or other custom behavior.
    Throws:
      `IOException` - if there is a low-level I/O error

  - ### SearcherManager

    public SearcherManager(IndexWriter writer, boolean applyAllDeletes, boolean writeAllDeletes, SearcherFactory searcherFactory) throws IOException
    Expert: creates and returns a new SearcherManager from the given `IndexWriter`, controlling whether past deletions should be applied.
    Parameters:
      `writer` - the IndexWriter to open the IndexReader from.
      `applyAllDeletes` - If `true`, all buffered deletes will be applied (made visible) in the `IndexSearcher` / `DirectoryReader`. If `false`, the deletes may or may not be applied, but remain buffered (in IndexWriter) so that they will be applied in the future. Applying deletes can be costly, so if your app can tolerate deleted documents being returned you might gain some performance by passing `false` . See `DirectoryReader.openIfChanged(DirectoryReader, IndexWriter, boolean)`.
      `writeAllDeletes` - If `true`, new deletes will be forcefully written to index files.
      `searcherFactory` - An optional `SearcherFactory`. Pass `null` if you don't require the searcher to be warmed before going live or other custom behavior.
    Throws:
      `IOException` - if there is a low-level I/O error

  - ### SearcherManager

    public SearcherManager(IndexWriter writer, boolean applyAllDeletes, boolean writeAllDeletes, SearcherFactory searcherFactory, RefreshCommitSupplier refreshCommitSupplier) throws IOException
    Expert: creates and returns a new SearcherManager from the given `IndexWriter`, controlling whether past deletions should be applied.
    Parameters:
      `writer` - the IndexWriter to open the IndexReader from.
      `applyAllDeletes` - If `true`, all buffered deletes will be applied (made visible) in the `IndexSearcher` / `DirectoryReader`. If `false`, the deletes may or may not be applied, but remain buffered (in IndexWriter) so that they will be applied in the future. Applying deletes can be costly, so if your app can tolerate deleted documents being returned you might gain some performance by passing `false` . See `DirectoryReader.openIfChanged(DirectoryReader, IndexWriter, boolean)`.
      `writeAllDeletes` - If `true`, new deletes will be forcefully written to index files.
      `searcherFactory` - An optional `SearcherFactory`. Pass `null` if you don't require the searcher to be warmed before going live or other custom behavior.
      `refreshCommitSupplier` - supplier for providing the commit to refresh on
    Throws:
      `IOException` - if there is a low-level I/O error

  - ### SearcherManager

    public SearcherManager(Directory dir, SearcherFactory searcherFactory) throws IOException
    Creates and returns a new SearcherManager from the given `Directory`.
    Parameters:
      `dir` - the directory to open the DirectoryReader on.
      `searcherFactory` - An optional `SearcherFactory`. Pass `null` if you don't require the searcher to be warmed before going live or other custom behavior.
    Throws:
      `IOException` - if there is a low-level I/O error

  - ### SearcherManager

    public SearcherManager(DirectoryReader reader, SearcherFactory searcherFactory) throws IOException
    Creates and returns a new SearcherManager from an existing `DirectoryReader`. Note that this steals the incoming reference.
    Parameters:
      `reader` - the DirectoryReader.
      `searcherFactory` - An optional `SearcherFactory`. Pass `null` if you don't require the searcher to be warmed before going live or other custom behavior.
    Throws:
      `IOException` - if there is a low-level I/O error

  - ### SearcherManager

    public SearcherManager(DirectoryReader reader, SearcherFactory searcherFactory, RefreshCommitSupplier refreshCommitSupplier) throws IOException
    Creates and returns a new SearcherManager from an existing `DirectoryReader`. Note that this steals the incoming reference.
    Parameters:
      `reader` - the DirectoryReader.
      `searcherFactory` - An optional `SearcherFactory`. Pass `null` if you don't require the searcher to be warmed before going live or other custom behavior.
      `refreshCommitSupplier` - supplier for providing the commit to refresh on
    Throws:
      `IOException` - if there is a low-level I/O error

- ## Method Details

  - ### decRef

    protected void decRef(IndexSearcher reference) throws IOException
    Description copied from class: `ReferenceManager`
    Decrement reference counting on the given reference.
    Specified by:
      `decRef` in class `ReferenceManager<IndexSearcher>`
    Throws:
      `IOException` - if reference decrement on the given resource failed.

  - ### refreshIfNeeded

    protected IndexSearcher refreshIfNeeded(IndexSearcher referenceToRefresh) throws IOException
    Description copied from class: `ReferenceManager`
    Refresh the given reference if needed. Returns `null` if no refresh was needed, otherwise a new refreshed reference.
    Specified by:
      `refreshIfNeeded` in class `ReferenceManager<IndexSearcher>`
    Throws:
      `IOException` - if the refresh operation failed

  - ### tryIncRef

    protected boolean tryIncRef(IndexSearcher reference)
    Description copied from class: `ReferenceManager`
    Try to increment reference counting on the given reference. Return true if the operation was successful.
    Specified by:
      `tryIncRef` in class `ReferenceManager<IndexSearcher>`

  - ### getRefCount

    protected int getRefCount(IndexSearcher reference)
    Description copied from class: `ReferenceManager`
    Returns the current reference count of the given reference.
    Specified by:
      `getRefCount` in class `ReferenceManager<IndexSearcher>`

  - ### getSearcher

    public static IndexSearcher getSearcher(SearcherFactory searcherFactory, IndexReader reader, IndexReader previousReader) throws IOException
    Expert: creates a searcher from the provided `IndexReader` using the provided `SearcherFactory`. NOTE: this decRefs incoming reader on throwing an exception.
    Throws:
      `IOException`