Java-Bibliothek

Die Java-Bibliothek ruft die Brevier-Engine aus Ihrem Java-Code auf. Sie übergeben HTML und Daten und bekommen das PDF zurück. Der Client läuft ab Java 8. Die Engine übernimmt das Layout, Sie schreiben keinen Code zum Zeichnen von PDFs.

Es gibt zwei Betriebsarten:

Engine installieren

Die Engine ist der Befehl brevier. Der Kindprozess-Modus startet ihn, er muss also im PATH des Rechners liegen, auf dem Ihr Java-Code läuft:

pip install brevier

Weitere Wege zur Installation stehen auf der Seite Installation.

Testschlüssel holen

Jede Erzeugung braucht einen Lizenzschlüssel, auch zum Testen. Holen Sie den Schlüssel vor der ersten Erzeugung.

1. Fordern Sie auf der Preisseite einen kostenlosen Testschlüssel für 30 Tage an. Er kommt per E-Mail.
2. Setzen Sie die Umgebungsvariable BREVIER_LICENCE_KEY:

export BREVIER_LICENCE_KEY="<ihr-lizenzschluessel>"

$env:BREVIER_LICENCE_KEY = "<ihr-lizenzschluessel>"

Die Engine liest den Schlüssel aus ihrer Umgebung. Der Java-Client gibt Ihre Umgebung an den Kindprozess weiter. Im Serve-Modus setzen Sie den Schlüssel in der Shell, die brevier serve startet.

Client hinzufügen

implementation 'dev.brevier:brevier:0.6.0'

<dependency>
  <groupId>dev.brevier</groupId>
  <artifactId>brevier</artifactId>
  <version>0.6.0</version>
</dependency>

Kindprozess

Dieses Programm erzeugt ein PDF aus einem HTML-Text und einer Map:

import dev.brevier.Pdf;
import java.nio.file.Paths;
import java.util.Collections;

public class Hello {
    public static void main(String[] args) {
        Pdf.builder()
            .withHtml("<h1>Hello {{ name }}</h1>")
            .withData(Collections.singletonMap("name", "World"))
            .toFile(Paths.get("hello.pdf"));
    }
}

Starten Sie es. Im Ordner liegt jetzt hello.pdf.

• withHtml und withCss nehmen das Layout als Text oder als Path.
• withData nimmt jedes Java-Objekt: eine Map oder eine Bean. withJson nimmt JSON-Text.
• toBytes gibt das PDF zurück. toFile schreibt es in einen Pfad.

Serve-Modus

Im Serve-Modus läuft die Engine als Dienst, und Ihr Code fragt sie mit dem Namen einer Vorlage nach einem PDF. Eine Vorlage ist ein Ordner mit einer Datei gleichen Namens:

<!DOCTYPE html>
<html lang="en">
<body>
  <h1>Hello {{ name }}</h1>
</body>
</html>

Starten Sie den Server in dem Ordner, der templates enthält:

brevier serve --templates templates

Der Server lauscht auf 127.0.0.1:8080. Er hat weder TLS noch eine Anmeldung. Stellen Sie ein Gateway davor, bevor Sie ihn nach außen öffnen. Dann erzeugen Sie die Vorlage aus Java:

import dev.brevier.Brevier;
import dev.brevier.transport.HttpTransport;
import java.nio.file.Files;
import java.nio.file.Paths;

public class HelloServe {
    public static void main(String[] args) throws Exception {
        byte[] pdf = Brevier.template("hello")
            .withTransport(new HttpTransport("http://127.0.0.1:8080"))
            .with("name", "World")
            .render();
        Files.write(Paths.get("hello.pdf"), pdf);
    }
}

• with(name, value) setzt eine Wurzel der Vorlage. with(map) setzt mehrere.
• rows(list) setzt die Zeilen einer Tabelle.
• render(objects...) bindet jedes Objekt an die Wurzel seines Typs.
• Ohne withTransport startet der Client brevier serve --stdio als Kindprozess. Er liest den Ordner templates des Arbeitsverzeichnisses und nutzt den Prozess weiter.

Wie erzeuge ich viele PDFs auf einmal?

Pdf.batch() macht aus jeder HTML-Datei eines Ordners und seiner Unterordner ein PDF. Alle Dateien bekommen dasselbe CSS. Der Batch übergibt keine Daten: Jede Datei muss schon die fertige Seite sein, zum Beispiel aus Ihrer eigenen Template-Engine.

import dev.brevier.Pdf;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;

public class Batch {
    public static void main(String[] args) {
        List<Path> written = Pdf.batch()
            .withInput(Paths.get("briefe"), "*.html")
            .withCss(Paths.get("firma.css"))
            .withOutput(Paths.get("out"))
            .toFiles();
        written.forEach(System.out::println);
    }
}

Mit briefe/2026-001.html und briefe/2026-002.html gibt das Programm eine Zeile je geschriebenem PDF aus, in der Reihenfolge, in der es die Dateien findet:

out/2026-001.pdf
out/2026-002.pdf

Für ein PDF je Datensatz rufen Sie stattdessen Pdf.builder() in einer Schleife auf. Ein Unterordner von briefe erscheint als derselbe Unterordner von out. Scheitert eine Datei, wirft toFiles eine BrevierException.

Wie liefere ich das PDF aus einem Web-Endpunkt aus?

Erzeugen Sie die Bytes und geben Sie sie mit dem Inhaltstyp application/pdf zurück. In Spring Boot:

@GetMapping(value = "/invoices/{id}/pdf", produces = MediaType.APPLICATION_PDF_VALUE)
public byte[] invoice(@PathVariable String id) {
    return Brevier.template("rechnung").render(invoices.find(id));
}

invoices steht für Ihren eigenen Datenzugriff. Bei vielen Anfragen starten Sie brevier serve und übergeben einen HttpTransport, wie unter Serve-Modus.

Wie bekomme ich HTML statt eines PDFs?

Html.builder() nimmt dieselben Aufrufe wie Pdf.builder() und gibt HTML zurück. Damit zeigen Sie das Dokument in einem Webportal, oder Sie vergleichen es in einem Test:

byte[] html = Html.builder()
    .withHtml("<h1>Hello {{ name }}</h1>")
    .withData(Collections.singletonMap("name", "World"))
    .toBytes();

Die Klassennamen dieses HTML bleiben von Version zu Version gleich. Ausgabe und Tests zeigt, wie Sie es in einem Snapshot-Test nutzen.

Einen JasperReports- oder Word-Aufruf ersetzen

Wenn Ihr Dienst heute einen JasperReports-Bericht oder eine Word-Datei füllt, importieren Sie zuerst die Vorlage. Ersetzen Sie dann den Aufruf in zwei Schritten.

Schritt 1 behält Ihre Map der Parameter und übergibt die Zeilen:

return Brevier.template("kontoauszug").with(params).rows(buchungen).render();

Schritt 2 übergibt Ihre Objekte. Der Client bindet jedes Objekt an die Wurzel seines Typs.

return Brevier.template("kontoauszug").render(konto, kunde, buchungen);

Fehler

Der Client wirft eine BrevierException. Sie hat getCode(), den Fehlercode der Engine wie DATA_ERROR, und getPath(), die Stelle in den Daten, an der das Problem liegt. Die Meldung enthält nie einen Wert aus Ihren Daten.