Module com.github.librepdf.openpdf.parent
Package org.openpdf.html

Class HtmlToPdfBatchUtils

java.lang.Object
org.openpdf.html.HtmlToPdfBatchUtils
public final class HtmlToPdfBatchUtils extends Object
High-performance batch HTML-to-PDF conversion utilities for OpenPDF HTML (Flying Saucer), powered by Java 21 virtual threads for scalable concurrent execution.

This class provides simple, high-level APIs for converting HTML sources to PDF files using ITextRenderer, with support for:

  • Raw HTML strings (with optional base URI for resolving relative resources)
  • Local HTML files and their relative assets (CSS, images, fonts, etc.)
  • Remote HTML content from HTTP/HTTPS URLs
  • Optional injection of custom CSS before rendering
  • Renderer customization hooks for advanced control (e.g., DPI, fonts, user agent)

Key Features

  • Runs each rendering task on a virtual thread for massive concurrency without thread exhaustion.
  • Provides convenient batch* methods to process large collections of jobs in parallel.
  • Supports flexible output path handling (directories created automatically).
  • Encapsulates results in a PdfBatch.BatchResult containing separate lists of successes and failures.

Usage Examples

Convert a single HTML string to PDF


 Path pdf = HtmlToPdfBatchUtils.renderHtmlString(
     "<html><body>Hello World</body></html>",
     "https://example.com/",
     Path.of("out.pdf"),
     HtmlToPdfBatchUtils.CSS_A4_20MM,
     HtmlToPdfBatchUtils.setDpi(150)
 );

Batch convert multiple HTML files


 List<HtmlFileJob> jobs = List.of(
     new HtmlFileJob(Path.of("file1.html"), Path.of("."), Path.of("file1.pdf"),
                     Optional.of(HtmlToPdfBatchUtils.CSS_LETTER_HALF_IN),
                     Optional.empty()),
     new HtmlFileJob(Path.of("file2.html"), Path.of("."), Path.of("file2.pdf"),
                     Optional.empty(),
                     Optional.of(HtmlToPdfBatchUtils.registerFontDir(Path.of("fonts"))))
 );

 BatchResult<Path> result = HtmlToPdfBatchUtils.batchHtmlFiles(jobs,
     path -> System.out.println("Created PDF: " + path),
     error -> error.printStackTrace()
 );

Notes invalid input: '&' Best Practices

  • Set page size and margins via CSS @page rules in your HTML or via the injectCss parameter.
  • Always provide a baseUri (or baseDir) if your HTML references relative resources.
  • Use rendererCustomizer to adjust advanced rendering settings like DPI or font loading.
  • Batch methods allow optional success and failure callbacks for real-time feedback during processing.
  • When using OutputStream-based batch jobs, every job must use a distinct OutputStream instance. Sharing a stream between concurrent jobs will corrupt the output. The caller is responsible for closing streams after the batch completes.
Since:
3.0.0

  • Field Details

    • CSS_A4_20MM

      public static final String CSS_A4_20MM
      Sample CSS for A4 portrait with 20mm margins.
      See Also:

    • CSS_LETTER_HALF_IN

      public static final String CSS_LETTER_HALF_IN
      Sample CSS for US Letter portrait with 0.5in margins.
      See Also:

  • Method Details

    • renderHtmlString

      public static Path renderHtmlString(String html, String baseUri, Path output, String injectCss, Consumer<ITextRenderer> rendererCustomizer) throws IOException
      Render an HTML string.
      Throws:
      IOException

    • renderHtmlString

      public static void renderHtmlString(String html, String baseUri, OutputStream outputStream, String injectCss, Consumer<ITextRenderer> rendererCustomizer)
      Render an HTML string.

    • renderHtmlFile

      public static Path renderHtmlFile(Path htmlFile, Path baseDir, Path output, String injectCss, Consumer<ITextRenderer> rendererCustomizer) throws IOException
      Render an HTML file (and relatives).
      Throws:
      IOException

    • renderHtmlFile

      public static void renderHtmlFile(Path htmlFile, Path baseDir, OutputStream outputStream, String injectCss, Consumer<ITextRenderer> rendererCustomizer) throws IOException
      Render an HTML file (and relatives).
      Throws:
      IOException

    • renderUrl

      public static Path renderUrl(String url, Path output, String injectCss, Consumer<ITextRenderer> rendererCustomizer) throws IOException
      Render a URL to PDF.
      Throws:
      IOException

    • renderUrl

      public static void renderUrl(String url, OutputStream outputStream, String injectCss, Consumer<ITextRenderer> rendererCustomizer) throws IOException
      Render a URL to PDF.
      Throws:
      IOException

    • batchHtmlStrings

      public static org.openpdf.text.utils.PdfBatch.BatchResult<Path> batchHtmlStrings(List<HtmlToPdfBatchUtils.HtmlStringJob> jobs, Consumer<Path> onSuccess, Consumer<Throwable> onFailure)

    • batchHtmlFiles

      public static org.openpdf.text.utils.PdfBatch.BatchResult<Path> batchHtmlFiles(List<HtmlToPdfBatchUtils.HtmlFileJob> jobs, Consumer<Path> onSuccess, Consumer<Throwable> onFailure)

    • batchUrls

      public static org.openpdf.text.utils.PdfBatch.BatchResult<Path> batchUrls(List<HtmlToPdfBatchUtils.UrlJob> jobs, Consumer<Path> onSuccess, Consumer<Throwable> onFailure)

    • batchHtmlStringsToStreams

      public static org.openpdf.text.utils.PdfBatch.BatchResult<Void> batchHtmlStringsToStreams(List<HtmlToPdfBatchUtils.HtmlStringStreamJob> jobs, Consumer<Void> onSuccess, Consumer<Throwable> onFailure)

    • batchHtmlFilesToStreams

      public static org.openpdf.text.utils.PdfBatch.BatchResult<Void> batchHtmlFilesToStreams(List<HtmlToPdfBatchUtils.HtmlFileStreamJob> jobs, Consumer<Void> onSuccess, Consumer<Throwable> onFailure)

    • batchUrlsToStreams

      public static org.openpdf.text.utils.PdfBatch.BatchResult<Void> batchUrlsToStreams(List<HtmlToPdfBatchUtils.UrlStreamJob> jobs, Consumer<Void> onSuccess, Consumer<Throwable> onFailure)

    • injectCssBlock

      public static UnaryOperator<String> injectCssBlock(String css)
      Wraps an HTML string with a