Довідник API для Kotlin

PDF Oxide постачає ідіоматичні прив’язки Kotlin/JVM (готові до Android) як тонкий фасад над зрілою прив’язкою для Java fyi.oxide:pdf-oxide, яка володіє єдиним нативним JNI-мостом (крейт pdf_oxide_jni). Модуль Kotlin не додає жодного нативного коду: він повторно експортує типи Java (PdfDocument, Pdf, PdfPage, DocumentEditor, PdfSigner, PdfValidator, AutoExtractor та типи-значення для геометрії / тексту / таблиць / пошуку) і додає Kotlin-цукор — розширення Optional<T> у T? та use { } на закриваних дескрипторах AutoCloseable.

// build.gradle.kts
dependencies {
    implementation("fyi.oxide:pdf-oxide-kotlin:0.3.69")
}

Нативна JNI-бібліотека (libpdf_oxide_jni) не входить до постачання — завантажте її через System.loadLibrary("pdf_oxide_jni") (постачайте .so/.dylib на вашому java.library.path або в jniLibs/<abi>/ на Android), або вкажіть на неї Java-завантажувачу NativeLoader через -Dfyi.oxide.pdf.lib.path=<path>.

Про API для Java див. Довідник API для Java. Про API для Rust див. Довідник API для Rust. Про деталі типів див. Типи та переліки.

import fyi.oxide.pdf.Pdf
import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.producerOrNull

Pdf.fromMarkdown("# Hello\n\nbody\n").use { pdf ->
    PdfDocument.open(pdf.save()).use { doc ->
        println(doc.pageCount())
        println(doc.extractText(0))
        println(doc.toMarkdown())
        println(doc.page(0).words().map { it.text() })
        println(doc.producerOrNull() ?: "(no producer)")   // Optional -> nullable
    }
}

Усі дескриптори (PdfDocument, Pdf, DocumentEditor) реалізують AutoCloseable, тож блок Kotlin use { } детерміновано звільняє нативну пам’ять. Помилки породжують PdfException (та його підкласи); див. Винятки.

---

PdfDocument

Основна точка входу лише для читання до PDF — відкривайте, видобувайте, конвертуйте, рендеріть, шукайте та інспектуйте поля форм. Екземпляри володіють нативною пам’яттю й мають бути закриті; використовуйте use { }.

import fyi.oxide.pdf.PdfDocument

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

PdfDocument.open(path: Path): PdfDocument

Відкрити PDF із шляху у файловій системі.

PdfDocument.open(path: String): PdfDocument

Відкрити PDF із рядка-шляху.

PdfDocument.open(bytes: ByteArray): PdfDocument

Відкрити PDF із байтів у пам’яті (наприклад, завантажених із S3 або отриманих через HTTP).

PdfDocument.open(path: Path, password: String): PdfDocument

Відкрити зашифрований PDF зі шляху з паролем користувача або власника.

PdfDocument.open(path: String, password: String): PdfDocument

Відкрити зашифрований PDF із рядка-шляху з паролем.

PdfDocument.open(bytes: ByteArray, password: String): PdfDocument

Відкрити зашифрований PDF із байтів з паролем.

PdfDocument.open(stream: InputStream): PdfDocument

Відкрити PDF, прочитавши всі байти з InputStream.

Статичні разові виклики

PdfDocument.extractText(path: String): String
PdfDocument.extractText(path: Path): String

Відкрити, видобути весь текст і закрити одним викликом — для простого випадку, коли вам не потрібен живий дескриптор.

Автентифікація

doc.authenticate(password: String): Boolean
doc.authenticate(password: ByteArray): Boolean

Автентифікувати зашифрований документ після відкриття. Повертає true, якщо пароль підійшов.

Інформація про документ

doc.pageCount(): Int

Кількість сторінок у документі.

doc.producer(): Optional<String>
doc.creator(): Optional<String>

Метадані /Producer і /Creator документа. Для доступу на основі null використовуйте розширення Kotlin producerOrNull() / creatorOrNull().

val doc.isOpen: Boolean

Чи досі відкритий нативний дескриптор (властивість Kotlin над Java-гетером isOpen()).

Видобування тексту

doc.extractText(pageIndex: Int): String

Видобути звичайний текст з окремої сторінки за індексом, що відлічується від нуля.

doc.extractTextAuto(pageIndex: Int): String

Видобути текст з автоматичним вибором стратегії (повертається до OCR для сканованих сторінок, коли доступна функція OCR).

doc.extractStructured(page: Int): String

Видобути структуроване (JSON) подання тексту та компонування сторінки.

Конвертація

doc.toMarkdown(): String
doc.toMarkdown(pageIndex: Int): String

Перетворити весь документ або окрему сторінку на Markdown.

doc.toHtml(): String
doc.toHtml(pageIndex: Int): String

Перетворити весь документ або окрему сторінку на HTML.

Пошук

doc.search(query: String): List<SearchMatch>

Шукати в документі літеральний рядок. Повертає посторінкові збіги з обмежувальними прямокутниками.

doc.search(query: String, caseInsensitive: Boolean, regex: Boolean, maxResults: Int): List<SearchMatch>

Пошук із урахуванням чутливості до регістру, regex та обмеженням кількості результатів (maxResults = 0 означає без обмеження).

Форми

doc.formFields(): List<FormField>

Отримати всі поля AcroForm з їхнім типом, значенням, межами віджета та індексом сторінки. Див. FormField.

Рендеринг

doc.render(pageIndex: Int): ByteArray
doc.render(pageIndex: Int, dpi: Int): ByteArray

Відрендерити сторінку в байти зображення PNG за стандартним або вказаним DPI.

Доступ до сторінок

doc.page(index: Int): PdfPage

Отримати лінивий дескриптор PdfPage для заданого індексу, що відлічується від нуля.

doc.pages(): List<PdfPage>

Отримати всі сторінки списком.

doc.pagesStream(): Stream<PdfPage>

Отримати всі сторінки як Java Stream для плавної обробки.

Життєвий цикл

doc.close()

Звільнити нативну пам’ять. Ідемпотентно — повторний виклик не робить нічого. Віддавайте перевагу use { }.

---

PdfPage

Лінивий дескриптор сторінки, що повертається з PdfDocument.page(), pages() або pagesStream(). Усі аксесори при зверненні делегують батьківському документу.

PdfDocument.open(bytes).use { doc ->
    val page = doc.page(0)
    val words = page.words()
    val tables = page.tables()
}

Геометрія

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

Батьківський документ, індекс від нуля, прямокутники MediaBox / CropBox, розміри в пунктах PDF та поворот сторінки в градусах.

Видобування вмісту

page.text(): String

Видобути весь текст на сторінці.

page.text(region: BBox): String

Видобути текст у межах ділянки, заданої обмежувальним прямокутником.

page.words(): List<TextWord>
page.lines(): List<TextLine>
page.chars(): List<TextChar>

Структурований текст із деталізацією до слова, рядка та символу.

page.images(): List<ExtractedImage>
page.tables(): List<Table>
page.annotations(): List<Annotation>

Видобуті зображення, виявлені таблиці та анотації сторінки.

---

Pdf

Створюйте PDF з вихідних форматів, розділяйте за закладками та серіалізуйте. Реалізує AutoCloseable.

import fyi.oxide.pdf.Pdf

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

Pdf.fromMarkdown(markdown: String): Pdf

Створити PDF із вмісту Markdown.

Pdf.fromHtml(html: String): Pdf

Створити PDF із вмісту HTML.

Pdf.fromImages(images: List<ByteArray>): Pdf

Створити багатосторінковий PDF зі списку масивів байтів зображень — по одній сторінці на зображення.

Розділення

pdf.planSplitByBookmarks(opts: SplitByBookmarksOptions): List<BookmarkSegment>

Спланувати розділення за закладками контуру без створення результату — повертає сегменти (заголовок, діапазон сторінок, ім’я файлу), які було б створено.

pdf.splitByBookmarks(opts: SplitByBookmarksOptions): List<ByteArray>

Розділити на декілька PDF за рівнем закладок. Повертає по одному масиву байтів на сегмент.

Pdf.planSplitByBookmarksCount(sourcePdf: ByteArray, level: Int): Int

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

Pdf.splitByBookmarksFromBytes(sourcePdf: ByteArray, level: Int): Array<ByteArray>

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

Збереження

pdf.save(): ByteArray

Серіалізувати PDF у байти.

pdf.saveTo(out: Path)

Записати PDF у файл.

val pdf.isOpen: Boolean
pdf.close()

Життєвий цикл (властивість Kotlin isOpen і close()). Віддавайте перевагу use { }.

---

DocumentEditor

Змінювальний редактор для редагування (редакції), заповнення форм, очищення метаданих та інкрементних збережень. Реалізує AutoCloseable. Методи-сетери повертають this для плавного ланцюгування.

import fyi.oxide.pdf.DocumentEditor

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

DocumentEditor.open(path: Path): DocumentEditor
DocumentEditor.open(path: String): DocumentEditor
DocumentEditor.open(bytes: ByteArray): DocumentEditor

Відкрити документ для редагування зі шляху або з байтів у пам’яті.

Заповнення форм

editor.setFormField(name: String, value: String): DocumentEditor

Встановити значення текстового поля / поля вибору за повним кваліфікованим ім’ям.

editor.setFormField(name: String, checked: Boolean): DocumentEditor

Встановити стан прапорця / перемикача за ім’ям.

Редакція

editor.addRedaction(pageIndex: Int, region: BBox): DocumentEditor

Поставити в чергу редакцію над прямокутною ділянкою на сторінці.

editor.redactionCount(pageIndex: Int): Int
editor.redactionCount(): Int

Кількість поставлених у чергу редакцій на сторінці або по всьому документу.

editor.applyRedactionsDestructive(): RedactResult

Безповоротно застосувати всі поставлені в чергу редакції, видаливши прихований вміст. Повертає RedactResult з кількістю застосованих редакцій і статусом оракул-верифікації.

Метадані

editor.scrubMetadata(): DocumentEditor

Видалити метадані документа (словник Info, XMP) задля приватності.

Збереження

editor.save(): ByteArray
editor.saveTo(out: Path)

Серіалізувати відредагований документ із повним перезаписом.

editor.saveIncremental(): ByteArray
editor.saveIncrementalTo(out: Path)

Серіалізувати з інкрементним оновленням (дописує зміни, зберігаючи оригінальні байти).

val editor.isOpen: Boolean
editor.close()

Життєвий цикл. Віддавайте перевагу use { }.

---

AutoExtractor

Адаптивний конвеєр видобування, що класифікує сторінки (текстовий шар vs. сканована), застосовує OCR там, де потрібно, і видає текст / Markdown / HTML з оцінками впевненості.

import fyi.oxide.pdf.AutoExtractor

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

AutoExtractor.of(doc: PdfDocument): AutoExtractor
AutoExtractor.of(doc: PdfDocument, config: AutoExtractConfig): AutoExtractor

Створити екстрактор над документом, за бажанням із власною AutoExtractConfig.

AutoExtractor.fast(doc: PdfDocument): AutoExtractor
AutoExtractor.balanced(doc: PdfDocument): AutoExtractor
AutoExtractor.highFidelity(doc: PdfDocument): AutoExtractor

Попередньо налаштовані конфігурації, що балансують швидкість і точність.

Видобування

extractor.extractText(): String
extractor.extractTextForPage(pageIndex: Int): String

Видобування звичайного тексту для всього документа або окремої сторінки.

extractor.extractDocument(): AutoResult
extractor.extractPage(pageIndex: Int): AutoResult

Повне адаптивне видобування, що повертає AutoResult (текст, опціональні Markdown/HTML, причина, впевненість, прапорець OCR, ділянки).

extractor.extractAutoDocument(): AutoResult
extractor.extractAutoPage(pageIndex: Int): AutoResult

Варіанти видобування в авто-режимі на рівні документа та сторінки.

extractor.extractDocumentJson(): String
extractor.extractPageJson(pageIndex: Int): String

Видобування, серіалізоване як JSON-рядок.

Класифікація

extractor.classifyDocument(): ClassifyResult
extractor.classifyPage(pageIndex: Int): ClassifyResult

Класифікувати документ або сторінку, повертаючи ClassifyResult (клас кожної сторінки плюс списки сторінок, яким потрібен OCR, які містять діаграми або зашифровані).

extractor.classifyPageKind(pageIndex: Int): PageClass
extractor.classifyDocumentKinds(): List<PageClass>

Отримати PageClass (TEXT_LAYER / SCANNED / MIXED) для сторінки або всіх сторінок.

Аксесори

extractor.document(): PdfDocument
extractor.config(): AutoExtractConfig

Обгорнутий документ і активна конфігурація.

---

MarkdownConverter

Конвертер без стану, безпечний для потоків, із PdfDocument у Markdown або HTML.

import fyi.oxide.pdf.MarkdownConverter

MarkdownConverter.toMarkdown(doc: PdfDocument): String
MarkdownConverter.toMarkdown(doc: PdfDocument, pageIndex: Int): String
MarkdownConverter.toHtml(doc: PdfDocument): String
MarkdownConverter.toHtml(doc: PdfDocument, pageIndex: Int): String

Перетворити весь документ або окрему сторінку на Markdown / HTML.

---

PdfSigner

Цифрово підписуйте та перевіряйте PDF за допомогою сховищ ключів PKCS#12 (рівні PAdES B-B / B-T / B-LT).

import fyi.oxide.pdf.PdfSigner

PdfSigner.fromPkcs12(keystore: Path, password: String): PdfSigner
PdfSigner.fromPkcs12(keystoreBytes: ByteArray, password: String): PdfSigner

Завантажити підписувача зі сховища ключів PKCS#12 на диску або в пам’яті.

signer.sign(pdf: ByteArray, opts: SignOptions): ByteArray

Підписати байти PDF із заданими SignOptions (рівень, причина, місце, контакт, URL TSA). Повертає підписаний PDF.

signer.verify(pdf: ByteArray): Boolean

Перевірити всі підписи в PDF. Повертає true, якщо кожен підпис криптографічно дійсний.

PdfSigner.classifyLevel(pdf: ByteArray): SignatureLevel

Статичний помічник: визначити рівень відповідності PAdES наявного підписаного PDF.

---

PdfValidator

Перевірка без стану, безпечна для потоків, на відповідність рівням PDF/A, PDF/X і PDF/UA.

import fyi.oxide.pdf.PdfValidator

PdfValidator.isPdfA(doc: PdfDocument, level: PdfALevel): Boolean
PdfValidator.isPdfUa(doc: PdfDocument, level: PdfUaLevel): Boolean

Швидкі булеві перевірки відповідності.

PdfValidator.validatePdfA(doc: PdfDocument, level: PdfALevel): ValidationResult
PdfValidator.validatePdfX(doc: PdfDocument, level: PdfXLevel): ValidationResult
PdfValidator.validatePdfUa(doc: PdfDocument, level: PdfUaLevel): ValidationResult

Повна перевірка, що повертає ValidationResult зі списком порушень.

---

PdfPolicy

Глобальні засоби керування політикою безпеки, що визначають, які криптографічні алгоритми дозволені.

import fyi.oxide.pdf.PdfPolicy

PdfPolicy.current(): PolicyMode
PdfPolicy.set(mode: PolicyMode)
PdfPolicy.compat(): PolicyMode
PdfPolicy.strict(): PolicyMode
PdfPolicy.fipsStrict(): PolicyMode

Прочитати або встановити активний PolicyMode та отримати вбудовані режими compat / strict / FIPS-strict.

---

Розширення Kotlin

Єдина додана поверхня фасаду Kotlin: конвертери Optional<T> у T? та узагальнений помічник orNull(). Імпортуйте з fyi.oxide.pdf.

fun <T : Any> Optional<T>.orNull(): T?

Узагальнений: порожній Optional стає null.

fun PdfDocument.producerOrNull(): String?
fun PdfDocument.creatorOrNull(): String?

/Producer і /Creator документа, або null, якщо відсутні.

fun FormField.valueOrNull(): String?
fun FormField.bboxOrNull(): BBox?

Значення поля форми та обмежувальний прямокутник віджета, або null.

fun Annotation.contentsOrNull(): String?
fun Annotation.uriOrNull(): String?

/Contents анотації та URI цілі посилання, або null.

fun AutoResult.markdownOrNull(): String?
fun AutoResult.htmlOrNull(): String?

Рендеринг авто-видобування в Markdown / HTML, або null, якщо не створено.

fun ValidationViolation.pageIndexOrNull(): Int?

Індекс сторінки, до якої застосовується порушення, або null для правил рівня документа.

---

Геометричні типи

BBox

Вирівняний за осями обмежувальний прямокутник у пунктах PDF.

BBox(x0: Double, y0: Double, x1: Double, y1: Double)

Аксесор	Тип	Опис
x0(), y0(), x1(), y1()	Double	Координати кутів
width()	Double	x1 - x0
height()	Double	y1 - y0

Color

8-бітний колір RGBA з іменованими константами Color.BLACK, Color.WHITE, Color.TRANSPARENT.

Color(r: Int, g: Int, b: Int, a: Int)
Color(r: Int, g: Int, b: Int)            // a = 255

Аксесори: r(): Int, g(): Int, b(): Int, a(): Int.

Point

Point(x: Double, y: Double)

Аксесори: x(): Double, y(): Double.

Rect

Прямокутник «позиція плюс розмір».

Rect(x: Double, y: Double, width: Double, height: Double)

Аксесори: x(), y(), width(), height() (усі Double) та toBBox(): BBox.

---

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

TextChar

Окремий видобутий символ.

TextChar(codepoint: Int, bbox: BBox, confidence: Float)

Аксесори: codepoint(): Int, bbox(): BBox, confidence(): Float, asString(): String.

TextWord

TextWord(text: String, bbox: BBox, confidence: Float)

Аксесори: text(): String, bbox(): BBox, confidence(): Float.

TextLine

TextLine(text: String, bbox: BBox, words: List<TextWord>)

Аксесори: text(): String, bbox(): BBox, words(): List<TextWord>.

TextSpan

Послідовність однаково стилізованого тексту.

TextSpan(text: String, bbox: BBox, style: TextStyle)

Аксесори: text(): String, bbox(): BBox, style(): TextStyle.

TextStyle

TextStyle(font: String?, size: Double, color: Color, bold: Boolean, italic: Boolean)

Аксесори: font(): String?, size(): Double, color(): Color, bold(): Boolean, italic(): Boolean.

---

Типи таблиць

Table

Table(bbox: BBox, rows: Int, cols: Int, cells: List<TableCell>)

Аксесори: bbox(): BBox, rows(): Int, cols(): Int, cells(): List<TableCell>.

TableCell

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

Аксесори: text(): String, bbox(): BBox, row(): Int, col(): Int, rowSpan(): Int, colSpan(): Int.

---

Типи пошуку

SearchMatch

SearchMatch(pageIndex: Int, bbox: BBox, text: String)

Аксесори: pageIndex(): Int, bbox(): BBox, text(): String.

SearchResult

SearchResult(query: String, matches: List<SearchMatch>)

Аксесори: query(): String, matches(): List<SearchMatch>, count(): Int, isEmpty(): Boolean.

SearchOptions

Незмінні параметри, побудовані через плавний білдер. SearchOptions.DEFAULT — стандартний екземпляр. Примітка: наразі не підключено до PdfDocument.search() — замість цього використовуйте перевантаження з caseInsensitive/regex/maxResults вище.

SearchOptions.builder()
    .withCaseSensitive(true)
    .withWholeWord(true)
    .withRegex(false)
    .withMaxResults(50)
    .build()

Аксесори: caseSensitive(): Boolean, wholeWord(): Boolean, regex(): Boolean, maxResults(): Optional<Int>. Методи білдера: withCaseSensitive(Boolean), withWholeWord(Boolean), withRegex(Boolean), withMaxResults(Int) / withMaxResults(Int?), build().

---

Типи форм

FormField

FormField(name: String, type: FormFieldType, value: String?, bbox: BBox?, pageIndex: Int)

Аксесори: name(): String, type(): FormFieldType, value(): Optional<String>, bbox(): Optional<BBox>, pageIndex(): Int. Для доступу на основі null використовуйте valueOrNull() / bboxOrNull().

---

Типи анотацій

Annotation

Annotation(type: AnnotationType, pageIndex: Int, bbox: BBox, contents: String?, uri: String?)

Аксесори: type(): AnnotationType, pageIndex(): Int, bbox(): BBox, contents(): Optional<String>, uri(): Optional<String>. Для доступу на основі null використовуйте contentsOrNull() / uriOrNull().

---

Типи зображень

ExtractedImage

ExtractedImage(bytes: ByteArray, format: ImageFormat, bbox: BBox, width: Int, height: Int)

Аксесори: bytes(): ByteArray, format(): ImageFormat, bbox(): BBox, width(): Int, height(): Int.

---

Типи авто-видобування

AutoResult

Результат адаптивного видобування.

result.text(): String
result.markdown(): Optional<String>
result.html(): Optional<String>
result.reason(): ExtractReason
result.confidence(): Double
result.ocrUsed(): Boolean
result.regions(): List<RegionResult>
result.pagesNeedingOcr(): List<Int>

Для доступу на основі null до відрендереного виводу використовуйте markdownOrNull() / htmlOrNull().

RegionResult

Деталі видобування для кожної ділянки в межах AutoResult.

region.pageIndex(): Int
region.bbox(): BBox
region.text(): String
region.reason(): ExtractReason
region.confidence(): Double
region.ocrUsed(): Boolean
region.table(): Optional<Table>

ClassifyResult

result.pages(): List<PageClass>
result.pagesNeedingOcr(): List<Int>
result.pagesWithChart(): List<Int>
result.pagesEncrypted(): List<Int>

AutoExtractConfig

Незмінна конфігурація, побудована через плавний білдер; AutoExtractConfig.DEFAULT — стандартна. Перетворіть наявну конфігурацію назад на білдер за допомогою toBuilder().

AutoExtractConfig.builder()
    .withMode(ExtractMode.AUTO)
    .withForceOcrPages(listOf(2, 5))
    .withMinOcrConfidence(0.6)
    .withOcrLanguages("eng", "deu")
    .withPasswords("secret")
    .withTopMarginFraction(0.05)
    .withBottomMarginFraction(0.05)
    .withAllowSingleColumnTables(true)
    .withOcrInlineImages(false)
    .withCancelToken("token-id")
    .build()

Аксесори повертають Optional<...> для кожного поля: mode(), forceOcrPages(), minOcrConfidence(), ocrLanguages(), passwords(), topMarginFraction(), bottomMarginFraction(), allowSingleColumnTables(), ocrInlineImages(), cancelToken(). Сетери білдера приймають як упаковані-nullable, так і примітивні перевантаження (наприклад, withMinOcrConfidence(Double?) і withTopMarginFraction(double)), а також varargs-форми withOcrLanguages(vararg String) / withPasswords(vararg String).

---

Типи відповідності

ValidationResult

ValidationResult(valid: Boolean, violations: List<ValidationViolation>)

Аксесори: valid(): Boolean, violations(): List<ValidationViolation>.

ValidationViolation

ValidationViolation(ruleId: String, description: String, pageIndex: Int?)

Аксесори: ruleId(): String, description(): String, pageIndex(): Optional<Int>. Для доступу на основі null використовуйте pageIndexOrNull().

---

Типи метаданих

DocumentInfo

DocumentInfo(/* title, author, subject, keywords, creator, producer, creationDate, modificationDate */)

Усі аксесори повертають Optional<String>: title(), author(), subject(), keywords(), creator(), producer(), creationDate(), modificationDate().

XmpMetadata

Сирий пакет XMP. XmpMetadata.EMPTY — порожній екземпляр.

XmpMetadata(xml: String)

Аксесори: xml(): String, isEmpty(): Boolean.

---

Типи безпеки та редакції

SecurityPolicy

Незмінна політика, побудована через плавний білдер.

SecurityPolicy.builder()
    .withMode(PolicyMode.STRICT)
    .allow("algorithm-id")
    .deny("algorithm-id")
    .build()

Аксесори: mode(): PolicyMode, additionalAllow(): List<String>, additionalDeny(): List<String>. Методи білдера: withMode(PolicyMode), allow(String), deny(String), build().

RedactResult

RedactResult(regionsApplied: Int, oracleVerified: Boolean)

Аксесори: regionsApplied(): Int, oracleVerified(): Boolean.

---

Типи підпису

SignOptions

Незмінні параметри підписання, побудовані через плавний білдер.

SignOptions.builder()
    .withLevel(SignatureLevel.B_T)
    .withReason("Approved")
    .withLocation("HQ")
    .withContactInfo("ops@example.com")
    .withTsaUrl("https://freetsa.org/tsr")
    .build()

Аксесори: level(): SignatureLevel, reason(): Optional<String>, location(): Optional<String>, contactInfo(): Optional<String>, tsaUrl(): Optional<String>. Методи білдера: withLevel, withReason, withLocation, withContactInfo, withTsaUrl, build().

---

Типи розділення

BookmarkSegment

BookmarkSegment(title: String, firstPage: Int, lastPage: Int, filename: String)

Аксесори: title(): String, firstPage(): Int, lastPage(): Int, filename(): String.

SplitByBookmarksOptions

Незмінні параметри, побудовані через плавний білдер.

SplitByBookmarksOptions.builder()
    .withLevel(1)
    .withFilenamePrefix("chapter-")
    .build()

Аксесори: level(): Int, filenamePrefix(): Optional<String>. Методи білдера: withLevel(Int), withFilenamePrefix(String?), build().

---

Переліки

Перелік	Значення
FormFieldType	TEXT, CHECKBOX, RADIO, CHOICE
AnnotationType	HIGHLIGHT, TEXT, LINK, STAMP, UNDERLINE, STRIKEOUT, SQUIGGLY, FREE_TEXT, LINE, SQUARE, CIRCLE, FILE_ATTACHMENT
ImageFormat	JPEG, PNG, 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
PixelFormat	RGBA_8888, RGB_888, GRAY_8, PNG
PolicyMode	COMPAT, STRICT
SignatureLevel	B_B, B_T, B_LT
PdfALevel	A_1B, A_1A, A_2B, A_2A, A_2U, A_3B, A_3A, A_3U, A_4, A_4E, A_4F
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, X_6N
PdfUaLevel	UA_1, UA_2 (кожен надає code(): Int)
PdfErrorKind	PARSE, ENCRYPTED, PERMISSION, IO, OCR_UNAVAILABLE, SIGNATURE, INVALID_STATE, UNSUPPORTED, OTHER

---

Винятки

Усі збої породжують PdfException (неперевірюваний виняток) або один із його підкласів, специфічних для типу помилки. Аксесор kind() повертає PdfErrorKind.

import fyi.oxide.pdf.exception.PdfException

try {
    PdfDocument.open(bytes).use { doc ->
        println(doc.extractText(0))
    }
} catch (e: PdfException) {
    println("PDF error [${e.kind()}]: ${e.message}")
}

PdfException(message: String)
PdfException(kind: PdfErrorKind, message: String)
PdfException(kind: PdfErrorKind, message: String, cause: Throwable)

e.kind(): PdfErrorKind

Виняток	Причина
PdfParseException	Некоректний або пошкоджений PDF
PdfEncryptedException	Зашифрований документ відкрито без дійсного пароля
PdfPermissionException	Операцію заблоковано дозволами документа
PdfIoException	Збій базового вводу-виводу
PdfOcrUnavailableException	Запитано OCR, але функцію ocr не зібрано
PdfSignatureException	Збій підписання або перевірки підпису
PdfInvalidStateException	Операція недійсна для поточного стану дескриптора
PdfUnsupportedException	Непідтримувана функція або формат

---

Повний приклад

import fyi.oxide.pdf.AutoExtractor
import fyi.oxide.pdf.DocumentEditor
import fyi.oxide.pdf.Pdf
import fyi.oxide.pdf.PdfDocument
import fyi.oxide.pdf.geometry.BBox
import fyi.oxide.pdf.producerOrNull

// --- Creation ---
val bytes = Pdf.fromMarkdown("# Report\n\nGenerated by PDF Oxide.").use { it.save() }

// --- Extraction ---
PdfDocument.open(bytes).use { doc ->
    println("Pages: ${doc.pageCount()}")
    println("Producer: ${doc.producerOrNull() ?: "(none)"}")

    val page = doc.page(0)
    println("Words: ${page.words().map { it.text() }}")
    println("Tables: ${page.tables().size}")

    // Search with options
    val matches = doc.search("Report", caseInsensitive = true, regex = false, maxResults = 0)
    matches.forEach { m -> println("p${m.pageIndex()} '${m.text()}' @ ${m.bbox()}") }

    // Adaptive extraction
    val result = AutoExtractor.balanced(doc).extractDocument()
    println("confidence=${result.confidence()} ocr=${result.ocrUsed()}")
}

// --- Editing: redact + fill forms ---
DocumentEditor.open(bytes).use { editor ->
    editor.setFormField("name", "Jane Doe")
        .addRedaction(0, BBox(72.0, 700.0, 272.0, 720.0))
        .scrubMetadata()
    val redaction = editor.applyRedactionsDestructive()
    println("Redacted ${redaction.regionsApplied()} regions")
    val out: ByteArray = editor.save()
}

Other Language Bindings

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

Наступні кроки

• Типи та переліки — усі спільні типи та переліки
• Довідник API сторінки — узгоджена ітерація по сторінках для всіх прив’язок
• Початок роботи з Kotlin — посібник