Oct 18 2013

docx4j 3.0 – what you need to know

docx4j 3.0 (beta for which will be available shortly) contains a lot of changes, some big, some small.

Here are the most visible (see our changelog for the rest):


docx4j 3.0 uses slf4j, instead of log4j.

As the slf4j website puts it:

The Simple Logging Facade for Java (SLF4J) serves as a simple facade or abstraction for various logging frameworks (e.g. java.util.logging, logback, log4j) allowing the end user to plug in the desired logging framework at deployment time.

So you need the slf4j api jar on your classpath:


If you want to use log4j, then include it, and:


XHTML Import

The XHTML Import functionality is now a separate project on GitHub.

The reason being that its main dependency – Flying Saucer – is licensed under LGPL v2.1 (as opposed to ASL v2, which docx4j’s other dependencies use).

If you want this functionality, you have to add these jars to your classpath.  We’ll update this post with their coordinates once they are in Maven Central.

Docx4j facade

3.0 contains a facade providing clean access to some typical uses of docx4j:
  • Loading a document
  • Saving a document
  • Binding xml to content controls in a document
  • Exporting the document (to HTML, or PDF and other formats supported by the FO renderer)

You don’t have to use this – in that existing code should continue to work – but the facade is the right way to do things.  Behind the facade is a major rethink/cleanup to the export architecture/implementation, contributed by Alberto.


The key technology underlying docx4j – and a major differentiator from Apache POI – is JAXB.

There is a JAXB reference implementation; the JAXB baked into Java 6 and 7 is based on it.

Prior to v3, you had to use the reference implementation, or the implementation included in the JDK.

With v3, you can choose to use EclipseLink MOXy instead.  To do so, simply include docx4j-MOXy-JAXBContext-3.0.0.jar and the MOXy jars on your classpath.

Sample code

The docx4j samples have relocated to src/samples

One Response so far

  1. 1

    Yonatan said,

    October 22, 2013 @ 9:31 pm

    Hi Jason,

    Thanks for the work you put into this superb tool! I’m currently using version 2.8.1 and 3.0.0-Alpha and I would like to know if you have a release plan set for version 3.0.0?


    – Yonatan

Comment RSS