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

Package org.apache.lucene.util

# Class OfflineSorter

java.lang.Object
org.apache.lucene.util.OfflineSorter

public class OfflineSorter extends Object
On-disk sorting of byte arrays. Each byte array (entry) is composed of the following fields:

- (two bytes) length of the following byte array,
- exactly the above count of bytes for the sequence to be sorted.

See Also:
  - `sort(String)`
WARNING: This API is experimental and might change in incompatible ways in the next release.
NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `OfflineSorter.BufferSize`
  A bit more descriptive unit for constructors.
  `static class`
  `OfflineSorter.ByteSequencesReader`
  Utility class to read length-prefixed byte[] entries from an input.
  `static class`
  `OfflineSorter.ByteSequencesWriter`
  Utility class to emit length-prefixed byte[] entries to an output stream for sorting.
  `class`
  `OfflineSorter.SortInfo`
  Sort info (debugging mostly).

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final long`
  `ABSOLUTE_MIN_SORT_BUFFER_SIZE`
  Absolute minimum required buffer size for sorting.
  `static final Comparator<BytesRef>`
  `DEFAULT_COMPARATOR`
  Default comparator: sorts in binary (codepoint) order
  `static final long`
  `GB`
  Convenience constant for gigabytes
  `static final int`
  `MAX_TEMPFILES`
  Maximum number of temporary files before doing an intermediate merge.
  `static final long`
  `MB`
  Convenience constant for megabytes
  `static final long`
  `MIN_BUFFER_SIZE_MB`
  Minimum recommended buffer size for sorting.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `OfflineSorter(Directory dir, String tempFileNamePrefix)`
  Defaults constructor.
  `OfflineSorter(Directory dir, String tempFileNamePrefix, Comparator<BytesRef> comparator)`
  Defaults constructor with a custom comparator.
  `OfflineSorter(Directory dir, String tempFileNamePrefix, Comparator<BytesRef> comparator, OfflineSorter.BufferSize ramBufferSize, int maxTempfiles, int valueLength, ExecutorService exec, int maxPartitionsInRAM)`
  All-details constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Comparator<BytesRef>`
  `getComparator()`
  Returns the comparator in use to sort entries
  `Directory`
  `getDirectory()`
  Returns the `Directory` we use to create temp files.
  `protected OfflineSorter.ByteSequencesReader`
  `getReader(ChecksumIndexInput in, String name)`
  Subclasses can override to change how byte sequences are read from disk.
  `String`
  `getTempFileNamePrefix()`
  Returns the temp file name prefix passed to `Directory.createTempOutput(java.lang.String, java.lang.String, org.apache.lucene.store.IOContext)` to generate temporary files.
  `protected OfflineSorter.ByteSequencesWriter`
  `getWriter(IndexOutput out, long itemCount)`
  Subclasses can override to change how byte sequences are written to disk.
  `String`
  `sort(String inputFileName)`
  Sort input to a new temp file, returning its name.

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

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

- ## Field Details

  - ### MB

    public static final long MB
    Convenience constant for megabytes
    See Also:
      - Constant Field Values

  - ### GB

    public static final long GB
    Convenience constant for gigabytes
    See Also:
      - Constant Field Values

  - ### MIN_BUFFER_SIZE_MB

    public static final long MIN_BUFFER_SIZE_MB
    Minimum recommended buffer size for sorting.
    See Also:
      - Constant Field Values

  - ### ABSOLUTE_MIN_SORT_BUFFER_SIZE

    public static final long ABSOLUTE_MIN_SORT_BUFFER_SIZE
    Absolute minimum required buffer size for sorting.
    See Also:
      - Constant Field Values

  - ### MAX_TEMPFILES

    public static final int MAX_TEMPFILES
    Maximum number of temporary files before doing an intermediate merge.
    See Also:
      - Constant Field Values

  - ### DEFAULT_COMPARATOR

    public static final Comparator<BytesRef> DEFAULT_COMPARATOR
    Default comparator: sorts in binary (codepoint) order

- ## Constructor Details

  - ### OfflineSorter

    public OfflineSorter(Directory dir, String tempFileNamePrefix) throws IOException
    Defaults constructor.
    Throws:
      `IOException`
    See Also:
      - `OfflineSorter.BufferSize.automatic()`

  - ### OfflineSorter

    public OfflineSorter(Directory dir, String tempFileNamePrefix, Comparator<BytesRef> comparator) throws IOException
    Defaults constructor with a custom comparator.
    Throws:
      `IOException`
    See Also:
      - `OfflineSorter.BufferSize.automatic()`

  - ### OfflineSorter

    public OfflineSorter(Directory dir, String tempFileNamePrefix, Comparator<BytesRef> comparator, OfflineSorter.BufferSize ramBufferSize, int maxTempfiles, int valueLength, ExecutorService exec, int maxPartitionsInRAM)
    All-details constructor. If `valueLength` is -1 (the default), the length of each value differs; otherwise, all values have the specified length. If you pass a non-null `ExecutorService` then it will be used to run sorting operations that can be run concurrently, and maxPartitionsInRAM is the maximum concurrent in-memory partitions. Thus the maximum possible RAM used by this class while sorting is `maxPartitionsInRAM * ramBufferSize`.

- ## Method Details

  - ### getDirectory

    public Directory getDirectory()
    Returns the `Directory` we use to create temp files.

  - ### getTempFileNamePrefix

    public String getTempFileNamePrefix()
    Returns the temp file name prefix passed to `Directory.createTempOutput(java.lang.String, java.lang.String, org.apache.lucene.store.IOContext)` to generate temporary files.

  - ### sort

    public String sort(String inputFileName) throws IOException
    Sort input to a new temp file, returning its name.
    Throws:
      `IOException`

  - ### getWriter

    protected OfflineSorter.ByteSequencesWriter getWriter(IndexOutput out, long itemCount) throws IOException
    Subclasses can override to change how byte sequences are written to disk.
    Throws:
      `IOException`

  - ### getReader

    protected OfflineSorter.ByteSequencesReader getReader(ChecksumIndexInput in, String name) throws IOException
    Subclasses can override to change how byte sequences are read from disk.
    Throws:
      `IOException`

  - ### getComparator

    public Comparator<BytesRef> getComparator()
    Returns the comparator in use to sort entries