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

Package org.apache.lucene.util

# Class PagedBytes

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

All Implemented Interfaces:
  `Accountable`

public final class PagedBytes extends Object implements Accountable
Represents a logical byte[] as a series of pages. You can write-once into the logical byte[] (append only), using copy, and then retrieve slices (BytesRef) into it using fill.

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
  `final class`
  `PagedBytes.PagedBytesDataInput`
  Input that transparently iterates over pages
  `final class`
  `PagedBytes.PagedBytesDataOutput`
  Output that transparently spills to new pages as necessary
  `static final class`
  `PagedBytes.Reader`
  Provides methods to read BytesRefs from a frozen PagedBytes.

- ## Field Summary

  ### Fields inherited from interface org.apache.lucene.util.Accountable

  `NULL_ACCOUNTABLE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PagedBytes(int blockBits)`
  1<<blockBits must be bigger than biggest single BytesRef slice that will be pulled

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `copy(IndexInput in, long byteCount)`
  Read this many bytes from in
  `void`
  `copy(BytesRef bytes, BytesRef out)`
  Copy BytesRef in, setting BytesRef out to the result.
  `long`
  `copyUsingLengthPrefix(BytesRef bytes)`
  Copy bytes in, writing the length as a 1 or 2 byte vInt prefix.
  `PagedBytes.Reader`
  `freeze(boolean trim)`
  Commits final byte[], trimming it if necessary and if trim=true
  `PagedBytes.PagedBytesDataInput`
  `getDataInput()`
  Returns a DataInput to read values from this PagedBytes instance.
  `PagedBytes.PagedBytesDataOutput`
  `getDataOutput()`
  Returns a DataOutput that you may use to write into this PagedBytes instance.
  `long`
  `getPointer()`
  `long`
  `ramBytesUsed()`
  Returns an estimate of the JVM heap memory used by this object in bytes.

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

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

  ### Methods inherited from interface org.apache.lucene.util.Accountable

  `getChildResources`

- ## Constructor Details

  - ### PagedBytes

    public PagedBytes(int blockBits)
    1<<blockBits must be bigger than biggest single BytesRef slice that will be pulled

- ## Method Details

  - ### copy

    public void copy(IndexInput in, long byteCount) throws IOException
    Read this many bytes from in
    Throws:
      `IOException`

  - ### copy

    public void copy(BytesRef bytes, BytesRef out)
    Copy BytesRef in, setting BytesRef out to the result. Do not use this if you will use freeze(true). This only supports bytes.length <= blockSize

  - ### freeze

    public PagedBytes.Reader freeze(boolean trim)
    Commits final byte[], trimming it if necessary and if trim=true

  - ### getPointer

    public long getPointer()

  - ### ramBytesUsed

    public long ramBytesUsed()
    Description copied from interface: `Accountable`
    Returns an estimate of the JVM heap memory used by this object in bytes. The method name uses "ram" for historical reasons; only JVM heap memory should be reported. Off-heap resources such as memory-mapped files or native direct buffers should not be included. Negative values are illegal.
    Specified by:
      `ramBytesUsed` in interface `Accountable`

  - ### copyUsingLengthPrefix

    public long copyUsingLengthPrefix(BytesRef bytes)
    Copy bytes in, writing the length as a 1 or 2 byte vInt prefix.

  - ### getDataInput

    public PagedBytes.PagedBytesDataInput getDataInput()
    Returns a DataInput to read values from this PagedBytes instance.

  - ### getDataOutput

    public PagedBytes.PagedBytesDataOutput getDataOutput()
    Returns a DataOutput that you may use to write into this PagedBytes instance. If you do this, you should not call the other writing methods (eg, copy); results are undefined.