Справочник API Scala

PDF Oxide поставляется с идиоматичными привязками Scala 3 в виде тонкого, чисто JVM-фасада поверх зрелой Java-привязки fyi.oxide:pdf-oxide, которой принадлежит единственный нативный мост JNI (крейт pdf_oxide_jni). Модуль Scala не добавляет никакого нативного кода: он напрямую использует Java-типы (Pdf, PdfDocument, PdfPage, DocumentEditor, AutoExtractor, PdfSigner, PdfValidator и типы значений geometry/text/table/search) и накладывает поверх них методы-расширения Scala 3, которые превращают java.util.Optional[T] в Option[T], а java.util.List[T] — в Seq[T]. scala.util.Using сразу работает с любым ресурсом AutoCloseable.

// build.sbt — cross-versioned for Scala 3 (resolves pdf-oxide-scala_3)
libraryDependencies += "fyi.oxide" %% "pdf-oxide-scala" % "0.3.69"

Нативная библиотека JNI (libpdf_oxide_jni) не поставляется в комплекте. Сделайте её доступной для загрузки через System.loadLibrary("pdf_oxide_jni") в java.library.path, либо укажите Java-классу NativeLoader путь к ней через -Dfyi.oxide.pdf.lib.path=<path>.

import fyi.oxide.pdf.{Pdf, PdfDocument, producerOption, wordsSeq}
import scala.util.Using

Using.resource(Pdf.fromMarkdown("# Hello\n\nbody\n")): pdf =>
  Using.resource(PdfDocument.open(pdf.save())): doc =>
    println(doc.pageCount())
    println(doc.extractText(0))
    println(doc.toMarkdown())
    println(doc.page(0).wordsSeq.map(_.text))       // List -> Seq
    println(doc.producerOption.getOrElse("(none)")) // Optional -> Option

Информацию о Java API см. в Справочнике API Java. Информацию о Rust API см. в Справочнике API Rust. Подробности о типах см. в разделе Типы и перечисления.

---

Pdf

fyi.oxide.pdf.Pdf — создание новых PDF из исходных форматов и разбиение существующих. Реализует AutoCloseable.

Фабричные методы

def fromMarkdown(markdown: String): Pdf

Создать PDF из содержимого Markdown.

def fromHtml(html: String): Pdf

Создать PDF из содержимого HTML.

def fromImages(images: java.util.List[Array[Byte]]): Pdf

Создать многостраничный PDF, по одной странице на изображение (байты JPEG/PNG).

Разбиение

def planSplitByBookmarks(opts: SplitByBookmarksOptions): java.util.List[BookmarkSegment]

Спланировать разбиение по закладкам без формирования байтов; возвращает сегменты, которые были бы созданы.

def splitByBookmarks(opts: SplitByBookmarksOptions): java.util.List[Array[Byte]]

Разбить документ по границам закладок, возвращая по одному массиву байтов PDF на каждый сегмент.

def planSplitByBookmarksCount(sourcePdf: Array[Byte], level: Int): Int

Статический вспомогательный метод: подсчитать, сколько сегментов даст разбиение по закладкам на заданном уровне оглавления.

def splitByBookmarksFromBytes(sourcePdf: Array[Byte], level: Int): Array[Array[Byte]]

Статический вспомогательный метод: разбить байты исходного PDF на заданном уровне оглавления на массивы байтов по сегментам.

Сохранение и жизненный цикл

def save(): Array[Byte]
def saveTo(out: java.nio.file.Path): Unit
def isOpen(): Boolean
def close(): Unit

Сериализовать PDF в байты или в файл по пути, проверить, активен ли нативный дескриптор, и освободить его.

---

PdfDocument

fyi.oxide.pdf.PdfDocument — открытие, извлечение, рендеринг и запросы к PDF. Реализует AutoCloseable.

Открытие

def open(path: java.nio.file.Path): PdfDocument
def open(path: String): PdfDocument
def open(bytes: Array[Byte]): PdfDocument
def open(path: java.nio.file.Path, password: String): PdfDocument
def open(path: String, password: String): PdfDocument
def open(bytes: Array[Byte], password: String): PdfDocument
def open(stream: java.io.InputStream): PdfDocument

Открыть PDF из файлового пути, байтов в памяти или входного потока. Перегрузки с паролем расшифровывают зашифрованные документы за один шаг.

Статическое извлечение

def extractText(path: String): String
def extractText(path: java.nio.file.Path): String

Однократное удобное действие: открыть файл, извлечь весь текст и закрыть его.

Информация о документе и аутентификация

def pageCount(): Int
def authenticate(password: String): Boolean
def authenticate(password: Array[Byte]): Boolean
def isOpen(): Boolean
def close(): Unit

Количество страниц, аутентификация после открытия для зашифрованных PDF (строкой или сырыми байтами), проверка активности дескриптора и освобождение ресурсов.

Метаданные

def producer(): java.util.Optional[String]
def creator(): java.util.Optional[String]

Строки producer / creator документа. Используйте фасадные producerOption / creatorOption для идиоматичного Option[String].

Извлечение текста

def extractText(pageIndex: Int): String
def extractTextAuto(pageIndex: Int): String
def extractStructured(page: Int): String

Извлечь обычный текст страницы, текст с автоматическим переходом на OCR для сканированных страниц или структурированное представление в формате JSON. Страницы индексируются с нуля.

Конвертация

def toMarkdown(): String
def toMarkdown(pageIndex: Int): String
def toHtml(): String
def toHtml(pageIndex: Int): String

Преобразовать весь документ или отдельную страницу в Markdown или HTML.

Рендеринг

def render(pageIndex: Int): Array[Byte]
def render(pageIndex: Int, dpi: Int): Array[Byte]

Растрировать страницу в байты PNG, опционально с заданным DPI.

Страницы и поиск

def page(index: Int): PdfPage
def pages(): java.util.List[PdfPage]
def pagesStream(): java.util.stream.Stream[PdfPage]
def formFields(): java.util.List[FormField]
def search(query: String): java.util.List[SearchMatch]
def search(query: String, caseInsensitive: Boolean, regex: Boolean, maxResults: Int): java.util.List[SearchMatch]

Получить дескриптор отдельной страницы, все страницы (в виде списка или потока), все поля AcroForm и совпадения поиска по документу. maxResults = 0 означает отсутствие ограничения. Используйте фасадные pagesSeq, formFieldsSeq и searchSeq для получения результатов в виде Scala Seq.

---

PdfPage

fyi.oxide.pdf.PdfPage — дескриптор отдельной страницы, возвращаемый PdfDocument.page / pages.

Геометрия

def parent(): PdfDocument
def index(): Int
def mediaBox(): BBox
def cropBox(): BBox
def width(): Double
def height(): Double
def rotation(): Int

Владеющий документ, индекс с нуля, прямоугольники MediaBox / CropBox, размеры страницы в пунктах и поворот в градусах.

Извлечение содержимого

def text(): String
def text(region: BBox): String
def words(): java.util.List[TextWord]
def lines(): java.util.List[TextLine]
def chars(): java.util.List[TextChar]
def images(): java.util.List[ExtractedImage]
def tables(): java.util.List[Table]
def annotations(): java.util.List[Annotation]

Текст всей страницы или ограниченной области, а также структурированные слова, строки, символы, изображения, таблицы и аннотации. Используйте фасадные wordsSeq, linesSeq, charsSeq, imagesSeq, tablesSeq и annotationsSeq для получения Scala Seq.

---

DocumentEditor

fyi.oxide.pdf.DocumentEditor — заполнение форм, редактирование (redaction), очистка метаданных и сохранение (инкрементальное или полное). Реализует AutoCloseable. Методы-сеттеры цепочные и возвращают this.

Открытие

def open(path: java.nio.file.Path): DocumentEditor
def open(path: String): DocumentEditor
def open(bytes: Array[Byte]): DocumentEditor

Формы

def setFormField(name: String, value: String): DocumentEditor
def setFormField(name: String, checked: Boolean): DocumentEditor

Установить значение текстового/выборного поля или переключить состояние флажка/радиокнопки.

Редактирование (Redaction)

def addRedaction(pageIndex: Int, region: BBox): DocumentEditor
def redactionCount(pageIndex: Int): Int
def redactionCount(): Int
def applyRedactionsDestructive(): RedactResult

Поставить в очередь прямоугольник редактирования, подсчитать ожидающие редактирования по странице или в целом, и применить их деструктивно (удалив исходное содержимое), вернув RedactResult.

Метаданные и сохранение

def scrubMetadata(): DocumentEditor
def save(): Array[Byte]
def saveTo(out: java.nio.file.Path): Unit
def saveIncremental(): Array[Byte]
def saveIncrementalTo(out: java.nio.file.Path): Unit
def isOpen(): Boolean
def close(): Unit

Удалить идентифицирующие метаданные, затем сохранить полностью перезаписанный или инкрементально дополненный PDF в байты или на диск.

---

AutoExtractor

fyi.oxide.pdf.AutoExtractor — интеллектуальное извлечение, которое классифицирует страницы и при необходимости переходит на OCR.

Конструирование

def of(doc: PdfDocument): AutoExtractor
def of(doc: PdfDocument, config: AutoExtractConfig): AutoExtractor
def fast(doc: PdfDocument): AutoExtractor
def balanced(doc: PdfDocument): AutoExtractor
def highFidelity(doc: PdfDocument): AutoExtractor

Создать экстрактор со стандартной, пользовательской или предустановленной (fast / balanced / high-fidelity) конфигурацией.

Извлечение

def extractText(): String
def extractTextForPage(pageIndex: Int): String
def extractDocument(): AutoResult
def extractPage(pageIndex: Int): AutoResult
def extractAutoDocument(): AutoResult
def extractAutoPage(pageIndex: Int): AutoResult
def extractDocumentJson(): String
def extractPageJson(pageIndex: Int): String

Извлечь обычный текст или подробные записи AutoResult (текст, опциональные Markdown/HTML, степень уверенности, использование OCR, регионы) для всего документа или отдельной страницы, а также варианты в формате JSON.

Классификация и аксессоры

def classifyDocument(): ClassifyResult
def classifyPage(pageIndex: Int): ClassifyResult
def document(): PdfDocument
def config(): AutoExtractConfig

Классифицировать страницы (текстовый слой / сканированная / смешанная, а также списки страниц с OCR/диаграммами/шифрованием) без извлечения, и получить исходный документ и конфигурацию.

---

MarkdownConverter

fyi.oxide.pdf.MarkdownConverter — статические вспомогательные методы конвертации в Markdown/HTML.

def toMarkdown(doc: PdfDocument): String
def toMarkdown(doc: PdfDocument, pageIndex: Int): String
def toHtml(doc: PdfDocument): String
def toHtml(doc: PdfDocument, pageIndex: Int): String

Преобразовать весь документ или отдельную страницу в Markdown или HTML.

---

PdfSigner

fyi.oxide.pdf.PdfSigner — цифровая подпись и проверка PAdES / CMS.

def fromPkcs12(keystore: java.nio.file.Path, password: String): PdfSigner
def fromPkcs12(keystoreBytes: Array[Byte], password: String): PdfSigner
def sign(pdf: Array[Byte], opts: SignOptions): Array[Byte]
def verify(pdf: Array[Byte]): Boolean
def classifyLevel(pdf: Array[Byte]): SignatureLevel

Загрузить подписант из хранилища ключей PKCS#12 (файла или байтов), подписать PDF с заданными SignOptions, проверить существующую подпись и статически классифицировать уровень PAdES подписанного PDF.

---

PdfValidator

fyi.oxide.pdf.PdfValidator — проверки соответствия PDF/A, PDF/X и PDF/UA.

def isPdfA(doc: PdfDocument, level: PdfALevel): Boolean
def isPdfUa(doc: PdfDocument, level: PdfUaLevel): Boolean
def validatePdfA(doc: PdfDocument, level: PdfALevel): ValidationResult
def validatePdfX(doc: PdfDocument, level: PdfXLevel): ValidationResult
def validatePdfUa(doc: PdfDocument, level: PdfUaLevel): ValidationResult

Быстрые булевы проверки, а также полные отчёты ValidationResult (с нарушениями по каждому правилу) для PDF/A, PDF/X и PDF/UA.

---

PdfPolicy

fyi.oxide.pdf.PdfPolicy — глобальный режим криптографической политики.

def current(): PolicyMode
def set(mode: PolicyMode): Unit
def compat(): PolicyMode
def strict(): PolicyMode
def fipsStrict(): PolicyMode

Прочитать или установить общепроцессный режим политики, а также получить доступ к пресетам COMPAT / STRICT / FIPS_STRICT.

---

Результирующие типы и типы значений

AutoResult

def text(): String
def markdown(): java.util.Optional[String]   // facade: markdownOption
def html(): java.util.Optional[String]       // facade: htmlOption
def reason(): ExtractReason
def confidence(): Double
def ocrUsed(): Boolean
def regions(): java.util.List[RegionResult]
def pagesNeedingOcr(): java.util.List[Integer]  // facade: pagesNeedingOcrSeq

RegionResult

def pageIndex(): Int
def bbox(): BBox
def text(): String
def reason(): ExtractReason
def confidence(): Double
def ocrUsed(): Boolean
def table(): java.util.Optional[Table]

ClassifyResult

def pages(): java.util.List[PageClass]
def pagesNeedingOcr(): java.util.List[Integer]
def pagesWithChart(): java.util.List[Integer]
def pagesEncrypted(): java.util.List[Integer]

AutoExtractConfig

Неизменяемая конфигурация, создаётся через AutoExtractConfig.builder() (или .toBuilder()). Аксессоры возвращают Optional:

def builder(): AutoExtractConfig.Builder
def toBuilder(): AutoExtractConfig.Builder
def mode(): java.util.Optional[ExtractMode]
def forceOcrPages(): java.util.Optional[java.util.List[Integer]]
def minOcrConfidence(): java.util.Optional[Double]
def ocrLanguages(): java.util.Optional[java.util.List[String]]
def passwords(): java.util.Optional[java.util.List[String]]
def topMarginFraction(): java.util.Optional[Double]
def bottomMarginFraction(): java.util.Optional[Double]
def allowSingleColumnTables(): java.util.Optional[Boolean]
def ocrInlineImages(): java.util.Optional[Boolean]
def cancelToken(): java.util.Optional[String]

AutoExtractConfig.Builder:

def withMode(m: ExtractMode): Builder
def withForceOcrPages(p: java.util.List[Integer]): Builder
def withMinOcrConfidence(c: Double): Builder
def withOcrLanguages(l: java.util.List[String]): Builder
def withOcrLanguages(l: String*): Builder
def withPasswords(p: java.util.List[String]): Builder
def withPasswords(p: String*): Builder
def withTopMarginFraction(f: Double): Builder
def withBottomMarginFraction(f: Double): Builder
def withAllowSingleColumnTables(b: Boolean): Builder
def withOcrInlineImages(b: Boolean): Builder
def withCancelToken(t: String): Builder
def build(): AutoExtractConfig

ValidationResult / ValidationViolation

// ValidationResult
def valid(): Boolean
def violations(): java.util.List[ValidationViolation]

// ValidationViolation
def ruleId(): String
def description(): String
def pageIndex(): java.util.Optional[Integer]  // facade: pageIndexOption

RedactResult

def regionsApplied(): Int
def oracleVerified(): Boolean

SearchResult / SearchMatch / SearchOptions

// SearchResult
def query(): String
def matches(): java.util.List[SearchMatch]
def count(): Int
def isEmpty(): Boolean

// SearchMatch
def pageIndex(): Int
def bbox(): BBox
def text(): String

// SearchOptions (builder via SearchOptions.builder())
def caseSensitive(): Boolean
def wholeWord(): Boolean
def regex(): Boolean
def maxResults(): java.util.Optional[Integer]

SearchOptions.Builder: withCaseSensitive(b: Boolean), withWholeWord(b: Boolean), withRegex(b: Boolean), withMaxResults(m: Int), build().

FormField

def name(): String
def type(): FormFieldType
def value(): java.util.Optional[String]   // facade: valueOption
def bbox(): java.util.Optional[BBox]       // facade: bboxOption
def pageIndex(): Int

Annotation

def `type`(): AnnotationType
def pageIndex(): Int
def bbox(): BBox
def contents(): java.util.Optional[String]  // facade: contentsOption
def uri(): java.util.Optional[String]        // facade: uriOption

ExtractedImage

def bytes(): Array[Byte]
def format(): ImageFormat
def bbox(): BBox
def width(): Int
def height(): Int

Table / TableCell

// Table
def bbox(): BBox
def rows(): Int
def cols(): Int
def cells(): java.util.List[TableCell]

// TableCell
def text(): String
def bbox(): BBox
def row(): Int
def col(): Int
def rowSpan(): Int
def colSpan(): Int

Текстовые типы

// TextWord
def text(): String
def bbox(): BBox
def confidence(): Float

// TextLine
def text(): String
def bbox(): BBox
def words(): java.util.List[TextWord]

// TextChar
def codepoint(): Int
def bbox(): BBox
def confidence(): Float
def asString(): String

// TextSpan
def text(): String
def bbox(): BBox
def style(): TextStyle

// TextStyle
def size(): Double
def color(): Color
def bold(): Boolean
def italic(): Boolean

Геометрия

// BBox(x0, y0, x1, y1)
def x0(): Double
def y0(): Double
def x1(): Double
def y1(): Double
def width(): Double
def height(): Double

// Color(r, g, b[, a])
def r(): Int
def g(): Int
def b(): Int
def a(): Int

// Point(x, y)
def x(): Double
def y(): Double

// Rect(x, y, width, height)
def x(): Double
def y(): Double
def width(): Double
def height(): Double
def toBBox(): BBox

Метаданные

// DocumentInfo — all accessors return Optional[String]
def title(); def author(); def subject(); def keywords()
def creator(); def producer(); def creationDate(); def modificationDate()

// XmpMetadata(xml: String)
def xml(): String
def isEmpty(): Boolean

Опции подписи и разбиения

// SignOptions (builder via SignOptions.builder())
def level(): SignatureLevel
def reason(): java.util.Optional[String]
def location(): java.util.Optional[String]
def contactInfo(): java.util.Optional[String]
def tsaUrl(): java.util.Optional[String]
// Builder: withLevel, withReason, withLocation, withContactInfo, withTsaUrl, build

// SplitByBookmarksOptions (builder via SplitByBookmarksOptions.builder())
def level(): Int
def filenamePrefix(): java.util.Optional[String]
// Builder: withLevel(l: Int), withFilenamePrefix(p: String), build

// BookmarkSegment
def title(): String
def firstPage(): Int
def lastPage(): Int
def filename(): String

SecurityPolicy

def mode(): PolicyMode
def additionalAllow(): java.util.List[String]
def additionalDeny(): java.util.List[String]
def builder(): SecurityPolicy.Builder
// Builder: withMode(m: PolicyMode), allow(algId: String), deny(algId: String), build

---

Перечисления

Перечисление	Константы
AnnotationType	HIGHLIGHT, TEXT, LINK, STAMP, UNDERLINE, STRIKEOUT, SQUIGGLY, FREE_TEXT, LINE, SQUARE, CIRCLE, FILE_ATTACHMENT
FormFieldType	TEXT, CHECKBOX, RADIO, CHOICE, SIGNATURE
ImageFormat	JPEG, PNG, JBIG2, JPEG2000, CCITT, RAW
ExtractMode	TEXT_ONLY, AUTO
ExtractReason	OK, SCANNED_NO_TEXT_LAYER, GLYPH_MAPPING_MISSING, ENCRYPTED_NO_EXTRACT_PERMISSION, IMAGE_TABLE_NO_STRUCTURE, CHART_NOT_TRANSCRIBED, OCR_REQUESTED_BUT_UNAVAILABLE, OCR_LOW_CONFIDENCE, EMPTY
PageClass	TEXT_LAYER, SCANNED, MIXED
PdfALevel	A_1B, A_1A, A_2B, A_2A, A_2U, A_3B, A_3A, A_3U, A_4, A_4E
PdfUaLevel	UA_1, UA_2 (у каждого есть code(): Int)
PdfXLevel	X_1A_2001, X_1A_2003, X_3_2002, X_3_2003, X_4, X_4P, X_5G, X_5N, X_5PG, X_6, X_6P
PolicyMode	COMPAT, STRICT, FIPS_STRICT
PixelFormat	RGBA_8888, RGB_888, GRAY_8
SignatureLevel	B_B, B_T, B_LT

---

Фасадные расширения Scala

Модуль Scala добавляет следующие методы-расширения (extension) поверх Java-типов, чтобы вызывающий код получал Option/Seq вместо java.util.Optional/java.util.List. Импортируйте нужные из fyi.oxide.pdf.

// Generic — any java.util.Optional[T]
extension [T](o: java.util.Optional[T]) def toOption: Option[T]

// PdfDocument
extension (doc: PdfDocument)
  def producerOption: Option[String]
  def creatorOption: Option[String]
  def formFieldsSeq: Seq[FormField]
  def pagesSeq: Seq[PdfPage]
  def searchSeq(query: String): Seq[SearchMatch]

// PdfPage
extension (page: PdfPage)
  def wordsSeq: Seq[TextWord]
  def linesSeq: Seq[TextLine]
  def charsSeq: Seq[TextChar]
  def tablesSeq: Seq[Table]
  def imagesSeq: Seq[ExtractedImage]
  def annotationsSeq: Seq[Annotation]

// FormField
extension (f: FormField)
  def valueOption: Option[String]
  def bboxOption: Option[BBox]

// Annotation
extension (a: Annotation)
  def contentsOption: Option[String]
  def uriOption: Option[String]

// AutoResult
extension (r: AutoResult)
  def markdownOption: Option[String]
  def htmlOption: Option[String]
  def pagesNeedingOcrSeq: Seq[Int]

// ValidationViolation
extension (v: ValidationViolation)
  def pageIndexOption: Option[Int]

---

Исключения

Все ошибки наследуются от fyi.oxide.pdf.exception.PdfException:

Исключение	Причина
PdfException	Базовый класс для всех ошибок PDF Oxide
PdfParseException	Повреждённый или некорректный PDF
PdfEncryptedException	Зашифрованный PDF открыт без пароля
PdfPermissionException	Операция запрещена флагами шифрования документа
PdfInvalidStateException	Операция над закрытым или недействительным дескриптором
PdfIoException	Сбой ввода-вывода на уровне ниже
PdfUnsupportedException	Неподдерживаемая функция или формат
PdfOcrUnavailableException	Запрошен OCR, но функция ocr не встроена в сборку
PdfSignatureException	Ошибка подписания или проверки подписи

PdfErrorKind — перечисление, классифицирующее конкретную категорию ошибки, которую несёт PdfException.

---

Полный пример

import fyi.oxide.pdf.*
import fyi.oxide.pdf.auto.AutoExtractConfig
import scala.util.Using

// --- Creation ---
Using.resource(Pdf.fromMarkdown("# Report\n\nGenerated by PDF Oxide.")): pdf =>
  pdf.saveTo(java.nio.file.Path.of("report.pdf"))

// --- Extraction ---
Using.resource(PdfDocument.open("report.pdf")): doc =>
  println(s"Pages: ${doc.pageCount()}")

  val page = doc.page(0)
  println(s"${page.width()} x ${page.height()}")
  page.wordsSeq.foreach(w => println(s"${w.text} @ ${w.bbox.x0}"))

  // Search (facade -> Seq)
  doc.searchSeq("Report").foreach(m => println(s"p${m.pageIndex}: ${m.text}"))

  // Metadata (facade -> Option)
  println(doc.producerOption.getOrElse("(none)"))

  // Auto extraction with OCR fallback
  val cfg = AutoExtractConfig.builder().withMinOcrConfidence(0.6).build()
  val result = AutoExtractor.of(doc, cfg).extractDocument()
  println(s"confidence=${result.confidence} ocr=${result.ocrUsed}")
  result.markdownOption.foreach(println)

// --- Editing: fill a form, redact, scrub ---
Using.resource(DocumentEditor.open("form.pdf")): ed =>
  ed.setFormField("name", "Jane Doe")
    .setFormField("agree", true)
    .addRedaction(0, BBox(72, 700, 272, 720))
  val redacted = ed.applyRedactionsDestructive()
  println(s"redacted ${redacted.regionsApplied} regions")
  ed.scrubMetadata().saveTo(java.nio.file.Path.of("output.pdf"))

Other Language Bindings

PDF Oxide предоставляет нативные привязки для всех основных экосистем: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Clojure, Objective-C, и Elixir.

Дальнейшие шаги

• Типы и перечисления — все общие типы и перечисления
• Справочник Page API — единообразная постраничная итерация для всех привязок
• Начало работы с Scala — учебное руководство