Migrating off Flying Saucer, and leaving XHTML strictness behind

What ports and what does not

Everything ports, and more easily than the templates expect. Flying Saucer parsed XHTML strictly, so your markup is well-formed, every tag is closed and every attribute is quoted, which is exactly the input a browser engine is happiest with. Its CSS support stopped at 2.1, so the templates contain no modern layout at all. Nothing breaks and nothing improves until the templates are rewritten, which is the same shape as the dompdf migration with a different language around it.

What the call becomes

ITextRenderer, setDocumentFromString, layout and createPDF collapse into a POST to /v1/pdf with html. The renderer's shared context configuration, its user agent callback for resolving resources and its font directory registration have no counterpart: resource resolution becomes ordinary HTTP from the markup, and fonts become @font-face at a public URL. Page setup was already CSS in Flying Saucer, so set options.prefer_css_page_size to true and leave the rest alone.

Side by side

The old shape and the new one, with the parts that have no counterpart called out in comments rather than quietly omitted.

// Before
ITextRenderer renderer = new ITextRenderer();
renderer.getFontResolver().addFont("/fonts/brand.ttf", true);
renderer.setDocumentFromString(xhtml, baseUrl);
renderer.layout();
ByteArrayOutputStream out = new ByteArrayOutputStream();
renderer.createPDF(out);

// After
String body = mapper.writeValueAsString(Map.of(
    "html", xhtml,
    "filename", "invoice.pdf",
    "options", Map.of("prefer_css_page_size", true)
));

HttpResponse<byte[]> resp = client.send(
    HttpRequest.newBuilder()
        .uri(URI.create("https://api.pdfpipe.xyz/v1/pdf"))
        .header("Authorization", "Bearer " + System.getenv("PDFPIPE_KEY"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build(),
    HttpResponse.BodyHandlers.ofByteArray());

/* addFont has no counterpart. The font becomes an @font-face rule in
   the document pointing at a public URL:

     @font-face {
       font-family: "Brand";
       src: url("https://assets.example.com/brand.woff2") format("woff2");
     }

   The user agent callback that resolved images and stylesheets from the
   classpath also has no counterpart. Those assets have to be reachable
   over HTTP or inlined. */

The CSS delta, in both directions

What the old engine accepted that a current one does not, and what it refused that a current one wants. The second direction is the one people forget, and it is where the value of the migration is.

• CSS 2.1 is a subset of what is available now, so nothing in the stylesheets stops working. Flexbox and grid become available and the table-based layouts continue to render.
• The XHTML strictness requirement is gone. That is a relaxation rather than a change, and it is worth keeping the discipline: well-formed markup is easier to reason about and the templates already have it.
• Resource resolution changes from a classpath callback to ordinary HTTP, which is the substantive difference and the one that needs work.
• Font registration changes from a renderer call to @font-face, which also means the font file has to move somewhere public.

What changes without anything erroring

The dangerous list. Each of these produces a different document and no diagnostic, so none of them are caught by a test that only checks the render succeeded.

• Fonts, because addFont registrations vanish and the family names in the CSS resolve to nothing.
• Images and stylesheets loaded through the user agent callback, which stop loading and produce an unstyled or incomplete document.
• Page count, from metric differences, though less than in most migrations because CSS 2.1 layout is comparatively predictable.

What to diff before cutting over

List every resource the user agent callback was resolving, because that list is invisible in the markup: the URLs in the templates may look like ordinary paths while being served from the classpath. Then diff extracted text and page counts.

The one thing that always breaks

Resource loading through the callback. Flying Saucer let an application intercept every resource request and serve it from anywhere, typically the classpath or a database, and templates written against it reference resources by paths that mean nothing over HTTP. Everything they point at fails to load at once.

Frequently asked

Other migrations

The nearest neighbours first, then others that started from the same kind of tool, because the model matters more than the language.