XDocReport: merging a docx template with a Java model to produce a report

The idea is a document template, not a document API

XDocReport means XML Document reporting, and the repository description states the mechanism plainly. It is a Java API to merge an XML document created with MS Office, meaning docx, or with OpenOffice and LibreOffice, meaning odt, with a Java model to generate a report, and to convert it if you need another format such as PDF or XHTML.

That framing is the whole value proposition, and it is aimed at a specific kind of organisation. A Java service holds the data, and the shape of the output is designed by somebody who is not a programmer, in Word or in LibreOffice, using the office tools they already have. The document becomes a template, the Java model supplies the values, and the merge produces the finished report.

The alternative designs all start from the code. You build the document programmatically, which means the layout decisions live in Java, which means changing a header means a developer and a deployment. XDocReport moves the layout into the office file and leaves the data in the code, which is the arrangement most enterprise reporting needs and most developers find tedious to build themselves.

The project is published to Maven Central under the group fr.opensagres.xdocreport, and the README points at a Getting Started wiki page as the place to start rather than trying to document the whole flow in the repository itself.

The module layout, as it appears in the repository

The top level of the repository shows a project that has been decomposed over a long period, and the directory names are the best available description of its structure.

There is a core/ directory, a converter/ directory, and a document/ directory. Three directories are named for deployment and integration targets rather than for functionality: remoting/, gae/ and sandbox/. The gae/ directory is the Google App Engine integration, and remoting/ is the remote invocation layer, which is what the REST demos in the README exercise.

There is a template/ directory for the template handling, a tools/ directory, a thirdparties-extension/ directory for the third party integrations, an integrationtests/ directory, and an uberjar/ directory for the single jar build. The pom.xml at the root is the Maven reactor that ties them together, and header.txt sits at the top level as the licence header applied to source files, which is a common convention in Maven projects that check header consistency during the build.

The uberjar/ directory is worth noticing, because it signals a deployment model. A single self-contained jar is what you want when the reporting engine has to be dropped into a customer environment, a legacy application server, or an environment where dependency resolution is a problem. The remoting/ and gae/ directories suggest the same project is expected to run in quite different hosts, from a plain Java application to a Google App Engine deployment to a Tomcat web application.

A .travis.yml at the root and a .github/ directory cover continuous integration, and the build status badge in the README points at Travis CI.

The three sample applications and where their source lives

The README offers three online demos, and the differences between them are the clearest description of what the library can be used for.

The first is a web application that uses XDocReport to generate a report, at the demo-webapp path. The second is a web application that uses a REST service to generate a report, at the rest-service-reporting path. The third is a web application that uses a REST service to convert docx and odt to pdf and xhtml, at the rest-service-converter path.

Read them in order and you get the three deployment shapes the library supports. Embed the engine in your own web application and call it directly. Expose the reporting function over HTTP as a service. Or expose the conversion as a service, which is the docx-to-pdf pipeline that a lot of people actually want, since the template lives in Word and the output has to be a PDF.

The source code for all three is in a separate repository, xdocreport.samples, and the README links it. That split is deliberate and it is the licence story, which is the next thing to look at.

The demos themselves are hosted on a mytomcatapp-opensagres.rhcloud.com address. The important thing to notice is that they are described as something you can test the online demo with, and they are pointed at as three distinct applications rather than one demo with different parameters, which is what tells you the library is meant to sit inside a service architecture rather than only inside a single desktop process.

Why the samples are LGPL and the core is MIT

The licence section is the most consequential part of this README, and it explains itself rather than leaving you to work it out.

XDocReport code is licensed under the MIT license but the samples are licensed under the LGPL license, this is why. The reasoning is given under the XDocReport Core heading. Because we love to share our code, we prefer a very weak license, which is why the MIT License was chosen for the core modules. And MIT License is called a weak license which allows redistribution and modification, although contributions are appreciated.

The reason the samples differ is iText. iText is a very powerful Java library for creating PDF, and the iText based converter is by far the best PDF converter the project provides. But iText 2.1.7 comes with an LGPL license which is not compliant with the MIT License. So people who use and redistribute xdocreport with the iText based converter have to comply with the LGPL license, and that is exactly what the project does with the samples, which are licensed under LGPL and not MIT.

So the licensing story is: the core is MIT, and anything that pulls in the iText based PDF converter is LGPL. This is a deliberate and clearly communicated structure, and it is a good sign about the project, because the alternative would be to license the whole thing LGPL and hope nobody notices, or to drop the best converter.

For an adopter, the practical consequence is that you have to know which converter you are shipping. If your usage is internal, the distinction may not matter to you. If you redistribute, it does. And the note that the samples are LGPL applies to the sample project specifically, not to a reading of the core, so the split has to be evaluated module by module rather than taken at the repository level.

Note also that the repository's own licence field is listed as unknown, and there is no LICENSE file in the top level listing, so the statement in the README is the only description of the terms. That is a detail to confirm with the project rather than assume.

What the README does not tell you

This is a short README, and for a library of this age and scope that is unusual, so it is worth being clear about what a reader has to go and find elsewhere.

There is no installation section. The Maven coordinates are visible in the badge, fr.opensagres.xdocreport, and the build is Maven from the root pom.xml, but the README does not give a dependency snippet, does not say which Java version is required, and does not list the modules you would declare as dependencies. The Getting Started wiki is named as the place to begin, and that is where the setup detail lives.

There is no description of the merge syntax. How a Java bean maps onto a tag or a placeholder inside the Word document is the central question of the library, and the README does not answer it. There is also no list of the supported conversion formats beyond PDF and XHTML, no mention of the templates that ship with the project, and no statement about thread safety or performance.

There is no changelog and no GitHub releases. The repository is not archived and the last push was on 2026-09-01, so work is continuing, but the history of the project is not visible from the repository itself.

None of that is disqualifying. A library that has been developed for long enough to have a remoting layer, a Google App Engine integration and an uberjar build has its documentation elsewhere by now, and pointing at a wiki is a normal convention for a project of this vintage. But it does mean that evaluating XDocReport properly means reading the wiki, not the README, and that the first question to ask the maintainers is about the module and converter you would actually depend on.

Editorial conclusion

XDocReport is a good pick for a Java team that already has business users designing report templates in Word or LibreOffice, because letting the template live in the tool your users know is worth more than a pure programmatic document API, and the converter separation means you can pick a PDF path with the licence terms you can accept; it is the wrong pick if you need a clean MIT dependency tree, because the iText based converter pulls in LGPL terms, and before you adopt it you should confirm which converter you intend to ship and read the Getting Started wiki, because the README holds almost no setup detail.

Frequently asked questions

Official sources

1. Issues
2. opensagres/xdocreport on GitHub
3. Project website
4. README