Skip to content
PDF Oxide

Erste Schritte mit PDF Oxide (Java)

PDF Oxide ist die schnellste Java-PDF-Bibliothek für die Textextraktion — 0,8 ms im Durchschnitt, 100 % Erfolgsquote bei 3.830 realen PDFs. Derselbe Rust-Kern wird auch für Python, Go, JS und C# ausgeliefert; das Java-Binding ist eine schlanke JNI-Schicht mit JDK 11 LTS als Mindestversion und kostenloser Kotlin-Interoperabilität aus demselben JAR.

Installation

Das JAR bringt native Bibliotheken für Linux (x86_64/aarch64), macOS (x86_64/aarch64) und Windows (x86_64) mit. Kein Compiler, keine zusätzliche Einrichtung — die passende Bibliothek wird beim ersten Aufruf entpackt.

Maven

<dependency>
  <groupId>fyi.oxide</groupId>
  <artifactId>pdf-oxide</artifactId>
  <version>0.3.69</version>
</dependency>

Gradle

// Kotlin DSL
implementation("fyi.oxide:pdf-oxide:0.3.69")

// Groovy
implementation 'fyi.oxide:pdf-oxide:0.3.69'

Schnellstart

Öffnen Sie ein PDF und extrahieren Sie Text. PdfDocument ist AutoCloseable, verwenden Sie also try-with-resources, um das native Handle deterministisch freizugeben.

import fyi.oxide.pdf.PdfDocument;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("report.pdf"))) {
    System.out.println("Pages: " + doc.pageCount());
    System.out.println(doc.extractText(0)); // zero-based page index
}

Sie können aus einem Pfad-String, einem Path, rohen byte[] oder einem InputStream öffnen:

import fyi.oxide.pdf.PdfDocument;

byte[] pdfBytes = downloadFromS3();
try (PdfDocument doc = PdfDocument.open(pdfBytes)) {
    String text = doc.extractText(0);
}

Textextraktion

Durchlaufen Sie jede Seite anhand ihres nullbasierten Index:

import fyi.oxide.pdf.PdfDocument;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("book.pdf"))) {
    for (int i = 0; i < doc.pageCount(); i++) {
        System.out.println("--- Page " + (i + 1) + " ---");
        System.out.println(doc.extractText(i));
    }
}

Extraktion auf Wortebene

Eine PdfPage legt strukturierte Geometrie offen. words() liefert eine Liste von TextWord, jeweils mit Text, Bounding Box und OCR-Konfidenz.

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.PdfPage;
import fyi.oxide.pdf.text.TextWord;
import fyi.oxide.pdf.geometry.BBox;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("paper.pdf"))) {
    PdfPage page = doc.page(0);
    for (TextWord word : page.words()) {
        BBox b = word.bbox();
        System.out.printf("'%s' at (%.1f, %.1f) conf=%.2f%n",
            word.text(), b.x0(), b.y0(), word.confidence());
    }
}

PdfPage bietet außerdem lines(), chars(), tables(), images(), annotations() sowie width(), height() und text(BBox region), um aus einem Teilbereich zu extrahieren.

Markdown-Konvertierung

Konvertieren Sie eine einzelne Seite oder das gesamte Dokument nach Markdown über den Helfer MarkdownConverter (oder die Komfortmethoden doc.toMarkdown(...)).

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.MarkdownConverter;
import java.nio.file.Files;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("report.pdf"))) {
    String md = MarkdownConverter.toMarkdown(doc); // whole document
    Files.writeString(Path.of("report.md"), md);

    String pageMd = doc.toMarkdown(0); // single page
    String pageHtml = doc.toHtml(0);   // or HTML
}

Suche

search() durchsucht das gesamte Dokument und liefert eine Liste von SearchMatch, jeweils mit Seitenindex, Bounding Box und gefundenem Text.

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.search.SearchMatch;
import fyi.oxide.pdf.geometry.BBox;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("manual.pdf"))) {
    for (SearchMatch m : doc.search("configuration")) {
        BBox b = m.bbox();
        System.out.printf("Page %d: '%s' at (%.0f, %.0f)%n",
            m.pageIndex(), m.text(), b.x0(), b.y0());
    }
}

PDFs erstellen

Der Typ Pdf erstellt PDFs aus Markdown, HTML oder Bildern. Er ist AutoCloseable und hat keine Cleaner-Absicherung, schließen Sie ihn also immer explizit oder in try-with-resources.

import fyi.oxide.pdf.Pdf;
import java.nio.file.Path;

try (Pdf pdf = Pdf.fromMarkdown("# Hello\n\nThis is a PDF.")) {
    pdf.saveTo(Path.of("out.pdf"));
}

try (Pdf pdf = Pdf.fromHtml("<h1>Invoice</h1><p>Amount: $42</p>")) {
    byte[] bytes = pdf.save(); // serialize to memory instead of disk
}

Passwortgeschützte PDFs

Übergeben Sie ein Passwort an open() oder rufen Sie authenticate() auf, nachdem Sie eine PdfEncryptedException abgefangen haben.

import fyi.oxide.pdf.PdfDocument;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("confidential.pdf"), "secret")) {
    System.out.println(doc.extractText(0));
}

Fehlerbehandlung

PdfException extends RuntimeException (unchecked), mit typisierten Unterklassen und einem kind()-Enum für die switch-Verteilung.

import fyi.oxide.pdf.PdfDocument;
import fyi.oxide.pdf.exception.PdfEncryptedException;
import fyi.oxide.pdf.exception.PdfException;
import java.nio.file.Path;

try (PdfDocument doc = PdfDocument.open(Path.of("document.pdf"))) {
    String text = doc.extractText(0);
} catch (PdfEncryptedException e) {
    System.err.println("Password required");
} catch (PdfException e) {
    switch (e.kind()) {
        case PARSE -> System.err.println("Malformed PDF");
        case IO    -> System.err.println("I/O error");
        default    -> System.err.println("PDF error: " + e.getMessage());
    }
}

Kotlin

Dasselbe JAR funktioniert direkt aus Kotlin — Record-Accessoren werden zu Properties.

import fyi.oxide.pdf.PdfDocument
import java.nio.file.Path

PdfDocument.open(Path.of("report.pdf")).use { doc ->
    println("Pages: ${doc.pageCount()}")
    println(doc.extractText(0))
}

Nächste Schritte