PDF-Formulare mit Java und PDFtk automatisch ausfüllen

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Java kann PDFtk strukturierte Feldwerte übergeben, um das wiederkehrende Ausfüllen von Formularen zu automatisieren. Diese Anleitung erzeugt XFDF mit den XML-APIs von Java, statt PDF-Syntax von Hand zusammenzusetzen, und erhält vorhandene Dateien, während sie das Ergebnis des Konverters prüft.

Einführung in PDFtk und die Java-Integration

PDFtk kann vorhandene AcroForm-Felder mit FDF- oder XFDF-Daten ausfüllen. Es erstellt keine ausfüllbaren Felder in einer gescannten Seite, und dieser Workflow behandelt keine XFA-Formulare. Beginnen Sie mit einer Vorlage, deren Feldnamen, Darstellungsschriften und Exportwerte Sie geprüft haben.

Voraussetzungen

Ein gepflegtes JDK, für dieses Beispiel Java 17 oder neuer.
Der Befehl pdftk muss in PATH verfügbar sein.
Eine echte PDF-Vorlage mit ausfüllbaren AcroForm-Feldern.
Ein Zieldateisystem, das Hardlinks unterstützt.

PDFtk in Ihrer Java-Umgebung einrichten

Unter Ubuntu/Debian:

sudo apt-get update
sudo apt-get install pdftk-java

Unter macOS:

brew install pdftk-java

Folgen Sie unter Windows der PDFtk-Installationsdokumentation für die von Ihnen gewählte Distribution. Prüfen Sie den Befehl und das JDK, bevor Sie fortfahren:

pdftk --version
javac -version

Formulardatenfelder mit PDFtk aus PDFs extrahieren

Prüfen Sie Namen und Exportwerte in UTF-8:

pdftk template.pdf dump_data_fields_utf8

Ein Textfeld kann einen Namen wie Name haben; Kontrollkästchen und Optionsfelder melden zusätzlich die Werte unter FieldStateOption. Verwenden Sie genau diese Namen und Werte, nicht die sichtbare Beschriftung oder einen angenommenen Wert wie Yes. Ein erfolgreicher PDFtk-Befehl kann ein unbekanntes Feld dennoch unausgefüllt lassen.

Das Ausfüllen von Formularen mit Java automatisieren

Speichern Sie dieses vollständige Beispiel als PdfFormFiller.java. fillForm nimmt eine Map aus Feldnamen und Werten entgegen. Das CLI-Beispiel übergibt Name und Date; passen Sie diese Schlüssel an Ihre Vorlage an.

import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.OutputKeys;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import org.w3c.dom.Document;
import org.w3c.dom.Element;

public class PdfFormFiller {
    public static void fillForm(Path template, Path output, Map<String, String> values,
                                boolean flatten) throws Exception {
        template = template.toAbsolutePath().normalize();
        output = output.toAbsolutePath().normalize();
        if (!Files.isRegularFile(template)) {
            throw new IOException("Template must be a regular file");
        }
        if (Files.exists(output, LinkOption.NOFOLLOW_LINKS)) {
            throw new IOException("Output must not exist");
        }
        if (values.isEmpty() || values.entrySet().stream().anyMatch(
                entry -> entry.getKey() == null || entry.getValue() == null)) {
            throw new IllegalArgumentException("Supply nonnull field names and values");
        }
        Path temporary = Files.createTempDirectory(output.getParent(), ".pdf-form-");
        Path data = temporary.resolve("data.xfdf");
        Path candidate = temporary.resolve("result.pdf");
        try {
            writeXfdf(data, values);
            List<String> arguments = new ArrayList<>(List.of("pdftk", template.toString(),
                    "fill_form", data.toString(), "output", candidate.toString()));
            if (flatten) arguments.add("flatten");
            arguments.add("dont_ask");
            Process process = new ProcessBuilder(arguments)
                    .redirectOutput(ProcessBuilder.Redirect.DISCARD)
                    .redirectError(ProcessBuilder.Redirect.DISCARD).start();
            process.getOutputStream().close();
            try {
                if (!process.waitFor(120, TimeUnit.SECONDS)) {
                    throw new IOException("PDFtk conversion timed out");
                }
                if (process.exitValue() != 0) {
                    throw new IOException("PDFtk conversion failed");
                }
            } finally {
                if (process.isAlive()) {
                    process.destroyForcibly();
                    process.waitFor();
                }
            }
            if (!Files.isRegularFile(candidate) || Files.size(candidate) == 0) {
                throw new IOException("PDFtk did not produce a nonempty result");
            }
            // Same-filesystem publication fails if a destination appeared during conversion.
            Files.createLink(output, candidate);
        } finally {
            Files.deleteIfExists(candidate);
            Files.deleteIfExists(data);
            Files.deleteIfExists(temporary);
        }
    }

    private static void writeXfdf(Path path, Map<String, String> values) throws Exception {
        String namespace = "http://ns.adobe.com/xfdf/";
        Document document = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
        Element root = document.createElementNS(namespace, "xfdf");
        document.appendChild(root);
        Element fields = document.createElementNS(namespace, "fields");
        root.appendChild(fields);
        for (Map.Entry<String, String> entry : values.entrySet()) {
            Element field = document.createElementNS(namespace, "field");
            field.setAttribute("name", entry.getKey());
            Element value = document.createElementNS(namespace, "value");
            value.setTextContent(entry.getValue());
            field.appendChild(value);
            fields.appendChild(field);
        }
        var transformer = TransformerFactory.newInstance().newTransformer();
        transformer.setOutputProperty(OutputKeys.ENCODING, "UTF-8");
        try (OutputStream stream = Files.newOutputStream(path)) {
            transformer.transform(new DOMSource(document), new StreamResult(stream));
        }
    }

    public static void main(String[] args) {
        if (args.length != 2) {
            System.err.println("Usage: java PdfFormFiller <template.pdf> <new-output.pdf>");
            System.exit(1);
        }
        try {
            fillForm(Path.of(args[0]), Path.of(args[1]),
                    Map.of("Name", "Jane Doe", "Date", "2026-09-15"), true);
            System.out.println("Filled PDF saved");
        } catch (InterruptedException error) {
            Thread.currentThread().interrupt();
            System.err.println("PDF form filling interrupted");
            System.exit(1);
        } catch (Exception error) {
            System.err.println("PDF form filling failed; check template, fields, destination, and PDFtk");
            System.exit(1);
        }
    }
}

Kompilieren Sie es und führen Sie es aus:

javac PdfFormFiller.java
java PdfFormFiller template.pdf filled_form.pdf

Der XML-Serializer maskiert sowohl Feldnamen als auch Werte. Die Übertragung in UTF-8 erhält die Zeichen, doch die Darstellungsschriften des PDFs müssen sie weiterhin unterstützen. Das temporäre Verzeichnis enthält Formulardaten: Bewahren Sie es auf einem Speicherort mit eingeschränktem Zugriff auf und setzen Sie passende Verzeichnisberechtigungen oder ACLs für Ihre Plattform. Die Veröffentlichung per Hardlink schützt vor Namenskollisionen bei der Ausgabe; sie verschlüsselt das Ergebnis nicht.

flatten=true rendert Felder in den Seiteninhalt. Das ist weder Zugriffskontrolle noch Manipulationsschutz, und das Neuschreiben eines signierten PDFs macht dessen Signatur ungültig. Verwenden Sie false, wenn Sie bearbeitbare Felder benötigen. Prüfen Sie das sichtbare Ergebnis und bei nicht abgeflachter Ausgabe zusätzlich die Feldwerte.

Praktische Beispiele: Steuerformulare und Charakterbögen automatisieren

Rufen Sie fillForm für jede geprüfte Vorlage mit einer anderen Map auf. Halten Sie sensible Finanzdaten aus Quellcode und Logs heraus. Verwenden Sie für Tests synthetische Datensätze; ein Entwickler-Tutorial ist kein validierter Workflow zur Steuererstellung. Charakterbögen und interne Formulare sind nützliche Fixtures mit geringem Risiko, um Feldnamen, mehrzeiligen Text und Auswahlwerte zu prüfen.

Fortgeschrittene Tipps zum Umgang mit komplexen PDF-Formularen

Werte von Kontrollkästchen und Optionsfeldern müssen mit den Exportwerten der Vorlage übereinstimmen.
Auswahlfelder können Anzeigebeschriftungen haben, die von ihren gespeicherten Werten abweichen; prüfen Sie beides.
Dieses auf einer Map basierende Beispiel schreibt einen reinen Textwert pro Feld, keinen Rich Text und keine Liste von Auswahlen.
Schriftabdeckung, Feldgrenzen und die Erzeugung der Darstellung beeinflussen das Rendering, selbst wenn die Werte korrekt sind.

Häufige Probleme beheben

PDFtk nicht gefunden

Führen Sie pdftk --version aus derselben Umgebung heraus aus wie Java. Korrigieren Sie PATH oder konfigurieren Sie in ProcessBuilder einen explizit angegebenen, vertrauenswürdigen Pfad zur ausführbaren Datei. Übernehmen Sie den Namen der ausführbaren Datei nicht aus einem Upload.

Berechtigungsprobleme

Der Prozess benötigt Lesezugriff auf die Vorlage und Schreibzugriff auf das Zielverzeichnis. Außerdem benötigt er Hardlink-Unterstützung auf diesem Dateisystem. Schlägt die Veröffentlichung fehl, greifen Sie nicht auf eine überschreibende Kopie zurück; wählen Sie einen unterstützten Speicherort oder implementieren Sie eine ausdrücklich nicht überschreibende Alternative.

Umgang mit verschlüsselten PDFs

Verschlüsselte Vorlagen erfordern ein eigenes Konzept für den Umgang mit Passwörtern. PDFtk unterstützt input_pw, doch Passwörter in Prozessargumenten können durch Prozessinspektion sichtbar werden. Schreiben Sie Passwörter nicht fest in den Code und kopieren Sie sie nicht in Logs. Verwenden Sie einen für Ihre Umgebung geeigneten sicheren Workflow, statt Secrets in die Kommandozeile dieses Tutorials aufzunehmen.

Falsche Feldnamen oder Werte

Prüfen Sie die genauen Feldnamen und Exportwerte mit dump_data_fields_utf8. Vergleichen Sie ein nicht abgeflachtes Ergebnis mit der vorgesehenen Map und prüfen Sie anschließend das abgeflachte Ergebnis visuell. Klammern, Kaufmanns-Unds, Anführungszeichen und Backslashes werden vom XML-Serializer behandelt, nicht von einer selbst geschriebenen FDF-Escape-Funktion. Fehlende Glyphen erfordern passende Schriften in der Vorlage; sie lassen sich nicht durch eine Änderung der XML-Zeichenkodierung beheben.

Fazit

Die XML-APIs von Java und PDFtk ergeben einen kleinen, testbaren Workflow zum Ausfüllen von Formularen. Verwenden Sie eine echte AcroForm-Vorlage, halten Sie Ausgaben getrennt, geben Sie Fehler weiter und überprüfen Sie sowohl die gespeicherten Werte als auch die Darstellung. Führen Sie den Konverter bei nicht vertrauenswürdigen Dokumenten in einem eingeschränkten Worker mit Ressourcenlimits und ohne Anwendungszugangsdaten aus.

Entdecken Sie für verwaltete Dokumenten-Workflows den Dienst zur Dokumentenverarbeitung von Transloadit und den Robot 🤖 /document/merge.