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

Package org.apache.lucene.codecs

# Class PostingsFormat

java.lang.Object
org.apache.lucene.codecs.PostingsFormat

All Implemented Interfaces:
  `NamedSPILoader.NamedSPI`

Direct Known Subclasses:
  `Lucene104PostingsFormat`, `PerFieldPostingsFormat`

public abstract class PostingsFormat extends Object implements NamedSPILoader.NamedSPI
Encodes/decodes terms, postings, and proximity data.

Note, when extending this class, the name (`getName()`) may written into the index in certain configurations. In order for the segment to be read, the name must resolve to your implementation via `forName(String)`. This method uses Java's `Service Provider Interface` (SPI) to resolve format names.

If you implement your own format, make sure that it has a no-arg constructor so SPI can load it.

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final PostingsFormat[]`
  `EMPTY`
  Zero-length `PostingsFormat` array.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `PostingsFormat(String name)`
  Creates a new postings format.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Set<String>`
  `availablePostingsFormats()`
  returns a list of all available format names
  `abstract FieldsConsumer`
  `fieldsConsumer(SegmentWriteState state)`
  Writes a new segment
  `abstract FieldsProducer`
  `fieldsProducer(SegmentReadState state)`
  Reads a segment.
  `static PostingsFormat`
  `forName(String name)`
  looks up a format by name
  `final String`
  `getName()`
  Returns this posting format's name
  `static void`
  `reloadPostingsFormats(ClassLoader classloader)`
  Reloads the postings format list from the given `ClassLoader`.
  `String`
  `toString()`

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

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

- ## Field Details

  - ### EMPTY

    public static final PostingsFormat[] EMPTY
    Zero-length `PostingsFormat` array.

- ## Constructor Details

  - ### PostingsFormat

    protected PostingsFormat(String name)
    Creates a new postings format.

    The provided name will be written into the index segment in some configurations (such as when using `PerFieldPostingsFormat`): in such configurations, for the segment to be read this class should be registered with Java's SPI mechanism (registered in META-INF/ of your jar file, etc).

    Parameters:
      `name` - must be all ascii alphanumeric, and less than 128 characters in length.

- ## Method Details

  - ### getName

    public final String getName()
    Returns this posting format's name
    Specified by:
      `getName` in interface `NamedSPILoader.NamedSPI`

  - ### fieldsConsumer

    public abstract FieldsConsumer fieldsConsumer(SegmentWriteState state) throws IOException
    Writes a new segment
    Throws:
      `IOException`

  - ### fieldsProducer

    public abstract FieldsProducer fieldsProducer(SegmentReadState state) throws IOException
    Reads a segment. NOTE: by the time this call returns, it must hold open any files it will need to use; else, those files may be deleted. Additionally, required files may be deleted during the execution of this call before there is a chance to open them. Under these circumstances an IOException should be thrown by the implementation. IOExceptions are expected and will automatically cause a retry of the segment opening logic with the newly revised segments.
    Throws:
      `IOException`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### forName

    public static PostingsFormat forName(String name)
    looks up a format by name

  - ### availablePostingsFormats

    public static Set<String> availablePostingsFormats()
    returns a list of all available format names

  - ### reloadPostingsFormats

    public static void reloadPostingsFormats(ClassLoader classloader)
    Reloads the postings format list from the given `ClassLoader`. Changes to the postings formats are visible after the method ends, all iterators (`availablePostingsFormats()`,...) stay consistent.

    NOTE: Only new postings formats are added, existing ones are never removed or replaced.

    This method is expensive and should only be called for discovery of new postings formats on the given classpath/classloader!