Office-stamper is a Java template engine that allows for dynamic creation of DOCX documents at runtime. You design a template using your preferred Word processor; and office-stamper will generate documents based on that template.
-
Expression-based templating: Use Spring Expression Language (SpEL) for powerful template expressions
-
Comment-based processing: Add special instructions as comments in your Word documents
-
Formatting preservation: All formatting from the original template is preserved
-
Custom functions: Extend the templating capabilities with your own functions
-
Type-safe: Strong typing for Java integration
-
Flexible configuration: Customize the behavior to suit your needs
class Example {
static void main(String[] args) {
// an object to use as context for the expressions found in the template.
var context = new YourPojoContext(_, _ , _);
// create a stamper that handles streams
var stamper = OfficeStampers.docxStamper();
var templatePath = Paths.get("your/docx/template/file.docx");
var outputPath = Paths.get("your/desired/output/path.docx");
try(
var template = Files.newInputStream(templatePath);
var output = Files.newOutputStream(outputPath)
) {
stamper.stamp(template, context, output);
}
}
}If you already have a WordprocessingMLPackage (Docx4J document), you can use docxPackageStamper instead:
var stamper = OfficeStampers.docxPackageStamper(OfficeStamperConfigurations.standard());
WordprocessingMLPackage stamped = stamper.stamp(document, context);Office-stamper provides three main configuration presets in OfficeStamperConfigurations to help you get started quickly:
-
minimal(): Sets up the base engine with placeholder preprocessors. Ideal for simple use cases. -
standard(): Builds onminimal()by adding common comment processors (repeat, displayIf, replaceWith) and date/time formatting functions. This is the recommended starting point for most users. -
full(): Further extendsstandard()with additional preprocessors for cleaning up language information and post-processors for cleaning up orphaned footnotes and endnotes.
You can create a configuration via one of these presets and then further customize it:
var configuration = OfficeStamperConfigurations.standard()
.addResolver(new MyCustomResolver());<dependency>
<groupId>pro.verron.office-stamper</groupId>
<artifactId>engine</artifactId>
<version>3.3</version>
</dependency>
<!-- You also need to provide a dependency to Docx4J -->
<dependency>
<groupId>org.docx4j</groupId>
<artifactId>docx4j-core</artifactId>
<version>11.5.11</version>
</dependency>
<dependency>
<groupId>org.docx4j</groupId>
<artifactId>docx4j-JAXB-ReferenceImpl</artifactId>
<version>11.5.11</version>
</dependency>Comprehensive documentation is available at verronpro.github.io/office-stamper.
The latest release is v3.3. See the Release Notes for details.
-
SVG Support: Built-in support for inserting SVG images into documents.
-
Smart Tag Attribute Validation: New utility method to check attributes in DOCX smart tags.
-
Internal Cleanup: Simplified codebase by removing legacy utility classes.
-
Updated Dependencies: Latest Spring and Jackson versions for better security and performance.
-
Expression API Refactor: Improved expression handling with the new
Expressionabstraction. -
Table and Row Manipulation: New public APIs for easier document structure modification.
-
Comment Removal: Optional automatic cleanup of comments after processing.
-
Asciidoc Enhancements: Major improvements to Docx to Asciidoc conversion capabilities.
-
Updated Dependencies: Latest
docx4jand Spring versions.
-
API Consolidation: Continued streamlining of the public API by moving core interfaces like
PlaceholderHooker,CommentHooker, andHookRemoverto thepro.verron.officestamper.apipackage. -
Internal Cleanup: Removed several internal utility classes and simplified the engine’s internal structure for better maintainability.
-
Experimental Features: Moved experimental stamper implementations to a dedicated
pro.verron.officestamper.experimentalpackage to clearly distinguish them from the stable API. -
Logging: Refined logging levels; many verbose debug messages moved to trace level.
-
Processing model overhaul: the engine now iterates hooks (placeholders, inline processors, comments) strictly in document order. See
3.0_UPDATE.mdfor the full rationale and migration guidance. -
New hook concept: each placeholder/comment is treated as a hook — the iterator walks hooks one by one.
-
Hierarchical scopes:
ContextTreeresolve placeholders along the current branch; unresolved values bubble up to parent scopes. -
Preprocessor-driven placeholders: include the placeholder preprocessor in your
OfficeStamperConfiguration(already present in standard presets) to enable resolution. -
Comment processor lifecycle simplified: processors are created per comment and executed once.
-
Postprocessors added:
Postprocessors.removeTags(String)can remove all smart tags used by the engine after processing.
Breaking API highlights:
-
AbstractCommentProcessor→CommentProcessor; introduceCommentProcessorFactory. -
ContextDependentrenamed toHook(inpro.verron.officestamper.api). -
Preprocessors moved:
PlaceholderHookerandCommentHookerare now public inpro.verron.officestamper.api. -
Postprocessors moved:
HookRemoveris now public inpro.verron.officestamper.api. -
EvaluationContextConfigurer→EvaluationContextFactory(fresh context per hook). -
DocxDocumentremoved in favor ofDocxPart. -
New
InsertAPI for multi-run insertions;PlaceholderReplacerremoved. -
OfficeStamperhandlesOpcPackage; useStreamStamperfor stream-to-stream. -
Expression parser is pluggable (
ExpressionParser), SpEL by default. -
DocxStamper#stampnow returns the document. -
Java 23+ required; Maven release set to 25.
Minor updates:
-
Spring dependencies bumped to 7.0.2
-
New docs:
engine/src/site/asciidoc/how-to-custom.adocandHOW_DOES_IT_WORKS.adoc -
Test matrix extended for Docx4J 11.5.7 and 11.5.8
-
New modules:
asciidoc,utils
The source code contains a set of tests showing how to use the features.
If you want to run them yourself, clone the repository and run mvn test.
To view the resulting .docx documents, you can export the stamped documents with the method stamped.save(OutputStream)
If you want to have a look at the .docx templates used in the tests, have a look at the sources subfolder in the test folder.
Contributions are welcome! See the Contributing Guide for details on how to contribute to Office-stamper.