docx-stamper is a Java template engine for docx documents. You create a template .docx document with your favorite word processor and feed it to a DocxStamper instance to create a document based on the template at runtime. Example code:

MyContext context = ...;                 // your own POJO against which expressions found in the template
                                         // will be resolved
InputStream template = ...;              // InputStream to your .docx template file
OutputStream out = ...;                  // OutputStream in which to write the resulting .docx document
DocxStamper stamper = new DocxStamper();
stamper.stamp(template, context, out);
out.close();

The main feature of docx-stamper is replacement of expressions within the text of the template document. Simply add expressions like ${person.name} in the text of your .docx template and provide a context object against which the expression can be resolved. docx-stamper will try to keep the original formatting of the text in the template intact.

The value an expression resolves to may be of the following types:

If an expression cannot be resolved successfully, it will be skipped (meaning the expression stays in the document as it was in the template). To support more than the above types you can implement your own TypeResolver. To register your own TypeResolver with docx-stamper, use the following code:

DocxStamper stamper = ...;              
ITypeResolver typeResolver = ...;              // instance of your own ITypeResolver implementation
Class<?> type ...;                             // class of expression values your resolver handles
stamper.getTypeResolverRegistry()
    .registerTypeResolver(type, typeResolver);

Besides replacing expressions, docx-stamper can process comments on paragraphs of text in the template .docx document and do manipulations on the template based on these comments. By default, you can use the following expressions in comments:

If a comment cannot be processed, it is simply skipped. Successfully processed comments are removed from the document. You can add support to more expressions in comments by implementing your own ICommentProcessor. To register you comment processor to docx-stamper, use the following code:

DocxStamper stamper = ...;              
ICommentProcessor commentProcessor = ...;      // instance of your own ICommentProcessor implementation
Class<?> interfaceClass = ...;                 // class of the interface that defines the methods that are
                                               // exposed into the expression language
stamper.getCommentProcessorRegistry()
    .registerCommentProcessor(interfaceClass, commentProcessor);

For an in-depth description of how to create a comment processor, see the javadoc of ICommentProcessor.

The source code contains a set of tests show how to use the features. If you want to run them yourself, clone the repository and run the tests in the main package with the system property -DkeepOutputFile=true so that the resulting .docx documents will not be cleaned up so you can view them. The resulting files will be stored in your local temp folder (watch the logging output for the exact location of the files).

If you want to have a look at the .docx templates used in the tests, have a look at the resources subfolder in the test folder.

To include docx-stamper in your project, you can use the following maven coordinates in your dependency management system:

<dependency>
    <groupId>org.wickedsource</groupId>
    <artifactId>docx-stamper</artifactId>
    <version>1.0.1</version>
</dependency>

If you have an issue or created a comment processor or type resolver that you think deserves to be part of the default distribution, feel free to open an issue or - even better - a pull request with your contribution.

See the Frequently Asked Questions wiki page for some answers to recurring questions.