How to implement your own custom comment processors and resolvers

How to implement your own custom comment processors and resolvers

This guide shows you, step by step, how to build your own comment processors and placeholder resolvers in Office‑stamper. It assumes you already know how to stamp a .docx using DocxStamper.

• Comment processors: manipulate the document structure based on expressions inside Word comments (e.g., conditional display, repetition, replacement).
• Placeholder resolvers: turn the evaluated value of an expression (SpEL) into the actual content inserted into the document (e.g., strings, images, formatted values, custom objects).

Where to look in code:

• Comment processing API: pro.verron.officestamper.api.CommentProcessor, pro.verron.officestamper.api.CommentProcessorFactory, pro.verron.officestamper.api.ProcessorContext
• Processor wiring: pro.verron.officestamper.api.OfficeStamperConfiguration, pro.verron.officestamper.core.DocxStamperConfiguration, pro.verron.officestamper.core.DocxStamper
• Resolver API: pro.verron.officestamper.api.ObjectResolver, pro.verron.officestamper.api.StringResolver<T>
• Defaults and examples: engine/src/site/asciidoc/comment-processors.adoc, engine/src/site/asciidoc/template-expressions.adoc, engine/src/site/asciidoc/custom-settings.adoc

Part A — Build a Custom Comment Processor

A custom comment processor lets you define your own comment expressions like watermark("CONFIDENTIAL") or highlightIf(condition) that alter paragraphs, text runs, or larger parts of the document.

package com.acme.docs;

public interface IWatermarkProcessor {
    void watermark(String text);
}

package com.acme.docs;

import org.docx4j.wml.*;
import pro.verron.officestamper.api.*;

public class WatermarkProcessor extends CommentProcessor implements IWatermarkProcessor {
    public WatermarkProcessor(ProcessorContext context) { super(context); }

    @Override
    public void watermark(String text) {
        // Minimal example: prepend a gray, uppercase label to the current paragraph
        paragraph().apply(content -> {
            var run = new R();
            var rPr = new RPr();
            var color = new Color();
            color.setVal("808080");
            rPr.setColor(color);
            var caps = new BooleanDefaultTrue();
            rPr.setCaps(caps);
            run.setRPr(rPr);
            var t = new Text();
            t.setValue("[" + text + "] ");
            run.getContent().add(t);
            content.getContent().addFirst(run);
        });
    }
}

import pro.verron.officestamper.core.DocxStamperConfiguration;

DocxStamperConfiguration configuration = new DocxStamperConfiguration()
    .addCommentProcessor(IWatermarkProcessor.class, WatermarkProcessor::new);

var stamper = new pro.verron.officestamper.core.DocxStamper(configuration);
try (var in = Files.newInputStream(templatePath); var out = Files.newOutputStream(outputPath)) {
    stamper.stamp(in, contextObject, out);
}

public interface IHighlightProcessor {
    void highlightIf(boolean condition, String colorName); // e.g. "yellow"
}

public class HighlightProcessor extends CommentProcessor implements IHighlightProcessor {
    public HighlightProcessor(ProcessorContext ctx) { super(ctx); }

    @Override
    public void highlightIf(boolean condition, String colorName) {
        if (!condition) return;
        paragraph().apply(content -> {
            var r = new R();
            var rPr = new RPr();
            var highlight = new Highlight();
            // For simplicity use named colors accepted by Word (e.g., yellow, green, cyan)
            highlight.setVal(colorName);
            rPr.setHighlight(highlight);
            r.setRPr(rPr);
            content.getContent().add(0, r);
        });
    }
}

public interface IRedactProcessor {
    void redact(String replacement);
}

public class RedactProcessor extends CommentProcessor implements IRedactProcessor {
    public RedactProcessor(ProcessorContext ctx) { super(ctx); }

    @Override
    public void redact(String replacement) {
        paragraph().apply(p -> p.getContent().stream()
            .filter(R.class::isInstance)
            .map(R.class::cast)
            .forEach(r -> r.getContent().stream()
                .filter(Text.class::isInstance)
                .map(Text.class::cast)
                .forEach(t -> t.setValue(replacement))));
    }
}

Part B — Build Custom Placeholder Resolvers

Resolvers convert the result of ${…​} expressions into document content. Use them to support new data types or custom formatting logic.

Resolver types: - StringResolver<T>: for a specific Java type; you return a String to be inserted into the document. - ObjectResolver: a catch‑all strategy that can return strings or special objects supported by the engine (e.g., inline images). Most custom work is done with StringResolver<T>.

The default resolvers include images and various date/time types (see engine/src/site/asciidoc/template-expressions.adoc).

package com.acme.docs;

import pro.verron.officestamper.api.StringResolver;

import java.math.BigDecimal;
import java.text.NumberFormat;
import java.util.Locale;

public record Money(BigDecimal amount,Locale locale) {}

public class MoneyResolver extends StringResolver<Money> {
    public MoneyResolver() {
        super(Money.class);
    }

    @Override
    public String resolve(Money money) {
        var nf = NumberFormat.getCurrencyInstance(money.locale());
        return nf.format(money.amount());
    }
}

DocxStamperConfiguration configuration = new DocxStamperConfiguration()
    .addResolver(new MoneyResolver());

/// @param digits  e.g., "4155551234"
public record PhoneNumber(String digits) {}

public class PhoneNumberResolver extends StringResolver<PhoneNumber> {
    public PhoneNumberResolver() { super(PhoneNumber.class); }

    @Override
    public String resolve(PhoneNumber number) {
        var d = number.digits();
        if (d == null || d.length() < 10) return d;
        return String.format("(%s) %s-%s", d.substring(0,3), d.substring(3,6), d.substring(6));
    }
}

Part C — Wire Everything Together

A canonical setup combining custom processor and resolvers:

var configuration = new pro.verron.officestamper.core.DocxStamperConfiguration()
    // Custom comment processors
    .addCommentProcessor(IWatermarkProcessor.class, WatermarkProcessor::new)
    .addCommentProcessor(IHighlightProcessor.class, HighlightProcessor::new)

    // Custom resolvers (ordering matters: specific before generic)
    .addResolver(new MoneyResolver())
    .addResolver(new PhoneNumberResolver())

    // Exception behavior for expressions
    .setExceptionResolver(pro.verron.officestamper.preset.ExceptionResolvers.throwing());

var stamper = new pro.verron.officestamper.core.DocxStamper(configuration);
try (var in = Files.newInputStream(templateDocx); var out = Files.newOutputStream(stampedDocx)) {
    stamper.stamp(in, context, out);
}

Template snippets: - Comment on a paragraph: watermark("CONFIDENTIAL") - Comment on a paragraph: highlightIf(order.total > 1000, "yellow") - Placeholders: Customer: ${customer.name}, Total: ${invoice.total}, Phone: ${customer.phone}

Part D — Testing Checklist (aligned with the Style Guide)

• Arrange‑Act‑Assert:
  • Arrange: build DocxStamperConfiguration with only the processor/resolver under test, load a minimal .docx template from test resources.
  • Act: call stamper.stamp(context, in, out) to produce an output document.
  • Assert: parse the output with docx4j and verify the structure:
    • For processors: look for new/removed runs, tables, comments removed post‑processing, and expected properties (e.g., RPr highlight).
    • For resolvers: assert text replacements and formatting preservation.
• Edge cases:
  • Nulls and empty collections.
  • Large numbers, localization (for Money, dates).
  • Multiple processors acting on the same paragraph.
• Isolation:
  • Keep tests independent; avoid reusing a single DocxStamperConfiguration across tests if it keeps state.
• Naming:
  • Use descriptive test names (e.g., watermarkAddsGrayLabel_atParagraphStart). '''

Part E — Common Pitfalls and How to Avoid Them

• Forgetting to register: define your interface and implementation, but do not call .addCommentProcessor(…​) — your comment expressions won’t be recognized.
• State leakage: holding fields across calls and forgetting to implement reset().
• Resolver order: adding a generic resolver before specific ones can swallow the value; always add the most specific first.
• Deprecated API: avoid the deprecated setCurrentRun/setParagraph(P) in new processors; use ProcessorContext and Paragraph wrapper.
• Headers/footers: Word comments are not allowed; for header/footer control use #{…​} directive as documented in comment-processors.adoc.
• Error handling surprises: if you do not want stamping to fail, use ExceptionResolvers.passing() or defaulting("…"). '''

Quick Reference

• Register comment processors: DocxStamperConfiguration.addCommentProcessor(MyInterface.class, MyProcessor::new)
• Register resolvers: DocxStamperConfiguration.addResolver(new MyResolver())
• Access context in processors: use paragraph(), comment(), and context() from the base CommentProcessor.
• Stamping: new DocxStamper(configuration).stamp(in, context, out)