Introduce PdfObjectContributor extension mechanism and update to version 0.8.0

- Add `PdfObjectContributor` for external indirect object contributions.
- Implement `PdfDocumentContext` as an isolated contributor interface.
- Extend `FontRegistry` for indirect font registration.
- Add unit tests ensuring deterministic output and contributor execution order.
- Add new `ContentStream#showTextHex` method for hex-encoded text rendering.

Author: Mirzoxid

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.offixa</groupId>
     <artifactId>pdfixa-core</artifactId>
-    <version>0.7.0</version>
+    <version>0.8.0</version>
     <packaging>jar</packaging>
 
     <name>PDFixa Core</name>

src/main/java/io/offixa/pdfixa/core/content/ContentStream.java

@@ -156,6 +156,19 @@ public ContentStream showText(String text) {
         return this;
     }
 
+    /**
+     * Appends {@code <hexString> Tj\n} — show text from a hex-encoded string.
+     *
+     * <p>The caller is responsible for providing valid hex digits.
+     * This method does not affect or share logic with {@link #showText}.
+     *
+     * @param hexString hex-encoded byte sequence (without angle brackets)
+     */
+    public ContentStream showTextHex(String hexString) {
+        buf.append('<').append(hexString).append("> Tj\n");
+        return this;
+    }
+
     // ── Graphics operators ─────────────────────────────────────────────────
 
     /**

src/main/java/io/offixa/pdfixa/core/document/FontRegistry.java

@@ -25,6 +25,7 @@ public final class FontRegistry {
 
     private final Map<String, String> nameToAlias = new LinkedHashMap<>();
     private final Map<String, String> aliasToName = new LinkedHashMap<>();
+    private final Map<String, Integer> indirectFontObjects = new LinkedHashMap<>();
     private int nextIndex = 1;
 
     /**
@@ -50,6 +51,46 @@ public String getFontName(String alias) {
         return aliasToName.get(alias);
     }
 
+    /**
+     * Registers an indirect font whose definition lives in a separate
+     * indirect PDF object.
+     *
+     * <p>Alias generation uses the same {@code nextIndex} counter as
+     * {@link #getAlias} to preserve deterministic numbering.
+     *
+     * @param fontName     logical font name
+     * @param objectNumber the indirect object number holding the font definition
+     * @return the alias assigned (e.g. {@code "F3"})
+     */
+    public String registerIndirectFont(String fontName, int objectNumber) {
+        String alias = "F" + nextIndex++;
+        nameToAlias.put(fontName, alias);
+        aliasToName.put(alias, fontName);
+        indirectFontObjects.put(alias, objectNumber);
+        return alias;
+    }
+
+    /**
+     * Returns {@code true} if the given alias refers to an indirect font
+     * (registered via {@link #registerIndirectFont}).
+     */
+    public boolean isIndirect(String alias) {
+        return indirectFontObjects.containsKey(alias);
+    }
+
+    /**
+     * Returns the indirect object number for the given alias.
+     *
+     * @throws IllegalArgumentException if the alias is not an indirect font
+     */
+    public int getIndirectObjectNumber(String alias) {
+        Integer objNum = indirectFontObjects.get(alias);
+        if (objNum == null) {
+            throw new IllegalArgumentException("not an indirect font alias: " + alias);
+        }
+        return objNum;
+    }
+
     /**
      * Returns an unmodifiable, insertion-ordered view of all alias → font-name
      * mappings currently held by this registry.

src/main/java/io/offixa/pdfixa/core/document/PdfDocument.java

@@ -52,6 +52,7 @@ public final class PdfDocument {
     private final int catalogNum;
     private final int pagesNum;
     private final List<PdfPage> pages = new ArrayList<>();
+    private final List<PdfObjectContributor> contributors = new ArrayList<>();
     private PdfInfo info;
     private boolean saved;
 
@@ -151,6 +152,23 @@ public PdfImage addPngImage(byte[] pngBytes) {
         return img;
     }
 
+    /**
+     * Registers a contributor that will be invoked during {@link #save} to
+     * inject additional indirect objects into the document.
+     *
+     * <p>Contributors are executed in registration order, before page
+     * resource wiring begins.
+     *
+     * @param contributor the contributor to register; must not be {@code null}
+     */
+    public void registerContributor(PdfObjectContributor contributor) {
+        Objects.requireNonNull(contributor, "contributor");
+        if (saved) {
+            throw new IllegalStateException("document has already been saved");
+        }
+        contributors.add(contributor);
+    }
+
     /**
      * Sets document metadata to be written into the PDF {@code /Info} dictionary.
      *
@@ -186,6 +204,13 @@ public void save(OutputStream out) throws IOException {
         }
         saved = true;
 
+        if (!contributors.isEmpty()) {
+            PdfDocumentContext ctx = new PdfDocumentContext(registry, fontRegistry);
+            for (PdfObjectContributor c : contributors) {
+                c.contribute(ctx);
+            }
+        }
+
         MessageDigest digest = sha256Digest();
         DigestOutputStream digestOut = new DigestOutputStream(out, digest);
         PdfWriter writer = new PdfWriter(digestOut);
@@ -323,15 +348,20 @@ private void wirePage(PdfPage page) {
                     for (String alias : usedFonts) {
                         if (!firstFont) w.writeSpace();
                         firstFont = false;
-                        String baseFontName = fontRegistry.getFontName(alias);
-                        w.writeName(alias); w.writeSpace();
-                        w.beginDictionary();
-                        w.writeName("Type");     w.writeSpace(); w.writeName("Font");
-                        w.writeSpace();
-                        w.writeName("Subtype");  w.writeSpace(); w.writeName("Type1");
-                        w.writeSpace();
-                        w.writeName("BaseFont"); w.writeSpace(); w.writeName(baseFontName);
-                        w.endDictionary();
+                        if (fontRegistry.isIndirect(alias)) {
+                            w.writeName(alias); w.writeSpace();
+                            w.writeReference(fontRegistry.getIndirectObjectNumber(alias), 0);
+                        } else {
+                            String baseFontName = fontRegistry.getFontName(alias);
+                            w.writeName(alias); w.writeSpace();
+                            w.beginDictionary();
+                            w.writeName("Type");     w.writeSpace(); w.writeName("Font");
+                            w.writeSpace();
+                            w.writeName("Subtype");  w.writeSpace(); w.writeName("Type1");
+                            w.writeSpace();
+                            w.writeName("BaseFont"); w.writeSpace(); w.writeName(baseFontName);
+                            w.endDictionary();
+                        }
                     }
                     w.endDictionary();
                 }

src/main/java/io/offixa/pdfixa/core/document/PdfDocumentContext.java

@@ -0,0 +1,60 @@
+package io.offixa.pdfixa.core.document;
+
+import io.offixa.pdfixa.core.internal.ObjectRegistry;
+import io.offixa.pdfixa.core.writer.PdfSerializable;
+
+import java.util.Objects;
+
+/**
+ * Facade provided to {@link PdfObjectContributor} implementations during
+ * {@link PdfDocument#save}.
+ *
+ * <p>Exposes only the operations a contributor needs — object allocation,
+ * body assignment, and indirect font registration — without leaking the
+ * {@link ObjectRegistry} type or any other internal infrastructure.
+ *
+ * <p>Instances are created exclusively by {@link PdfDocument}; the
+ * constructor is package-private.
+ */
+public final class PdfDocumentContext {
+
+    private final ObjectRegistry registry;
+    private final FontRegistry fontRegistry;
+
+    PdfDocumentContext(ObjectRegistry registry, FontRegistry fontRegistry) {
+        this.registry = registry;
+        this.fontRegistry = fontRegistry;
+    }
+
+    /**
+     * Allocates the next indirect object number.
+     *
+     * @return the newly allocated object number
+     */
+    public int allocateObject() {
+        return registry.allocate();
+    }
+
+    /**
+     * Assigns the serialization body for a previously allocated object.
+     *
+     * @param objNum object number returned by {@link #allocateObject()}
+     * @param body   non-null serializer for the object's content tokens
+     */
+    public void setObjectBody(int objNum, PdfSerializable body) {
+        Objects.requireNonNull(body, "body");
+        registry.setBody(objNum, body);
+    }
+
+    /**
+     * Registers an indirect font whose definition lives in a separate
+     * indirect object (allocated via {@link #allocateObject()}).
+     *
+     * @param fontName     logical font name
+     * @param objectNumber the indirect object number holding the font definition
+     * @return the alias assigned (e.g. {@code "F3"})
+     */
+    public String registerIndirectFont(String fontName, int objectNumber) {
+        return fontRegistry.registerIndirectFont(fontName, objectNumber);
+    }
+}

src/main/java/io/offixa/pdfixa/core/document/PdfObjectContributor.java

@@ -0,0 +1,14 @@
+package io.offixa.pdfixa.core.document;
+
+/**
+ * Extension point for external modules to register indirect PDF objects
+ * without accessing internal packages directly.
+ *
+ * <p>Implementations are registered via
+ * {@link PdfDocument#registerContributor(PdfObjectContributor)} and invoked
+ * during {@link PdfDocument#save} — before page resource wiring — in
+ * registration order.
+ */
+public interface PdfObjectContributor {
+    void contribute(PdfDocumentContext context);
+}

src/test/java/io/offixa/pdfixa/core/document/PdfObjectContributorTest.java

@@ -0,0 +1,94 @@
+package io.offixa.pdfixa.core.document;
+
+import org.junit.jupiter.api.Test;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Tests for the {@link PdfObjectContributor} extension mechanism introduced
+ * in pdfixa-core 0.8.0.
+ */
+class PdfObjectContributorTest {
+
+    @Test
+    void contributorAllocatesObjectDeterministically() throws IOException {
+        byte[] run1 = buildWithDummyContributor();
+        byte[] run2 = buildWithDummyContributor();
+
+        assertArrayEquals(run1, run2,
+                "Document with a contributor must produce bit-for-bit identical output across runs");
+    }
+
+    @Test
+    void noContributorProducesSameOutputAsPlainDocument() throws IOException {
+        byte[] withoutContributor = buildPlain();
+        byte[] withEmptyList = buildPlain();
+
+        assertArrayEquals(withoutContributor, withEmptyList,
+                "Empty contributor list must produce byte-identical output to a plain document");
+    }
+
+    @Test
+    void contributorExecutionOrderMatchesRegistrationOrder() throws IOException {
+        StringBuilder order = new StringBuilder();
+
+        PdfDocument doc = new PdfDocument();
+        doc.addPage().getContent()
+                .beginText()
+                .setFont("Helvetica", 12)
+                .moveText(72, 700)
+                .showText("test")
+                .endText();
+
+        doc.registerContributor(ctx -> order.append("A"));
+        doc.registerContributor(ctx -> order.append("B"));
+        doc.registerContributor(ctx -> order.append("C"));
+
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        doc.save(baos);
+
+        assertEquals("ABC", order.toString(),
+                "Contributors must execute in registration order");
+    }
+
+    private static byte[] buildWithDummyContributor() throws IOException {
+        PdfDocument doc = new PdfDocument();
+        PdfPage page = doc.addPage();
+        page.getContent()
+                .beginText()
+                .setFont("Helvetica", 12)
+                .moveText(72, 700)
+                .showText("contributor test")
+                .endText();
+
+        doc.registerContributor(ctx -> {
+            int objNum = ctx.allocateObject();
+            ctx.setObjectBody(objNum, w -> {
+                w.beginDictionary();
+                w.writeName("Type");  w.writeSpace(); w.writeName("DummyObj");
+                w.endDictionary();
+            });
+        });
+
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        doc.save(baos);
+        return baos.toByteArray();
+    }
+
+    private static byte[] buildPlain() throws IOException {
+        PdfDocument doc = new PdfDocument();
+        PdfPage page = doc.addPage();
+        page.getContent()
+                .beginText()
+                .setFont("Helvetica", 12)
+                .moveText(72, 700)
+                .showText("plain test")
+                .endText();
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        doc.save(baos);
+        return baos.toByteArray();
+    }
+}