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

Package org.apache.lucene.index

# Class FilterDirectoryReader

java.lang.Object
org.apache.lucene.index.IndexReader
org.apache.lucene.index.CompositeReader
org.apache.lucene.index.BaseCompositeReader<LeafReader>
org.apache.lucene.index.DirectoryReader
org.apache.lucene.index.FilterDirectoryReader

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

Direct Known Subclasses:
  `ExitableDirectoryReader`, `SoftDeletesDirectoryReaderWrapper`

public abstract class FilterDirectoryReader extends DirectoryReader
A FilterDirectoryReader wraps another DirectoryReader, allowing implementations to transform or extend it.

Subclasses should implement doWrapDirectoryReader to return an instance of the subclass.

If the subclass wants to wrap the DirectoryReader's subreaders, it should also implement a SubReaderWrapper subclass, and pass an instance to its super constructor.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `FilterDirectoryReader.DelegatingCacheHelper`
  A DelegatingCacheHelper is a CacheHelper specialization for implementing long-lived caching behaviour for FilterDirectoryReader subclasses.
  `static class`
  `FilterDirectoryReader.SubReaderWrapper`
  Factory class passed to FilterDirectoryReader constructor that allows subclasses to wrap the filtered DirectoryReader's subreaders.

  ## Nested classes/interfaces inherited from class org.apache.lucene.index.IndexReader

  `IndexReader.CacheHelper, IndexReader.CacheKey, IndexReader.ClosedListener`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final DirectoryReader`
  `in`
  The filtered DirectoryReader

  ### Fields inherited from class org.apache.lucene.index.DirectoryReader

  `directory`

  ### Fields inherited from class org.apache.lucene.index.BaseCompositeReader

  `subReadersSorter`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FilterDirectoryReader(DirectoryReader in, FilterDirectoryReader.SubReaderWrapper wrapper)`
  Create a new FilterDirectoryReader that filters a passed in DirectoryReader, using the supplied SubReaderWrapper to wrap its subreader.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `doClose()`
  Implements close.
  `protected final DirectoryReader`
  `doOpenIfChanged()`
  Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader)`.
  `protected final DirectoryReader`
  `doOpenIfChanged(ExecutorService executorService)`
  Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader)`.
  `protected final DirectoryReader`
  `doOpenIfChanged(IndexCommit commit)`
  Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader,IndexCommit)`.
  `protected final DirectoryReader`
  `doOpenIfChanged(IndexCommit commit, ExecutorService executorService)`
  Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader,IndexCommit)`.
  `protected final DirectoryReader`
  `doOpenIfChanged(IndexWriter writer, boolean applyAllDeletes)`
  Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader,IndexWriter,boolean)`.
  `protected final DirectoryReader`
  `doOpenIfChanged(IndexWriter writer, boolean applyAllDeletes, ExecutorService executorService)`
  Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader,IndexWriter,boolean)`.
  `protected abstract DirectoryReader`
  `doWrapDirectoryReader(DirectoryReader in)`
  Called by the doOpenIfChanged() methods to return a new wrapped DirectoryReader.
  `DirectoryReader`
  `getDelegate()`
  Returns the wrapped `DirectoryReader`.
  `IndexCommit`
  `getIndexCommit()`
  Expert: return the IndexCommit that this reader has opened.
  `long`
  `getVersion()`
  Version number when this IndexReader was opened.
  `boolean`
  `isCurrent()`
  Check whether any new changes have occurred to the index since this reader was opened.
  `static DirectoryReader`
  `unwrap(DirectoryReader reader)`
  Get the wrapped instance by `reader` as long as this reader is an instance of `FilterDirectoryReader`.

  ### Methods inherited from class org.apache.lucene.index.DirectoryReader

  `directory, indexExists, listCommits, open, open, open, open, open, open, open, open, open, open, openIfChanged, openIfChanged, openIfChanged, openIfChanged, openIfChanged, openIfChanged, openIfChanged, openIfChanged`

  ### Methods inherited from class org.apache.lucene.index.BaseCompositeReader

  `docFreq, getDocCount, getSequentialSubReaders, getSumDocFreq, getSumTotalTermFreq, maxDoc, numDocs, readerBase, readerIndex, storedFields, termVectors, totalTermFreq`

  ### Methods inherited from class org.apache.lucene.index.CompositeReader

  `getContext, toString`

  ### Methods inherited from class org.apache.lucene.index.IndexReader

  `close, decRef, ensureOpen, equals, getReaderCacheHelper, getRefCount, hasDeletions, hashCode, incRef, leaves, notifyReaderClosedListeners, numDeletedDocs, registerParentReader, tryIncRef`

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

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

- ## Field Details

  - ### in

    protected final DirectoryReader in
    The filtered DirectoryReader

- ## Constructor Details

  - ### FilterDirectoryReader

    public FilterDirectoryReader(DirectoryReader in, FilterDirectoryReader.SubReaderWrapper wrapper) throws IOException
    Create a new FilterDirectoryReader that filters a passed in DirectoryReader, using the supplied SubReaderWrapper to wrap its subreader.
    Parameters:
      `in` - the DirectoryReader to filter
      `wrapper` - the SubReaderWrapper to use to wrap subreaders
    Throws:
      `IOException`

- ## Method Details

  - ### unwrap

    public static DirectoryReader unwrap(DirectoryReader reader)
    Get the wrapped instance by `reader` as long as this reader is an instance of `FilterDirectoryReader`.

  - ### doWrapDirectoryReader

    protected abstract DirectoryReader doWrapDirectoryReader(DirectoryReader in) throws IOException
    Called by the doOpenIfChanged() methods to return a new wrapped DirectoryReader.

    Implementations should just return an instantiation of themselves, wrapping the passed in DirectoryReader.

    Parameters:
      `in` - the DirectoryReader to wrap
    Returns:
      the wrapped DirectoryReader
    Throws:
      `IOException`

  - ### doOpenIfChanged

    protected final DirectoryReader doOpenIfChanged() throws IOException
    Description copied from class: `DirectoryReader`
    Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader)`. If this reader does not support reopen, return `null`, so client code is happy. This should be consistent with `DirectoryReader.isCurrent()` (should always return `true`) if reopen is not supported.
    Specified by:
      `doOpenIfChanged` in class `DirectoryReader`
    Returns:
      null if there are no changes; else, a new DirectoryReader instance.
    Throws:
      `IOException` - if there is a low-level IO error

  - ### doOpenIfChanged

    protected final DirectoryReader doOpenIfChanged(ExecutorService executorService) throws IOException
    Description copied from class: `DirectoryReader`
    Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader)`. If this reader does not support reopen, return `null`, so client code is happy. This should be consistent with `DirectoryReader.isCurrent()` (should always return `true`) if reopen is not supported. ExecutorService provides intra-opening concurrency.
    Specified by:
      `doOpenIfChanged` in class `DirectoryReader`
    Returns:
      null if there are no changes; else, a new DirectoryReader instance.
    Throws:
      `IOException` - if there is a low-level IO error

  - ### doOpenIfChanged

    protected final DirectoryReader doOpenIfChanged(IndexCommit commit) throws IOException
    Description copied from class: `DirectoryReader`
    Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader,IndexCommit)`. If this reader does not support reopen from a specific `IndexCommit`, throw `UnsupportedOperationException`.
    Specified by:
      `doOpenIfChanged` in class `DirectoryReader`
    Returns:
      null if there are no changes; else, a new DirectoryReader instance.
    Throws:
      `IOException` - if there is a low-level IO error

  - ### doOpenIfChanged

    protected final DirectoryReader doOpenIfChanged(IndexCommit commit, ExecutorService executorService) throws IOException
    Description copied from class: `DirectoryReader`
    Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader,IndexCommit)`. If this reader does not support reopen from a specific `IndexCommit`, throw `UnsupportedOperationException`. ExecutorService provides intra-opening concurrency.
    Specified by:
      `doOpenIfChanged` in class `DirectoryReader`
    Returns:
      null if there are no changes; else, a new DirectoryReader instance.
    Throws:
      `IOException` - if there is a low-level IO error

  - ### doOpenIfChanged

    protected final DirectoryReader doOpenIfChanged(IndexWriter writer, boolean applyAllDeletes) throws IOException
    Description copied from class: `DirectoryReader`
    Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader,IndexWriter,boolean)`. If this reader does not support reopen from `IndexWriter`, throw `UnsupportedOperationException`.
    Specified by:
      `doOpenIfChanged` in class `DirectoryReader`
    Returns:
      null if there are no changes; else, a new DirectoryReader instance.
    Throws:
      `IOException` - if there is a low-level IO error

  - ### doOpenIfChanged

    protected final DirectoryReader doOpenIfChanged(IndexWriter writer, boolean applyAllDeletes, ExecutorService executorService) throws IOException
    Description copied from class: `DirectoryReader`
    Implement this method to support `DirectoryReader.openIfChanged(DirectoryReader,IndexWriter,boolean)`. If this reader does not support reopen from `IndexWriter`, throw `UnsupportedOperationException`. ExecutorService used to open segment readers in parallel.
    Specified by:
      `doOpenIfChanged` in class `DirectoryReader`
    Returns:
      null if there are no changes; else, a new DirectoryReader instance.
    Throws:
      `IOException` - if there is a low-level IO error

  - ### getVersion

    public long getVersion()
    Description copied from class: `DirectoryReader`
    Version number when this IndexReader was opened.

    This method returns the version recorded in the commit that the reader opened. This version is advanced every time a change is made with `IndexWriter`.

    Specified by:
      `getVersion` in class `DirectoryReader`

  - ### isCurrent

    public boolean isCurrent() throws IOException
    Description copied from class: `DirectoryReader`
    Check whether any new changes have occurred to the index since this reader was opened.

    If this reader was created by calling `DirectoryReader.open(org.apache.lucene.store.Directory)`, then this method checks if any further commits (see `IndexWriter.commit()`) have occurred in the directory.

    If instead this reader is a near real-time reader (ie, obtained by a call to `DirectoryReader.open(IndexWriter)`, or by calling `DirectoryReader.openIfChanged(org.apache.lucene.index.DirectoryReader)` on a near real-time reader), then this method checks if either a new commit has occurred, or any new uncommitted changes have taken place via the writer. Note that even if the writer has only performed merging, this method will still return false.

    In any event, if this returns false, you should call `DirectoryReader.openIfChanged(org.apache.lucene.index.DirectoryReader)` to get a new reader that sees the changes.

    Specified by:
      `isCurrent` in class `DirectoryReader`
    Throws:
      `IOException` - if there is a low-level IO error

  - ### getIndexCommit

    public IndexCommit getIndexCommit() throws IOException
    Description copied from class: `DirectoryReader`
    Expert: return the IndexCommit that this reader has opened.
    Specified by:
      `getIndexCommit` in class `DirectoryReader`
    Throws:
      `IOException`

  - ### doClose

    protected void doClose() throws IOException
    Description copied from class: `IndexReader`
    Implements close.
    Specified by:
      `doClose` in class `IndexReader`
    Throws:
      `IOException`

  - ### getDelegate

    public DirectoryReader getDelegate()
    Returns the wrapped `DirectoryReader`.