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

Package org.apache.lucene.index

# Class BaseCompositeReader<R extends IndexReader>

java.lang.Object
org.apache.lucene.index.IndexReader
org.apache.lucene.index.CompositeReader
org.apache.lucene.index.BaseCompositeReader<R>

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

Direct Known Subclasses:
  `DirectoryReader`, `MultiReader`, `ParallelCompositeReader`

public abstract class BaseCompositeReader<R extends IndexReader> extends CompositeReader
Base class for implementing `CompositeReader`s based on an array of sub-readers. The implementing class has to add code for correctly refcounting and closing the sub-readers.

User code will most likely use `MultiReader` to build a composite reader on a set of sub-readers (like several `DirectoryReader`s).

For efficiency, in this API documents are often referred to via document numbers, non-negative integers which each name a unique document in the index. These document numbers are ephemeral -- they may change as documents are added to and deleted from an index. Clients should thus not rely on a given document having the same number between sessions.

NOTE: `IndexReader` instances are completely thread safe, meaning multiple threads can call any of its methods, concurrently. If your application requires external synchronization, you should not synchronize on the `IndexReader` instance; use your own (non-Lucene) objects instead.

See Also:
  - `MultiReader`
NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- ## Nested Class Summary

  ## 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 Comparator<R>`
  `subReadersSorter`
  A comparator for sorting sub-readers

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `BaseCompositeReader(R[] subReaders, Comparator<R> subReadersSorter)`
  Constructs a `BaseCompositeReader` on the given subReaders.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final int`
  `docFreq(Term term)`
  Returns the number of documents containing the `term`.
  `final int`
  `getDocCount(String field)`
  Returns the number of documents that have at least one term for this field.
  `protected final List<? extends R>`
  `getSequentialSubReaders()`
  Expert: returns the sequential sub readers that this reader is logically composed of.
  `final long`
  `getSumDocFreq(String field)`
  Returns the sum of `TermsEnum.docFreq()` for all terms in this field.
  `final long`
  `getSumTotalTermFreq(String field)`
  Returns the sum of `TermsEnum.totalTermFreq()` for all terms in this field.
  `final int`
  `maxDoc()`
  Returns one greater than the largest possible document number.
  `final int`
  `numDocs()`
  Returns the number of documents in this index.
  `protected final int`
  `readerBase(int readerIndex)`
  Helper method for subclasses to get the docBase of the given sub-reader index.
  `protected final int`
  `readerIndex(int docID)`
  Helper method for subclasses to get the corresponding reader for a doc ID
  `final StoredFields`
  `storedFields()`
  Returns a `StoredFields` reader for the stored fields of this index.
  `final TermVectors`
  `termVectors()`
  Returns a `TermVectors` reader for the term vectors of this index.
  `final long`
  `totalTermFreq(Term term)`
  Returns the total number of occurrences of `term` across all documents (the sum of the freq() for each doc that has this term).

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

  `getContext, toString`

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

  `close, decRef, doClose, 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

  - ### subReadersSorter

    protected final Comparator<R extends IndexReader> subReadersSorter
    A comparator for sorting sub-readers

- ## Constructor Details

  - ### BaseCompositeReader

    protected BaseCompositeReader(R[] subReaders, Comparator<R> subReadersSorter) throws IOException
    Constructs a `BaseCompositeReader` on the given subReaders.
    Parameters:
      `subReaders` - the wrapped sub-readers. This array is returned by `getSequentialSubReaders()` and used to resolve the correct subreader for docID-based methods. Please note: This array is not cloned and not protected for modification, the subclass is responsible to do this.
      `subReadersSorter` - – a comparator for sorting sub readers. If not `null`, this comparator is used to sort sub readers, before using the for resolving doc IDs.
    Throws:
      `IOException`

- ## Method Details

  - ### termVectors

    public final TermVectors termVectors() throws IOException
    Description copied from class: `IndexReader`
    Returns a `TermVectors` reader for the term vectors of this index.

    This call never returns `null`, even if no term vectors were indexed. The returned instance should only be used by a single thread.

    Example:

         TopDocs hits = searcher.search(query, 10);
         TermVectors termVectors = reader.termVectors();
         for (ScoreDoc hit : hits.scoreDocs) {
           Fields vector = termVectors.get(hit.doc);
         }

    Specified by:
      `termVectors` in class `IndexReader`
    Throws:
      `IOException` - If there is a low-level IO error

  - ### numDocs

    public final int numDocs()
    Description copied from class: `IndexReader`
    Returns the number of documents in this index.

    NOTE: This operation may run in O(maxDoc). Implementations that can't return this number in constant-time should cache it.

    Specified by:
      `numDocs` in class `IndexReader`

  - ### maxDoc

    public final int maxDoc()
    Description copied from class: `IndexReader`
    Returns one greater than the largest possible document number. This may be used to, e.g., determine how big to allocate an array which will have an element for every document number in an index.
    Specified by:
      `maxDoc` in class `IndexReader`

  - ### storedFields

    public final StoredFields storedFields() throws IOException
    Description copied from class: `IndexReader`
    Returns a `StoredFields` reader for the stored fields of this index.

    This call never returns `null`, even if no stored fields were indexed. The returned instance should only be used by a single thread.

    Example:

         TopDocs hits = searcher.search(query, 10);
         StoredFields storedFields = reader.storedFields();
         for (ScoreDoc hit : hits.scoreDocs) {
           Document doc = storedFields.document(hit.doc);
         }

    Specified by:
      `storedFields` in class `IndexReader`
    Throws:
      `IOException` - If there is a low-level IO error

  - ### docFreq

    public final int docFreq(Term term) throws IOException
    Description copied from class: `IndexReader`
    Returns the number of documents containing the `term`. This method returns 0 if the term or field does not exists. This method does not take into account deleted documents that have not yet been merged away.
    Specified by:
      `docFreq` in class `IndexReader`
    Throws:
      `IOException`
    See Also:
      - `TermsEnum.docFreq()`

  - ### totalTermFreq

    public final long totalTermFreq(Term term) throws IOException
    Description copied from class: `IndexReader`
    Returns the total number of occurrences of `term` across all documents (the sum of the freq() for each doc that has this term). Note that, like other term measures, this measure does not take deleted documents into account.
    Specified by:
      `totalTermFreq` in class `IndexReader`
    Throws:
      `IOException`

  - ### getSumDocFreq

    public final long getSumDocFreq(String field) throws IOException
    Description copied from class: `IndexReader`
    Returns the sum of `TermsEnum.docFreq()` for all terms in this field. Note that, just like other term measures, this measure does not take deleted documents into account.
    Specified by:
      `getSumDocFreq` in class `IndexReader`
    Throws:
      `IOException`
    See Also:
      - `Terms.getSumDocFreq()`

  - ### getDocCount

    public final int getDocCount(String field) throws IOException
    Description copied from class: `IndexReader`
    Returns the number of documents that have at least one term for this field. Note that, just like other term measures, this measure does not take deleted documents into account.
    Specified by:
      `getDocCount` in class `IndexReader`
    Throws:
      `IOException`
    See Also:
      - `Terms.getDocCount()`

  - ### getSumTotalTermFreq

    public final long getSumTotalTermFreq(String field) throws IOException
    Description copied from class: `IndexReader`
    Returns the sum of `TermsEnum.totalTermFreq()` for all terms in this field. Note that, just like other term measures, this measure does not take deleted documents into account.
    Specified by:
      `getSumTotalTermFreq` in class `IndexReader`
    Throws:
      `IOException`
    See Also:
      - `Terms.getSumTotalTermFreq()`

  - ### readerIndex

    protected final int readerIndex(int docID)
    Helper method for subclasses to get the corresponding reader for a doc ID

  - ### readerBase

    protected final int readerBase(int readerIndex)
    Helper method for subclasses to get the docBase of the given sub-reader index.

  - ### getSequentialSubReaders

    protected final List<? extends R> getSequentialSubReaders()
    Description copied from class: `CompositeReader`
    Expert: returns the sequential sub readers that this reader is logically composed of. This method may not return `null`.

    NOTE: In contrast to previous Lucene versions this method is no longer public, code that wants to get all `LeafReader`s this composite is composed of should use `IndexReader.leaves()`.

    Specified by:
      `getSequentialSubReaders` in class `CompositeReader`
    See Also:
      - `IndexReader.leaves()`