Kotlin-API-Referenz

PDF Oxide liefert idiomatische Kotlin/JVM-Bindings (Android-tauglich) als dünne Fassade über dem ausgereiften Java-Binding fyi.oxide:pdf-oxide, das die einzige native JNI-Brücke verwaltet (die pdf_oxide_jni-Crate). Das Kotlin-Modul fügt keinerlei nativen Code hinzu: Es re-exportiert die Java-Typen (PdfDocument, Pdf, PdfPage, DocumentEditor, PdfSigner, PdfValidator, AutoExtractor sowie die Wertetypen für Geometrie / Text / Tabellen / Suche) und ergänzt Kotlin-Komfort — Optional<T>-zu-T?-Erweiterungen und use { } auf den AutoCloseable-Handles.

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

Die native JNI-Bibliothek (libpdf_oxide_jni) wird nicht mitgeliefert — lade sie über System.loadLibrary("pdf_oxide_jni") (liefere die .so/.dylib auf deinem java.library.path aus, oder unter Android in jniLibs/<abi>/), oder verweise den Java-NativeLoader mit -Dfyi.oxide.pdf.lib.path=<path> darauf.

Zur Java-API siehe die Java-API-Referenz. Zur Rust-API siehe die Rust-API-Referenz. Für Typdetails siehe Typen & Enums.

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
    }
}

Alle Handles (PdfDocument, Pdf, DocumentEditor) implementieren AutoCloseable, sodass der Kotlin-use { }-Block nativen Speicher deterministisch freigibt. Fehler lösen PdfException (und ihre Unterklassen) aus; siehe Exceptions.

---

PdfDocument

Der primäre schreibgeschützte Einstiegspunkt zu einem PDF — öffnen, extrahieren, konvertieren, rendern, suchen und Formularfelder inspizieren. Instanzen besitzen nativen Speicher und müssen geschlossen werden; verwende use { }.

import fyi.oxide.pdf.PdfDocument

Factory-Methoden

PdfDocument.open(path: Path): PdfDocument

Öffnet ein PDF von einem Dateisystempfad.

PdfDocument.open(path: String): PdfDocument

Öffnet ein PDF von einem Pfad-String.

PdfDocument.open(bytes: ByteArray): PdfDocument

Öffnet ein PDF aus Bytes im Speicher (z. B. von S3 heruntergeladen oder über HTTP empfangen).

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

Öffnet ein verschlüsseltes PDF von einem Pfad mit dem Benutzer- oder Eigentümerpasswort.

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

Öffnet ein verschlüsseltes PDF von einem Pfad-String mit einem Passwort.

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

Öffnet ein verschlüsseltes PDF aus Bytes mit einem Passwort.

PdfDocument.open(stream: InputStream): PdfDocument

Öffnet ein PDF, indem alle Bytes aus einem InputStream gelesen werden.

Statische Einmal-Aufrufe

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

Öffnen, gesamten Text extrahieren und in einem einzigen Aufruf wieder schließen — für den einfachen Fall, in dem du kein aktives Handle benötigst.

Authentifizierung

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

Authentifiziert ein verschlüsseltes Dokument nach dem Öffnen. Gibt true zurück, wenn das Passwort übereinstimmte.

Dokumentinformationen

doc.pageCount(): Int

Anzahl der Seiten im Dokument.

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

/Producer- und /Creator-Metadaten des Dokuments. Verwende die Kotlin-Erweiterungen producerOrNull() / creatorOrNull() für null-basierten Zugriff.

val doc.isOpen: Boolean

Ob das native Handle noch geöffnet ist (Kotlin-Property über den Java-Getter isOpen()).

Textextraktion

doc.extractText(pageIndex: Int): String

Extrahiert reinen Text aus einer einzelnen, nullbasiert indizierten Seite.

doc.extractTextAuto(pageIndex: Int): String

Extrahiert Text mit automatischer Strategieauswahl (greift bei gescannten Seiten auf OCR zurück, wenn die OCR-Funktion verfügbar ist).

doc.extractStructured(page: Int): String

Extrahiert eine strukturierte (JSON-)Darstellung von Text und Layout der Seite.

Konvertierung

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

Konvertiert das gesamte Dokument oder eine einzelne Seite nach Markdown.

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

Konvertiert das gesamte Dokument oder eine einzelne Seite nach HTML.

Suche

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

Durchsucht das Dokument nach einer literalen Zeichenkette. Gibt seitenweise Treffer mit Begrenzungsrechtecken zurück.

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

Suche mit Groß-/Kleinschreibungs-Option, Regex und einer Obergrenze für die Trefferzahl (maxResults = 0 bedeutet keine Obergrenze).

Formulare

doc.formFields(): List<FormField>

Ruft alle AcroForm-Felder mit ihrem Typ, Wert, Widget-Begrenzungen und Seitenindex ab. Siehe FormField.

Rendering

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

Rendert eine Seite zu PNG-Bildbytes mit der Standard-DPI oder einer angegebenen DPI.

Seitenzugriff

doc.page(index: Int): PdfPage

Ruft ein faules PdfPage-Handle für den angegebenen nullbasierten Index ab.

doc.pages(): List<PdfPage>

Ruft alle Seiten als Liste ab.

doc.pagesStream(): Stream<PdfPage>

Ruft alle Seiten als Java-Stream für flüssige Verarbeitung ab.

Lebenszyklus

doc.close()

Gibt nativen Speicher frei. Idempotent — ein zweiter Aufruf ist eine No-op. Bevorzuge use { }.

---

PdfPage

Ein faules Seiten-Handle, das von PdfDocument.page(), pages() oder pagesStream() zurückgegeben wird. Alle Accessoren delegieren beim Zugriff an das übergeordnete Dokument.

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

Geometrie

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

Übergeordnetes Dokument, nullbasierter Index, MediaBox- / CropBox-Rechtecke, Abmessungen in PDF-Punkten und Seitendrehung in Grad.

Inhaltsextraktion

page.text(): String

Extrahiert den gesamten Text auf der Seite.

page.text(region: BBox): String

Extrahiert Text innerhalb einer Begrenzungsrechteck-Region.

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

Strukturierter Text auf Wort-, Zeilen- und Zeichenebene.

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

Extrahierte Bilder, erkannte Tabellen und Seitenannotationen.

---

Pdf

Erstellt PDFs aus Quellformaten, teilt nach Lesezeichen und serialisiert. Implementiert AutoCloseable.

import fyi.oxide.pdf.Pdf

Factory-Methoden

Pdf.fromMarkdown(markdown: String): Pdf

Erstellt ein PDF aus Markdown-Inhalt.

Pdf.fromHtml(html: String): Pdf

Erstellt ein PDF aus HTML-Inhalt.

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

Erstellt ein mehrseitiges PDF aus einer Liste von Bild-Byte-Arrays, eine Seite pro Bild.

Aufteilen

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

Plant eine Aufteilung nach Gliederungs-Lesezeichen, ohne Ausgabe zu erzeugen — gibt die Segmente (Titel, Seitenbereich, Dateiname) zurück, die erstellt würden.

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

Teilt nach Lesezeichenebene in mehrere PDFs auf. Gibt ein Byte-Array pro Segment zurück.

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

Statischer Helfer: Zählt, wie viele Segmente eine Lesezeichen-Aufteilung auf der angegebenen Ebene erzeugen würde.

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

Statischer Helfer: Teilt Quell-PDF-Bytes direkt nach Lesezeichenebene auf.

Speichern

pdf.save(): ByteArray

Serialisiert das PDF zu Bytes.

pdf.saveTo(out: Path)

Schreibt das PDF in eine Datei.

val pdf.isOpen: Boolean
pdf.close()

Lebenszyklus (Kotlin-isOpen-Property und close()). Bevorzuge use { }.

---

DocumentEditor

Verändernder Editor für Schwärzung, Formularausfüllung, Metadaten-Bereinigung und inkrementelle Speicherungen. Implementiert AutoCloseable. Setter-Methoden geben this für flüssige Verkettung zurück.

import fyi.oxide.pdf.DocumentEditor

Factory-Methoden

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

Öffnet ein Dokument zum Bearbeiten von einem Pfad oder aus Bytes im Speicher.

Formularausfüllung

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

Setzt den Wert eines Text-/Auswahlfelds anhand des vollqualifizierten Namens.

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

Setzt den Zustand eines Kontrollkästchen-/Optionsfelds anhand des Namens.

Schwärzung

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

Stellt eine Schwärzung über einer rechteckigen Region auf einer Seite in die Warteschlange.

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

Anzahl der eingereihten Schwärzungen auf einer Seite oder über das gesamte Dokument hinweg.

editor.applyRedactionsDestructive(): RedactResult

Wendet alle eingereihten Schwärzungen dauerhaft an und entfernt den zugrunde liegenden Inhalt. Gibt ein RedactResult mit der Anzahl der angewendeten Schwärzungen und dem Orakel-Verifizierungsstatus zurück.

Metadaten

editor.scrubMetadata(): DocumentEditor

Entfernt Dokumentmetadaten (Info-Dictionary, XMP) zum Schutz der Privatsphäre.

Speichern

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

Serialisiert das bearbeitete Dokument mit einer vollständigen Neufassung.

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

Serialisiert mit einem inkrementellen Update (hängt Änderungen an und bewahrt die ursprünglichen Bytes).

val editor.isOpen: Boolean
editor.close()

Lebenszyklus. Bevorzuge use { }.

---

AutoExtractor

Adaptive Extraktions-Pipeline, die Seiten klassifiziert (Textebene vs. gescannt), bei Bedarf OCR anwendet und Text / Markdown / HTML mit Konfidenzwerten ausgibt.

import fyi.oxide.pdf.AutoExtractor

Factory-Methoden

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

Erstellt einen Extractor über einem Dokument, optional mit einer benutzerdefinierten AutoExtractConfig.

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

Voreingestellte Konfigurationen, die Geschwindigkeit gegen Genauigkeit abwägen.

Extraktion

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

Reintext-Extraktion für das gesamte Dokument oder eine einzelne Seite.

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

Vollständige adaptive Extraktion, die ein AutoResult zurückgibt (Text, optionales Markdown/HTML, Grund, Konfidenz, OCR-Flag, Regionen).

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

Auto-Modus-Varianten der Extraktion auf Dokument- und Seitenebene.

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

Extraktion serialisiert als JSON-String.

Klassifizierung

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

Klassifiziert das Dokument oder eine Seite und gibt ein ClassifyResult zurück (Klasse pro Seite plus Listen der Seiten, die OCR benötigen, Diagramme enthalten oder verschlüsselt sind).

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

Ruft die PageClass (TEXT_LAYER / SCANNED / MIXED) für eine Seite oder alle Seiten ab.

Accessoren

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

Das umschlossene Dokument und die aktive Konfiguration.

---

MarkdownConverter

Zustandsloser, threadsicherer Konverter von PdfDocument nach Markdown oder 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

Konvertiert das gesamte Dokument oder eine einzelne Seite nach Markdown / HTML.

---

PdfSigner

Signiert PDFs digital und verifiziert sie mit PKCS#12-Keystores (PAdES-Stufen 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

Lädt einen Signierer aus einem PKCS#12-Keystore auf der Festplatte oder im Speicher.

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

Signiert PDF-Bytes mit den angegebenen SignOptions (Stufe, Grund, Ort, Kontakt, TSA-URL). Gibt das signierte PDF zurück.

signer.verify(pdf: ByteArray): Boolean

Verifiziert alle Signaturen in einem PDF. Gibt true zurück, wenn jede Signatur kryptografisch gültig ist.

PdfSigner.classifyLevel(pdf: ByteArray): SignatureLevel

Statischer Helfer: Erkennt die PAdES-Konformitätsstufe eines vorhandenen signierten PDF.

---

PdfValidator

Zustandslose, threadsichere Validierung gegen die Konformitätsstufen PDF/A, PDF/X und PDF/UA.

import fyi.oxide.pdf.PdfValidator

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

Schnelle boolesche Konformitätsprüfungen.

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

Vollständige Validierung, die ein ValidationResult mit der Liste der Verstöße zurückgibt.

---

PdfPolicy

Globale Sicherheitsrichtlinien-Steuerung, die regelt, welche kryptografischen Algorithmen zulässig sind.

import fyi.oxide.pdf.PdfPolicy

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

Liest oder setzt den aktiven PolicyMode und ruft die integrierten Compat- / Strict- / FIPS-Strict-Modi ab.

---

Kotlin-Erweiterungen

Die einzige zusätzliche Oberfläche der Kotlin-Fassade: Optional<T>-zu-T?-Konverter und der generische orNull()-Helfer. Importiere aus fyi.oxide.pdf.

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

Generisch: Ein leeres Optional wird zu null.

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

/Producer und /Creator des Dokuments, oder null, falls nicht vorhanden.

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

Formularfeldwert und Widget-Begrenzungsrechteck, oder null.

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

/Contents der Annotation und Link-Ziel-URI, oder null.

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

Markdown- / HTML-Rendering einer Auto-Extraktion, oder null, falls nicht erzeugt.

fun ValidationViolation.pageIndexOrNull(): Int?

Seitenindex, auf den sich ein Verstoß bezieht, oder null bei dokumentweiten Regeln.

---

Geometrietypen

BBox

Achsenparalleles Begrenzungsrechteck in PDF-Punkten.

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

Accessor	Typ	Beschreibung
x0(), y0(), x1(), y1()	Double	Eckkoordinaten
width()	Double	x1 - x0
height()	Double	y1 - y0

Color

8-Bit-RGBA-Farbe mit den benannten Konstanten Color.BLACK, Color.WHITE, Color.TRANSPARENT.

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

Accessoren: r(): Int, g(): Int, b(): Int, a(): Int.

Point

Point(x: Double, y: Double)

Accessoren: x(): Double, y(): Double.

Rect

Rechteck aus Position plus Größe.

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

Accessoren: x(), y(), width(), height() (alle Double) und toBBox(): BBox.

---

Texttypen

TextChar

Ein einzelnes extrahiertes Zeichen.

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

Accessoren: codepoint(): Int, bbox(): BBox, confidence(): Float, asString(): String.

TextWord

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

Accessoren: text(): String, bbox(): BBox, confidence(): Float.

TextLine

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

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

TextSpan

Ein Lauf gleich formatierten Texts.

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

Accessoren: text(): String, bbox(): BBox, style(): TextStyle.

TextStyle

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

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

---

Tabellentypen

Table

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

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

TableCell

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

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

---

Suchtypen

SearchMatch

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

Accessoren: pageIndex(): Int, bbox(): BBox, text(): String.

SearchResult

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

Accessoren: query(): String, matches(): List<SearchMatch>, count(): Int, isEmpty(): Boolean.

SearchOptions

Unveränderliche Optionen, erstellt über einen flüssigen Builder. SearchOptions.DEFAULT ist die Standardinstanz.

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

Accessoren: caseSensitive(): Boolean, wholeWord(): Boolean, regex(): Boolean, maxResults(): Optional<Int>. Builder-Methoden: withCaseSensitive(Boolean), withWholeWord(Boolean), withRegex(Boolean), withMaxResults(Int) / withMaxResults(Int?), build().

Hinweis: derzeit nicht mit PdfDocument.search() verdrahtet — verwenden Sie stattdessen die oben beschriebene Überladung mit caseInsensitive/regex/maxResults.

---

Formulartypen

FormField

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

Accessoren: name(): String, type(): FormFieldType, value(): Optional<String>, bbox(): Optional<BBox>, pageIndex(): Int. Verwende valueOrNull() / bboxOrNull() für null-basierten Zugriff.

---

Annotationstypen

Annotation

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

Accessoren: type(): AnnotationType, pageIndex(): Int, bbox(): BBox, contents(): Optional<String>, uri(): Optional<String>. Verwende contentsOrNull() / uriOrNull() für null-basierten Zugriff.

---

Bildtypen

ExtractedImage

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

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

---

Auto-Extraktions-Typen

AutoResult

Ergebnis einer adaptiven Extraktion.

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>

Verwende markdownOrNull() / htmlOrNull() für null-basierten Zugriff auf die gerenderte Ausgabe.

RegionResult

Extraktionsdetail pro Region innerhalb eines 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

Unveränderliche Konfiguration, erstellt über einen flüssigen Builder; AutoExtractConfig.DEFAULT ist der Standard. Wandle eine vorhandene Konfiguration mit toBuilder() wieder in einen Builder um.

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()

Accessoren geben für jedes Feld Optional<...> zurück: mode(), forceOcrPages(), minOcrConfidence(), ocrLanguages(), passwords(), topMarginFraction(), bottomMarginFraction(), allowSingleColumnTables(), ocrInlineImages(), cancelToken(). Die Builder-Setter akzeptieren sowohl geboxt-nullbare als auch primitive Überladungen (z. B. withMinOcrConfidence(Double?) und withTopMarginFraction(double)) sowie die Varargs-Formen withOcrLanguages(vararg String) / withPasswords(vararg String).

---

Konformitätstypen

ValidationResult

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

Accessoren: valid(): Boolean, violations(): List<ValidationViolation>.

ValidationViolation

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

Accessoren: ruleId(): String, description(): String, pageIndex(): Optional<Int>. Verwende pageIndexOrNull() für null-basierten Zugriff.

---

Metadatentypen

DocumentInfo

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

Alle Accessoren geben Optional<String> zurück: title(), author(), subject(), keywords(), creator(), producer(), creationDate(), modificationDate().

XmpMetadata

Rohes XMP-Paket. XmpMetadata.EMPTY ist die leere Instanz.

XmpMetadata(xml: String)

Accessoren: xml(): String, isEmpty(): Boolean.

---

Sicherheits- & Schwärzungstypen

SecurityPolicy

Unveränderliche Richtlinie, erstellt über einen flüssigen Builder.

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

Accessoren: mode(): PolicyMode, additionalAllow(): List<String>, additionalDeny(): List<String>. Builder-Methoden: withMode(PolicyMode), allow(String), deny(String), build().

RedactResult

RedactResult(regionsApplied: Int, oracleVerified: Boolean)

Accessoren: regionsApplied(): Int, oracleVerified(): Boolean.

---

Signaturtypen

SignOptions

Unveränderliche Signieroptionen, erstellt über einen flüssigen Builder.

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

Accessoren: level(): SignatureLevel, reason(): Optional<String>, location(): Optional<String>, contactInfo(): Optional<String>, tsaUrl(): Optional<String>. Builder-Methoden: withLevel, withReason, withLocation, withContactInfo, withTsaUrl, build().

---

Aufteilungstypen

BookmarkSegment

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

Accessoren: title(): String, firstPage(): Int, lastPage(): Int, filename(): String.

SplitByBookmarksOptions

Unveränderliche Optionen, erstellt über einen flüssigen Builder.

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

Accessoren: level(): Int, filenamePrefix(): Optional<String>. Builder-Methoden: withLevel(Int), withFilenamePrefix(String?), build().

---

Enums

Enum	Werte
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 (jeweils mit code(): Int)
PdfErrorKind	PARSE, ENCRYPTED, PERMISSION, IO, OCR_UNAVAILABLE, SIGNATURE, INVALID_STATE, UNSUPPORTED, OTHER

---

Exceptions

Alle Fehler lösen PdfException (eine ungeprüfte Exception) oder eine ihrer artspezifischen Unterklassen aus. Der kind()-Accessor gibt einen PdfErrorKind zurück.

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

Exception	Ursache
PdfParseException	Fehlerhaftes oder beschädigtes PDF
PdfEncryptedException	Verschlüsseltes Dokument ohne gültiges Passwort geöffnet
PdfPermissionException	Operation durch Dokumentberechtigungen blockiert
PdfIoException	Zugrunde liegender E/A-Fehler
PdfOcrUnavailableException	OCR angefordert, aber die ocr-Funktion ist nicht eingebaut
PdfSignatureException	Fehler beim Signieren oder bei der Signaturverifizierung
PdfInvalidStateException	Operation für den aktuellen Handle-Zustand ungültig
PdfUnsupportedException	Nicht unterstützte Funktion oder nicht unterstütztes Format

---

Vollständiges Beispiel

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 case-insensitively
    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 bietet native Bindings für jedes wichtige Ökosystem: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Dart, R, Julia, Zig, Scala, Clojure, Objective-C und Elixir.

Nächste Schritte

• Typen & Enums — alle gemeinsamen Typen und Enums
• Page-API-Referenz — konsistente Iteration pro Seite über alle Bindings hinweg
• Erste Schritte mit Kotlin — Tutorial