What is docx4j?

docx4j is an open source (Apache v2) library for creating, editing, and saving OpenXML “packages”, including docx, pptx, and xslx.  It is similar to Microsoft’s OpenXML SDK, but for Java rather than .NET.   It uses JAXB to create the Java objects out of the OpenXML parts.

Notable features for docx include export as HTML or PDF, and CustomXML databinding for document generation (including our OpenDoPE convention support for processing repeats and conditions).

The docx4j project started in October 2007.

What’s new?

This is mainly a maintenance release; things of note include:

• Preparation for including docx4j in Maven Central
• mc:AlternateContent preprocessor, allowing graceful degradation of Word 2010 specific content
• docx4j.properties, supports configuration of default page size, margins, orientation; also ability to set some of the doc props metadata (Application & AppVersion; dc.creator & dc.lastModifiedBy).
• HtmlExporterNG2,(Pdf)Conversion, SvgExporter: storing any images is delegated to a
  ConversionImageHandler that may be passed as a conversion parameter. Default implementation: DefaultConversionImageHandler
• OpenDoPE changes – see summary post in the sub-forum

Where do you get it?

Binaries: You can download a jar alone or a tar.gz with all deps or pick and choose.

Source: Checkout the source from SVN (use the pom.xml file to satisfy the dependencies eg with m2eclipse as explain in the Maven blog post, or download them from one of the links above)

Maven: From Maven Central; please see the blog post referenced above.

Getting Started

See the “Getting Started” guide.

Thanks to our contributors

A number of contributions have made this release what it is; thanks very much to those who contributed.

Contributors to this release and a more complete list of changes may be found in README.txt

This makes it really easy to get going with docx4j.  With Eclipse and m2eclipse installed, you just add docx4j, and you’re done.  No need to mess around with manually installing jars, setting class paths etc.

This post demonstrates that, starting with a fresh OS (Win 7 is used, but these steps would work equally well on OSX or Linux).

Step 1 – Install the JDK

For the purposes of this article, I used JDK 7, but docx4j works with Java 6 and 1.5.

Step 2 – Install Eclipse Indigo (3.7.1)

I normally download the version for J2EE developers. Unzip it and run eclipse

Step 3 – Install m2eclipse.

In Eclipse, click Help > Install New Software.

Type “http://download.eclipse.org/technology/m2e/releases” in the “Work with” field as shown:

then follow the prompts.

Step 4 – Create your Maven project

In Eclipse, File > New > Project.., then choose Maven project

You should see:

Check “Create a simple project (skip archetype selection)” then press next.

Allocate group and artifact id (what you choose as your artifact id will become the name of your new project in Eclipse):

Press finish

This will create a project with directories using Maven conventions:

(Note: If your starting point is a new or existing Java project in Eclipse, you can right click on the project, then choose Configure > Convert to Maven project)

Step 5 – Add docx4j to your POM

Double Click on pom.xml

Next click on the dependencies tab, then click the “add dependency” button, and enter the docx4j coordinates as shown in the image below:

The result is this pom:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>mygroup</groupId>
  <artifactId>myartifact</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <dependencies>
  	<dependency>
  		<groupId>org.docx4j</groupId>
  		<artifactId>docx4j</artifactId>
  		<version>2.7.1</version>
  	</dependency>
  </dependencies>
</project>

Ctrl-S to save it.

m2eclipse may take some time to download the dependencies.

When it has finished, you should be able to see them:

Step 6 – Create HelloMavenCentral.java

If you made a Maven project as per step 4 above, you should already have src/main/java on your build path.

If not, create the folder and add it.

Now add a new class:

import org.docx4j.openpackaging.packages.WordprocessingMLPackage;

public class HelloMavenCentral {

	public static void main(String[] args) throws Exception {

		WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.createPackage();

		wordMLPackage.getMainDocumentPart()
			.addStyledParagraphOfText("Title", "Hello Maven Central");

		wordMLPackage.getMainDocumentPart().addParagraphOfText("from docx4j!");

		// Now save it
		wordMLPackage.save(new java.io.File(System.getProperty("user.dir") + "/helloMavenCentral.docx") );

	}
}

Step 7 – Click Run

When you click run, all being well, a new docx called helloMavenCentral.docx will be saved.

You can open it in Word (or anything else which can read docx), or unzip it to inspect its contents.

Step 8 – Adding docx4j.properties

One final thing. If you plan on creating documents from scratch using docx4j, it is useful to set paper size etc, via docx4j.properties. Put something like the following on your path:

# Page size: use a value from org.docx4j.model.structure.PageSizePaper enum
# eg A4, LETTER
docx4j.PageSize=LETTER
# Page size: use a value from org.docx4j.model.structure.MarginsWellKnown enum
docx4j.PageMargins=NORMAL
docx4j.PageOrientationLandscape=false

# Page size: use a value from org.pptx4j.model.SlideSizesWellKnown enum
# eg A4, LETTER
pptx4j.PageSize=LETTER
pptx4j.PageOrientationLandscape=false

# These will be injected into docProps/app.xml
# if App.Write=true
docx4j.App.write=true
docx4j.Application=docx4j
docx4j.AppVersion=2.7.1
# of the form XX.YYYY where X and Y represent numerical values

# These will be injected into docProps/core.xml
docx4j.dc.write=true
docx4j.dc.creator.value=docx4j
docx4j.dc.lastModifiedBy.value=docx4j

#
#docx4j.McPreprocessor=true

# If you haven't configured log4j yourself
# docx4j will autoconfigure it.  Set this to true to disable that
docx4j.Log4j.Configurator.disabled=false

And that’s it. For more information on docx4j, see our Getting Started document.

Please click the +1 button if you found this article helpful.

I can only think Google doesn’t at all like a hostname other than “www”.

So I’ve moved everything to www.docx4java.org

This shouldn’t impact you (other than having to find this new site, and update any bookmarks) unless you are using svn and have docx4j checked out.

If you have the docx4j repository checked out, you’ll want to do something like:

 svn switch --relocate http://dev.plutext.org/svn/docx4j/trunk/docx4j http://www.docx4java.org/svn/docx4j/trunk/docx4j

If you are on Windows and using TortoiseSVN, use Tortoise’s “relocate” command (not its “switch” command).

That should make your SVN checkout work again.

There may be various broken or outdated links on the website.  I guess I’ll fix these over time.

If you encounter any other issues, then please post to http://www.docx4java.org/forums/announces/docx4j-has-a-new-home-t815.html

The Microsoft employees who ran that site have shut it down.  Not stopped accepting new submissions, but shut it down entirely.

As a result, all the community submitted data is lost to the community. Or has been taken from us, since it is no longer shared.

People have been asking me why Google bought Docverse.

Surely, Google already has the collaboration smarts?  After all, it was Google Docs which made document collaboration mainstream.  And it is Google Wave which is arguably now taking it to the next level.  Google also employs Neil Fraser, and it recently bought Etherpad.

So what does Docverse give them?  And why pay so much?

Its not about getting the people – Docverse is a small team – although additional engineers with domain knowledge are surely nice to have.

What this is about is taking away the reasons for upgrading to Office 2010, and more particularly, Sharepoint 2010.  Any business which takes Sharepoint 2010 is making a commitment to Microsoft technology for the next decade or so, which effectively shuts Google enterprise products out, and might even lead these customers to use IIS etc for their consumer web sites (which would also be bad for Google).

So Google is doing what it can to give businesses reason to stop and think.

In the 6 months ended 31 December 2009, Microsoft’s Business Products Division had revenue of $9.149 billion, and operating income of $5.867 billion.  Office is responsible for around 90% of that.

What would it be worth to Google, if it could put a 5% dent in those figures? 5% of $9 billion is $450 million. 0.5% is $45 million.

Put one way, if the people responsible for just 0.5% of Office purchase decisions look at Google + Docverse and say “hey, we can stick with the version of Office we’ve got; we don’t need to buy Office 2010 and Sharepoint to do real time collaboration”, then the Docverse acquisition has made sense for Google.

But really, its about the larger ecosystems, not just the Office purchase.  An Office purchase is a commitment to Windows on the client, and possibly Windows on the server.  And it has network effects along the supply chain (people you exchange documents with).  So preventing an Office purchase frees up a lot of other spend.

Now, Google needs to prove that with Google you get:

• the ability to keep using your existing Microsoft Office (Docverse’s contribution)
• real-time collaboration (without Office 2010 or Sharepoint 2010)
• web-based editing if/when you need it

Docverse gives Google slick looking Add-Ins for Word, Powerpoint and Excel.

Time is of the essence.  Office 2010 will be launched for businesses on May 12, and available online/retail in June.

The adds-ins are worth a few months head start.  (So maybe it is about the people after all?)

Now Google needs to integrate Docverse in to Google Apps.  Rip/replace of the existing Docverse back-end (and probably much of their Word Add-In, since it sends the whole document every time you save, not just the diffs – something Plutext has had right since the beginning) will take a while.  However, the rip/replace isn’t necessary for a rudimentary integration into Google Docs.  What is critical is to make Docverse’s server-side differencing work on Google scale and interoperate with the Google Docs webapp.  Same  for presentations and slides.

It’ll be interesting to see how quickly this can be done.

The robot is at docxwave@appspot.com

This is especially useful if your Word document contains tables or images, because copy/pasting from Word leaves them out. Adding the document as an attachment in Wave wouldn’t be the answer either, because that doesn’t bring the power of Wave to bear on the doc at all.

This wave was the announcement and is for support (Wave account required):

If you read the patent in question, US patent number 5787449, you’ll see that the so-called invention was entirely obvious, consisting only of annotations pointing to positions in a character stream (as distinct from embedded within it).

Microsoft suggested some prior art, but nothing which knocked out the patent.

What i4i chose to call a ‘metacode’ sounds a lot like the markers described in 1986 in Data Structures in the Andrew Text Editor:

A marker is a data structure that refers to a portion of the text of a document; the portion starting at some character and extending for some length.

The people involved in the Text Encoding Initiative guidelines leading up to publication of their proposal 3 in 1994 (which is before the patent was filed) probably discussed and published relevant stuff as well – did anyone ask them? [Edit 18/9/09] Hmmm, Markup Reconsidered (presented in 1992) says:

A word should be said about so-called out-of-line markup, non-embedded structure that conforms to the syntactic requirements of a given markup standard

and references a 1992 document: David Barnard, Lou Burnard, Jean-Pierre Gaspart, Lynne Price, C.M. Sperberg-McQueen, and Nino Varile, “Notes on SGML Solutions to Markup Problems”, TEI MLW18, which I haven’t looked at.  And “Refining our Notion of What Text Really Is: The Problem of Overlapping Hierarchies” contains a wealth of historical references which probably contain stuff.

[Added 18/9/09] Most interestingly, Ted Nelson states in “Embedded Markup Considered Harmful” that Xanadu has used parallel markup since the 1960′s!  Unfortunately, he didn’t publish much about it (which limits its value as prior art); though Rick points out that Nelson disclosed some stuff in his 1992 book.

So the i4i patent should have been knocked out:

• because it was obvious, and
• because the USPTO and Microsoft should have found prior art.

In any case, the patent system should be reformed, so that, if you must have a patent system at all, and one in which software and algorithms are effectively patentable, such patents last for no more than say 4 years from the priority date.  Their patent would have expired in 1998 (the same year it was granted!).

In this case, what i4i patented has been independently thought of (ie invented) as part of one approach to the related problem of overlapping markup.  Independent invention should also be a defense (although that might not have helped Microsoft in this case)

A further thought: what if patentees were liable every time they described something as new if it could be shown that it wasn’t? That might give them pause for thought.

For a good while now, with Plutext you’ve been able to be in a Word document at the same time as your co-workers – provided all you were doing was working on tables and paragraphs (editing them, inserting, deleting or moving them around).

With this latest release, you can add images and Word comments, and have them replicate properly between Word 2007 users.

Here is a screencast of this in action:

If you want to play with this yourself, you can download our Word Add-In and give it a shot!

For username & password, please see here. The password is “tester”.

For detailed instructions, see this PDF, or this earlier screencast.

If you’d like to chat about your own Plutext installation, please contact us using this form.

Steve Balmer gave hints in 2 separate reports at the beginning of the month that they’ll be announcing their in-Office collaboration stuff this week.

The first report was in www.cio.co.uk

Ballmer:So we are embracing Software + Services, Cloud Computing as hard as anybody. By the time we finish our Professional Developers Conference this month, I think you’ll have to say that there is nobody out there with as wide a range of Cloud Computing services as Microsoft, including, dare I say it, Google …

CIO: Steve, I guess the $64,000 question from a lot of people’s point of view is, is there going to be an Office for the Web, something that really competes head on with Google Docs, Google Apps?

Ballmer: .. I think what people want is something as rich as Microsoft Office, something that you can ‘click and run’, if you are not at your own desk. Something that is compatible, document-wise with Microsoft Office and something that offers the kind of joint editing capabilities that is nice in Google Docs and Spreadsheets. Will Microsoft Office offer that? Yes! Standby for details in the next month.

CIO: So, in the backend of Microsoft R&D, are there people beavering away at versions of Word, PowerPoint, Excel, etc, that are purely web based? Or, is it always going to be this hybrid?

Ballmer: What does it mean to be purely Web based? Do we want them to be as only as powerful as ‘runs in a browser’? No. We want software that is more powerful than runs in a browser. Does that mean we will not have some neat stuff that does run in the browser? No.

We think you’ll actually want the full power of Word, Excel and PowerPoint – and you’ll want to be able to get that simply. But, if you just happen to be in an Internet cafe kiosk and you want to do some light editing, perhaps we need to have a way to support you in that as well, inside the browser. ..

In another, in response to a question about Office Live, he said:

“Office Live has a few things left it needs to do. Number one, and probably most important, is to make sure that people using Office have greater ability to collaborate with one another. We have some of that today with [Office Live] Workspaces, as well as that we’ve got SharePoint; we can do more and some of those things will be better than the other alternatives.

Number two, is when we do Office Live, it has to be true to Office; you’ll need to be able to have full Office documents and programs and share them.

Number three, we have to make it so that – most people use Office most of the time from a single machine. But if you’re away from your desk, at a cafe, a kiosk or your school library, and you don’t have Office, you’ll want to be able to do something quickly; we have to make sure you can get it easily, stream it down, put it in a browser, something like that there… details coming in a few weeks.

I’m not going to write here what I think they are likely to announce.  More sensible to wait a little longer.  It will be interesting though to see what is available immediately, and how much is just vaporware.

But sometimes, Sun is just too slow to fix bugs (or make the fixes available). And this is still their role, even when a user has a fix to contribute.

Take the following 2 which have bitten me this week:

1. Preferences broken if you use org.apache.xalan.processor.TransformerFactoryImpl
2. Printing on Ubuntu 7.10

Fixes haven’t become available for either of these yet on Java 6 (though the first has been closed  here and here)

Sun really needs to invest more in Java, to get all the outstanding bugs fixed, and the fixes out quickly.  (Yes, people who write and use open source expect fixes more quickly than most vendors can deliver them.  Life is much quicker in the open source world)

But as we know, Sun doesn’t make much money from it – directly at least.  And even though Sun is quite clear in their strategy to use Java to drive sales of their hardware, this lack of revenue shows – shows up as a lack of support.

So what about a logo people using Java can put on their websites, which communicates “I bought some Sun hardware to support Sun’s investment in Java” to other people who use Java.  This may make them consider buying some Sun gear as well, and proliferation of the logo would remind Sun that Java really is what butters their bread.

Maybe that needs to be  “to support Sun’s investment in Java on Linux” (or even on Linux x86_64) – since its not Windows that these bugs occur on.

Or how about a way for Sun to earn credits towards a Sun hardware purchase: “If Sun fixes this bug, it will earn them a notional half a purchase”.  Fix this one as well, and I’ll buy something.  A great little site for someone to write.

Yes, I know you can vote for a bug (the printing bug has 45 votes since 26 November 2007 – that’s a lot of votes, comparatively speaking – but still there is no indication of when a fix will be available).

But Sun is wildly optimistic in only giving people three votes, no matter how many bugs are causing them grief.

I’ve bought 3 servers, 2 workstations, and a laptop in the last 6 months or so, and none of these are from Sun.  But I would change my purchasing policies for some tangible indication that result in quicker bug fixes.  So my third idea in this little brainstorm – what about allocating special higher priority bug votes when  people buy Sun gear?