iText Architecture & Modules

package com.example.billing;

import java.util.List;

/**
 * Reports which generation of iText (or its LGPL fork) is on the class path, by probing the root class of each one.
 */
public final class Generations {

    private record Generation(String name, String licence, String probeClass) {

        boolean present() {
            try {
                Class.forName(probeClass, false, Generations.class.getClassLoader());
                return true;
            } catch (ClassNotFoundException e) {
                return false;
            }
        }
    }

    private static final List<Generation> GENERATIONS = List.of(
            new Generation("iText 1/2 or OpenPDF 1.x/2.x", "MPL or LGPL", "com.lowagie.text.Document"),
            new Generation("iText 5", "AGPLv3 or commercial", "com.itextpdf.text.Document"),
            new Generation("iText 7, 8 or 9", "AGPLv3 or commercial", "com.itextpdf.kernel.pdf.PdfDocument"),
            new Generation("OpenPDF 3.x", "MPL or LGPL", "org.openpdf.text.Document"));

    private Generations() {
    }

    public static void main(String[] args) {
        GENERATIONS.forEach(generation -> System.out.printf("%-30s %-22s %s%n",
                generation.name(), generation.licence(), generation.present() ? "on the class path" : "absent"));
    }
}

iText 1/2 or OpenPDF 1.x/2.x   MPL or LGPL            absent
iText 5                        AGPLv3 or commercial   absent
iText 7, 8 or 9                AGPLv3 or commercial   on the class path
OpenPDF 3.x                    MPL or LGPL            absent

<properties>
    <java.version>21</java.version>
    <itext.version>9.8.0</itext.version>
</properties>

<dependencies>
    <!-- layout brings kernel, io and commons; no signing, forms or encryption support is included -->
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>layout</artifactId>
        <version>${itext.version}</version>
    </dependency>
</dependencies>

package com.example.billing;

import java.io.ByteArrayOutputStream;

import com.itextpdf.bouncycastleconnector.BouncyCastleFactoryCreator;
import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfWriter;
import com.itextpdf.layout.Document;
import com.itextpdf.layout.element.Paragraph;

public final class MinimalHello {

    public static void main(String[] args) {
        var bytes = new ByteArrayOutputStream();
        try (var document = new Document(new PdfDocument(new PdfWriter(bytes)))) {
            document.add(new Paragraph("Hello from kernel, io and layout only"));
        }
        System.out.println("PDF bytes: " + bytes.size());

        // Nothing above needed Bouncy Castle. Asking for its factory is where a missing adapter shows up.
        try {
            var factory = BouncyCastleFactoryCreator.getFactory();
            System.out.println(factory.getClass().getSimpleName());
            System.out.println(factory.getProviderName());
        } catch (RuntimeException e) {
            System.out.println(e.getClass().getSimpleName() + ": " + e.getMessage());
        }
    }
}

PDF bytes: 1139
BouncyCastleDefaultFactory
UnsupportedOperationException: Either com.itextpdf:bouncy-castle-adapter or com.itextpdf:bouncy-castle-fips-adapter dependency must be added in order to use functionality requiring cryptography

<dependencies>
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itext-core</artifactId>
        <version>${itext.version}</version>
        <type>pom</type>
    </dependency>

    <!-- replace bouncy-castle-adapter with the FIPS variant; never keep both -->
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>bouncy-castle-fips-adapter</artifactId>
        <version>${itext.version}</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-enforcer-plugin</artifactId>
            <version>3.6.2</version>
            <executions>
                <execution>
                    <id>one-bouncy-castle-adapter</id>
                    <goals>
                        <goal>enforce</goal>
                    </goals>
                    <configuration>
                        <rules>
                            <bannedDependencies>
                                <excludes>
                                    <exclude>com.itextpdf:bouncy-castle-fips-adapter</exclude>
                                </excludes>
                                <message>Use either bouncy-castle-adapter or bouncy-castle-fips-adapter, never both.</message>
                            </bannedDependencies>
                        </rules>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

package com.example.billing;

import java.nio.file.Path;
import java.util.LinkedHashMap;
import java.util.Map;

import com.itextpdf.barcodes.BarcodeQRCode;
import com.itextpdf.bouncycastleconnector.BouncyCastleFactoryCreator;
import com.itextpdf.commons.actions.EventManager;
import com.itextpdf.forms.PdfAcroForm;
import com.itextpdf.io.font.PdfEncodings;
import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.layout.Document;
import com.itextpdf.pdfa.PdfADocument;
import com.itextpdf.pdfua.PdfUADocument;
import com.itextpdf.signatures.PdfSigner;
import com.itextpdf.styledxmlparser.jsoup.Jsoup;
import com.itextpdf.svg.converter.SvgConverter;

public final class ModuleMap {

    private ModuleMap() {
    }

    private static String jarOf(Class<?> type) {
        var location = type.getProtectionDomain().getCodeSource().getLocation().getPath();
        return Path.of(location).getFileName().toString();
    }

    private static void printResource(String module, String resource) {
        var url = ModuleMap.class.getResource(resource);
        System.out.printf("%-18s %-45s %s%n", module, resource.substring(resource.lastIndexOf('/') + 1),
                url == null ? "missing" : url.getPath().replaceAll("^.*/([^/]+\\.jar).*$", "$1"));
    }

    public static void main(String[] args) {
        Map<String, Class<?>> representatives = new LinkedHashMap<>();
        representatives.put("commons", EventManager.class);
        representatives.put("io", PdfEncodings.class);
        representatives.put("kernel", PdfDocument.class);
        representatives.put("layout", Document.class);
        representatives.put("forms", PdfAcroForm.class);
        representatives.put("sign", PdfSigner.class);
        representatives.put("barcodes", BarcodeQRCode.class);
        representatives.put("pdfa", PdfADocument.class);
        representatives.put("pdfua", PdfUADocument.class);
        representatives.put("svg", SvgConverter.class);
        representatives.put("styled-xml-parser", Jsoup.class);

        representatives.forEach((module, type) ->
                System.out.printf("%-18s %-45s %s%n", module, type.getSimpleName(), jarOf(type)));

        // hyph and font-asian hold resources only, so look for a resource instead of a class
        printResource("hyph", "/com/itextpdf/hyph/fr.xml");
        printResource("font-asian", "/com/itextpdf/io/font/cmap/UniJIS-UTF16-H");

        // the Bouncy Castle adapter is found through a factory, not through a compile-time dependency
        var factory = BouncyCastleFactoryCreator.getFactory();
        System.out.printf("%-18s %-45s %s%n", "bouncy-castle", factory.getClass().getSimpleName(),
                jarOf(factory.getClass()));
    }
}

commons            EventManager                                  commons-9.8.0.jar
io                 PdfEncodings                                  io-9.8.0.jar
kernel             PdfDocument                                   kernel-9.8.0.jar
layout             Document                                      layout-9.8.0.jar
forms              PdfAcroForm                                   forms-9.8.0.jar
sign               PdfSigner                                     sign-9.8.0.jar
barcodes           BarcodeQRCode                                 barcodes-9.8.0.jar
pdfa               PdfADocument                                  pdfa-9.8.0.jar
pdfua              PdfUADocument                                 pdfua-9.8.0.jar
svg                SvgConverter                                  svg-9.8.0.jar
styled-xml-parser  Jsoup                                         styled-xml-parser-9.8.0.jar
hyph               fr.xml                                        hyph-9.8.0.jar
font-asian         UniJIS-UTF16-H                                font-asian-9.8.0.jar
bouncy-castle      BouncyCastleFactory                           bouncy-castle-adapter-9.8.0.jar

package com.example.billing;

import java.io.IOException;
import java.nio.file.Path;

import com.itextpdf.barcodes.BarcodeQRCode;
import com.itextpdf.forms.form.element.InputField;
import com.itextpdf.kernel.font.PdfFont;
import com.itextpdf.kernel.font.PdfFontFactory;
import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfWriter;
import com.itextpdf.kernel.pdf.xobject.PdfFormXObject;
import com.itextpdf.layout.Document;
import com.itextpdf.layout.element.Image;
import com.itextpdf.layout.element.Paragraph;
import com.itextpdf.layout.hyphenation.HyphenationConfig;
import com.itextpdf.svg.converter.SvgConverter;

/**
 * Touches the modules that sit on top of kernel and layout: barcodes, svg, forms, hyph and font-asian.
 */
public final class InvoiceModules {

    private static final String LOGO_SVG = """
            <svg xmlns="http://www.w3.org/2000/svg" width="120" height="40" viewBox="0 0 120 40">
              <rect width="120" height="40" fill="#1f5fa6"/>
              <text x="60" y="26" font-size="16" text-anchor="middle" fill="#ffffff">Bookshelf</text>
            </svg>
            """;

    private InvoiceModules() {
    }

    public static void main(String[] args) throws IOException {
        var target = Path.of(args.length > 0 ? args[0] : "invoice-modules.pdf");
        try (var pdf = new PdfDocument(new PdfWriter(target.toString()));
             var document = new Document(pdf)) {

            // layout (and kernel underneath): the high-level elements
            document.add(new Paragraph("Invoice 2026-0042"));

            // hyph: hyphenation patterns, found through the hyph jar on the class path
            document.add(new Paragraph("Internationalization considerations for typesetting")
                    .setWidth(90)
                    .setHyphenation(new HyphenationConfig("en", "US", 2, 2)));

            // svg: an SVG logo converted to a form XObject, then wrapped in a layout Image
            PdfFormXObject logo = SvgConverter.convertToXObject(LOGO_SVG, pdf);
            document.add(new Image(logo));

            // barcodes: the QR code image of the invoice
            var qr = new BarcodeQRCode("https://example.invalid/verify?invoice=2026-0042");
            document.add(new Image(qr.createFormXObject(pdf)).scaleToFit(80, 80));

            // forms: an AcroForm text field filled in by the customer
            var field = new InputField("customerReference");
            field.setInteractive(true);
            document.add(field.setWidth(150));

            // font-asian: predefined CJK fonts and their CMaps come from this module
            PdfFont cjk = PdfFontFactory.createFont("STSong-Light", "UniGB-UCS2-H",
                    PdfFontFactory.EmbeddingStrategy.PREFER_NOT_EMBEDDED);
            document.add(new Paragraph("书店 Bookshelf").setFont(cjk));
        }
        System.out.println("Wrote " + target.toAbsolutePath());
    }
}