3.0

[caring-coder]

What's Changed

Major changes

• Processing model overhaul: the engine now iterates hooks in strict document order.
  The API around iteration has been adapted accordingly.
  Consult the root file 3.0_UPDATE.md for details and migration notes.
• Introduced the hook concept: a hook represents a concrete target point in the DOCX to process (e.g., placeholder smart‑tags, inline processors, and comments) and is the unit the iterator walks through.
• New hierarchical scopes with ContextTree and ContextBranch.
  If a placeholder cannot resolve in the current scope, resolution walks up the branch (parent, then ancestors).
  Comment processors that create sub‑scopes (e.g., repeaters) can control whether a hook evaluates in a nested branch or reuses the current one.
• Placeholders are now resolved from smart‑tags produced by preprocessors.
  Ensure the appropriate placeholder preprocessor is included in your OfficeStamperConfiguration (standard presets already do this).
• Simplified lifecycle for comment processors: a processor instance is created for each encountered comment and executed once.

Breaking API Changes

• AbstractCommentProcessor was renamed and simplified into CommentProcessor.
• Removed mutating setters on the Comment interface.
• All previously @Deprecated API methods have been removed.
• Introduced @FunctionalInterface CommentProcessorFactory to create a CommentProcessor from a ProcessorContext.
• Removed DocxDocument from the public API; DocxPart covers previous use cases.
• Replaced EvaluationContextConfigurer with EvaluationContextFactory.
  Provide a factory that creates a fresh EvaluationContext per hook.
• Introduced Insert in the API, allowing resolvers to return content that spans multiple runs instead of a single run.
• OfficeStamper now focuses on OpcPackage handling.
  Stream‑based stamping is handled by the dedicated StreamStamper interface.
• Expression parsing is configurable: you can supply your own org.springframework.expression.ExpressionParser (SpEL by default).
• Removed PlaceholderReplacer in favor of the context‑stack driven placeholder management.

For a complete migration guide and code examples, see 3.0_UPDATE.md and the contributor‑focused HOW_DOES_IT_WORKS.adoc.

Minor changes

• Dependencies: upgraded Spring Expression/Context to 7.0.2 (from 6.2.12).
• Documentation: added an in‑depth how‑to for building custom resolvers and comment processors at engine/src/site/asciidoc/how-to-custom.adoc.
• Documentation: added a deeper architectural overview for contributors in HOW_DOES_IT_WORKS.adoc.
• Tests: extended Docx4J test matrix to include 11.5.7 and 11.5.8.
• Modules: added an asciidoc module to experiment with AsciiDoc ↔ DOCX conversion (useful for tests).
• Modules: added a utils module exposing common utilities; some utilities may spin off into dedicated projects later.

Full Changelog: v2.9.0...v3.0

---

This discussion was created from the release 3.0.