How mirakl/openhtmltopdf works
Main Components
• Input/Parsing Layer: Represent the starting point where well-formed XML/XHTML (or some crafted HTML5) and associated CSS is provided. This part likely relies on third‐party HTML/CSS parsers (for instance, JSoup or native Java DOM parsers).
• Plugins/Extension Modules: These include distinct submodules such as:
• OpenHTMLtoPDF-Core: The central library code.
• SVG Support (openhtmltopdf-svg-support): Processes SVG images using libraries like Apache Batik.
• MathML Support (openhtmltopdf-mathml-support): For rendering MathML content.
• Java2D Output Module (openhtmltopdf-java2d): Optionally outputs the render to images using Java2D routines.
• PDFBox Integration (openhtmltopdf-pdfbox and related modules): Responsible for converting the visual layout into PDF documents using Apache PDFBox.
• Modules for RTL support, barcode objects (from the objects module), and additional template processing.
• Output Layer: The final output is the PDF document (or raster images), which are produced by the rendering engine when it processes the layout.
• Auxiliary/testing and example modules: These include the “openhtmltopdf-examples”, “tests” folder with subdirectories (diff, regress, etc.) that indicate an extensive automated visual regression testing and example implementations.
Relationships and Data Flow
• Data flows from the user-provided document (HTML/CSS) into the Parsing Layer.
• During rendering, the layout engine queries the appropriate plugins (like the SVG or MathML components) if it encounters specialized markup.
• The output from the layout engine is then handed to a rendering device, which may either be a PDF creation engine (using PDFBox) or a Java2D-based image generator.
• The system supports plug-in style extension points (for object drawers, font resolution, output device configuration, etc.) that can be seen in certain modules.
• The testing modules run side-by-side to ensure visual output consistency through regression tests.
Architectural Patterns and Design Principles
• Modular design: The project is broken into several Maven modules (core, examples, various support modules) so each can be developed, tested, and maintained independently.
• Separation of concerns: Parsing, layout, rendering, and special plugin handling are separated into different packages and modules.
• Extensibility: With clearly defined extension points (e.g., client-supplied font resolvers, custom object drawers, and resource controlling mechanisms), the design adheres to the open/closed principle.
• Use of External Libraries: Integration with Apache PDFBox for PDF generation and Apache Batik for SVG rendering is an important architectural decision that drives component interactions.
• Testing & Regression: The presence of extensive test cases and visual regression tests indicates a design that heavily depends on constant feedback from automated tests to maintain rendering accuracy.
Technologies and Subsystems
• Components utilize Java 8 or later (as noted in the README).
• Core rendering with dependencies on PDFBOX and Batik.
• CSS parser and processing – both custom code and third-party libraries are used for interpreting and cascading styles.
• A multi-module Maven project, with modules such as openhtmltopdf-core, openhtmltopdf-java2d, openhtmltopdf-pdfbox, etc.
• Integration with build tools (Maven, GitHub Actions workflows) and automated testing frameworks (JUnit).