Class PlaceholderHooker

java.lang.Object
pro.verron.officestamper.api.PlaceholderHooker
All Implemented Interfaces:
PreProcessor
public class PlaceholderHooker extends Object implements PreProcessor

The PlaceholderHooker class is a pre-processor that prepares inline placeholders in a WordprocessingMLPackage document. It searches for placeholders introduced by one of the configured opening delimiters and wraps them with a smart tag, so the OfficeStamper engine can process them later.

Brace balancing

A placeholder ends at the closing brace that balances its opening brace, not at the first closing brace encountered. Braces nested inside the placeholder are therefore part of the expression, which is what makes SpEL inline lists and inline maps usable as placeholders:

${ {1, 2, 3} }              -> expression " {1, 2, 3} "   (a SpEL inline list)
${ {'a': 1, 'b': 2} }       -> expression " {'a': 1, 'b': 2} " (a SpEL inline map)
${ {1, 2, 3}.?[#this > 1] } -> expression " {1, 2, 3}.?[#this > 1] "

Malformed placeholders

An opening delimiter that is never balanced by a closing brace is malformed. Rather than leaving the stray delimiter behind — and rather than letting the text that follows it be interpreted as further placeholders — the malformed placeholder spans the remainder of the paragraph and is captured verbatim, delimiters included. The engine then fails to parse it and hands it to the configured ExceptionResolver, so the failure is reported through the usual channel instead of silently corrupting the output.

Single pass

All delimiters are matched in one left-to-right pass, and scanning resumes after each placeholder that has been wrapped. Consequently a placeholder nested inside another one is part of the outer expression and is never wrapped on its own.

  • Constructor Details

    • PlaceholderHooker

      public PlaceholderHooker(String opening, String element)
      Constructs a new PlaceholderHooker recognizing a single opening delimiter.
      Parameters:
      opening - the literal opening delimiter of a placeholder, for instance ${ or #{. It must end with an opening brace.
      element - the name of the smart tag type to wrap matching placeholders with.

    • PlaceholderHooker

      public PlaceholderHooker(Map<String,String> elementByOpening)
      Constructs a new PlaceholderHooker recognizing several opening delimiters in a single pass.
      Parameters:
      elementByOpening - the smart tag type to use for each literal opening delimiter. Every delimiter must end with an opening brace. When several delimiters could match at the same position, the longest one wins.

  • Method Details

    • process

      public void process(org.docx4j.openpackaging.packages.WordprocessingMLPackage document)
      Description copied from interface: PreProcessor
      Processes the provided WordprocessingMLPackage document based on implementation-specific behavior. This method allows for manipulation or transformation of the document, such as modifying its content, sanitizing specific sections, or preparing the document for further actions.
      Specified by:
      process in interface PreProcessor
      Parameters:
      document - the WordprocessingMLPackage document to be processed; cannot be null