Word Documents with XWPF

XWPF ("XML Word Processor Format") is the Apache POI component that reads and writes Word 2007 and later documents (.docx, and the macro-enabled .docm). It lives in the poi-ooxml jar, in the package org.apache.poi.xwpf.usermodel. A .docx file is a zip package (OOXML, ECMA-376) whose main content is the part /word/document.xml, written in the WordprocessingML vocabulary. XWPF wraps that XML in a Java object model.

Two facts shape everything on this page:

XWPF and HWPF (the .doc binary format) are separate APIs with no common interface. A program that must handle both needs two code paths, or the text-extraction classes that hide the difference when only the text matters.

A Word document is an ordered list of body elements (paragraphs, tables, and content controls) inside a body. A paragraph contains runs, and a run contains the text and the character formatting that applies to it. A run is the smallest unit that carries formatting: the paragraph holds block properties (alignment, spacing, indentation, style), the run holds character properties (bold, italic, font, size, colour).

The diagram shows how the main classes relate. Note that a table cell is itself a body (IBody): it contains paragraphs and nested tables, which is why the same XWPFParagraph class appears at the document level and inside a cell.

How the classes map to the package:

Creating an empty document is one constructor call. Opening an existing file has three forms:

Opening a File through OPCPackage.open(File) uses read-write access by default, and closing that package writes the changes back into the same file. For code that only reads a document, always pass PackageAccess.READ. Closing the XWPFDocument closes the underlying package, so a single try-with-resources on the document is enough.

Writing is document.write(OutputStream). It serialises the whole in-memory model into a new zip stream, so it can be called several times and the document stays usable afterwards.

document.createParagraph() appends a new empty paragraph at the end of the body and returns it. A paragraph with no run is still valid and shows as an empty line. The paragraph owns the block-level formatting:

Because Word measures lengths in twips in the file, so does XWPF: 20 twips are one point and 1,440 twips are one inch. There is no unit conversion in the paragraph methods, so a small helper makes code readable:

A paragraph also reports what it contains. paragraph.getText() concatenates the text of its runs (including hyperlink runs and content controls), paragraph.getRuns() returns the runs as a List<XWPFRun>, and paragraph.getIRuns() returns every run-level object as IRunElement, including some that getRuns does not model as XWPFRun. To insert a run at a position use insertNewRun(int); to delete one use removeRun(int). Both take the position in the list returned by getRuns(), not in the getIRuns() list; POI updates the getIRuns() list as a side effect.

A run is created with paragraph.createRun(). It starts empty and unformatted. The most important method is also the easiest to misuse:

The consequence: to replace the text of a run, call run.setText(newValue, 0). Calling run.setText(newValue) on a run that already has text produces a run holding the old and the new text one after the other. This is the most common mistake in code that edits existing documents, and it is why the template page spends so long on replacing text.

Control characters inside the string are not instructions. A "\n" inside setText does not start a new line in Word, and a "\t" is not a reliable tab. Use addBreak() and addTab() to insert real break and tab elements, one run per line when the text comes from a multi-line string:

Leading and trailing spaces are preserved: POI adds xml:space="preserve" to the text element when the string starts or ends with white space (see the first run in the figure). Characters that are not valid in XML 1.0 (most control characters below U+0020) cannot be stored; strip them from user-provided text before writing, otherwise the document is rejected by Word as corrupt or the write fails.

Source: XWPFRun Javadoc and POI XWPF Quick Guide.

All character formatting lives on the run. The setters create the property element in the run’s <w:rPr> as needed:

Getters mirror the setters but behave differently from what one expects. run.isBold() returns true only when the run itself says so. A run that is bold because its paragraph style or character style makes it bold reports false, and getFontFamily() returns null unless the run sets a font. XWPF does not resolve style inheritance for you; a program that wants the effective formatting has to walk run, character style, paragraph style and document defaults itself.

The following helper creates runs for the monthly report. It shows the habit that keeps formatting code readable: a small, named method per kind of text rather than repeated setters.

Source: XWPFRun Javadoc.

Direct formatting (setting bold and size on every run) is easy but does not scale: changing the look of all headings means editing all headings. Word’s answer is styles: named bundles of paragraph and character properties defined once in /word/styles.xml and applied by name. XWPF models them with XWPFStyles (the collection) and XWPFStyle (one definition).

The central rule: setStyle takes the style ID, not the name shown in Word. The ID is the w:styleId attribute and is usually the display name without spaces: the style shown as "Heading 1" has the ID Heading1, "List Paragraph" has ListParagraph. Styles can also have a different, user-defined ID entirely. XWPFStyles can look up both:

The second rule is the surprise for newcomers: a new XWPFDocument() has no style definitions at all. Calling paragraph.setStyle("Heading1") on such a document writes the reference but there is nothing for it to refer to, so Word shows the paragraph in its normal formatting. There are three ways to get real styles:

The example defines a heading style programmatically and uses it for the monthly report. The outline level makes the paragraphs appear in Word’s navigation pane and lets a table of contents (covered on the headers, footers and fields page) pick them up.

Source: XWPFStyles Javadoc, XWPFStyle Javadoc and the official SimpleDocument example, which adds a style the same way.

In addHeadingStyle the size is in half-points (36 is an 18 pt heading), because the CTStyle bean is the raw schema and the unit conversion that XWPFRun.setFontSize does for you is not available. This is the first appearance of the low-level layer; the section "Dropping down to the CT beans" below explains when it is worth it.

A few more points on styles:

Line breaks, page breaks and column breaks are all <w:br> elements inside a run, selected by BreakType:

There are two ways to start a page, and the difference matters for the report. run.addBreak(BreakType.PAGE) puts the break in the middle of a paragraph, so an empty paragraph that only holds the break leaves a trailing empty line at the top of the next page in some Word versions. paragraph.setPageBreak(true) sets the "page break before" property on the paragraph itself, which starts that paragraph on a fresh page without an extra empty line. For a chapter title prefer setPageBreak(true) on the title paragraph; reserve the break run for a break inside running text.

Source: BreakType Javadoc and XWPFParagraph Javadoc.

Page layout, section breaks, orientation and margins are not paragraph properties; they belong to the section and are covered in Word Headers, Footers, Sections & Fields.

XWPFParagraph.createHyperlinkRun(String uri) creates a hyperlink to an external address. POI registers the target as an external relationship of the main document part and returns an XWPFHyperlinkRun, which is a normal run for formatting purposes. Word does not style the link by itself: a link without formatting looks like plain text, so apply the usual blue and underline explicitly or through a character style such as "Hyperlink".

Reading the target goes through the document, because the URI is stored in the relationships:

An internal link to a bookmark has no relationship: it carries an anchor name, returned by getAnchor(). Creating bookmarks and internal links needs the CT beans (CTBookmark, CTHyperlink); XWPF has no higher-level API for them. Never build hyperlink targets from unvalidated input that may contain a javascript: or a file: scheme; allow https (and mailto) explicitly.

Source: XWPFHyperlinkRun Javadoc and XWPFParagraph Javadoc.

A document can interleave paragraphs and tables, and any program that processes a form (the Bookshelf book-request-form.docx) needs the original order. document.getParagraphs() and document.getTables() return two separate lists and lose the relative position. The ordered list is getBodyElements():

The next example reads book-request-form.docx and prints an outline of its structure. It opens the file read-only (PackageAccess.READ) so that closing it cannot modify the file, and it uses a switch on the BodyElementType enum.

Source: XWPFDocument Javadoc, IBodyElement Javadoc and OPCPackage Javadoc.

For a document such as the request form the output looks like this (the style ID is null for a paragraph without an explicit style, which Word treats as "Normal"):

Notice runs=3 for "Requested by: Ana García": a text that reads as one line was stored as three runs. That is normal, and it is why searching or replacing text in a paragraph run by run fails for anything that spans a boundary. The reading code here only prints, so it is unaffected, but the placeholder replacement on the templates page is built around this fact, and the import of structured data from Word forms builds on the same loop.

Several details about reading:

The core, extended and custom properties are available through document.getProperties(), which returns a POIXMLProperties. They are the data Word shows under File > Info and that the operating system uses for search.

Do not put personal data or internal paths into these properties unless that is intended: the creator field is the first thing that leaks when documents are published. Documents created from a template inherit the template’s properties, including its author and company, so overwrite them explicitly.

Source: POIXMLProperties Javadoc.

Opening an existing .docx, changing it, and writing the result under another name is the same model:

Source: XWPFDocument Javadoc.

Removing and reordering elements has two traps. document.removeBodyElement(int) takes an index in the body element list (the combined list), not in the paragraph list, so mixing the two index spaces removes the wrong thing. And document.setParagraph(XWPFParagraph, int) replaces the XML of a paragraph at an index of the paragraph list. Since a paragraph object keeps a reference to its XML node, a removed paragraph must not be used afterwards.

Inserting in the middle of a document uses a cursor: document.insertNewParagraph(XmlCursor) and insertNewTbl(XmlCursor) create an element at the cursor position of a paragraph’s XML (paragraph.getCTP().newCursor()). This is the pattern for "insert a paragraph at the marker paragraph" shown in Word Templates & Placeholder Replacement, and the XmlCursor should be released (close() or dispose(), depending on the XMLBeans version) after use.

Every XWPF object exposes its XML bean: paragraph.getCTP() returns a CTP, run.getCTR() returns a CTR, table.getCTTbl() a CTTbl, document.getDocument() a CTDocument1. These classes live in the package org.openxmlformats.schemas.wordprocessingml.x2006.main, are generated by XMLBeans from the ECMA-376 schema, and expose the complete file format. Use them when XWPF has no method for what you need:

Working at this level has three costs you should plan for.

The generated beans are tied to the POI and XMLBeans versions in use, so code that relies on CT* details should be covered by a test that opens the produced file again (see the testing section) whenever POI is upgraded.

XWPF builds the complete document in memory as XML beans, with no streaming writer comparable to SXSSF for spreadsheets. As a rough rule the memory used is a multiple of the file size (typically several times for text, much more with large embedded images, which stay in memory as byte arrays until write). Practical consequences:

A generator is correct when the result opens in Word, not when write returned. Two cheap tests catch most regressions: write the file to a temporary location and read it back with XWPF, asserting the text and the style IDs of the paragraphs, and open it with another independent reader (LibreOffice in headless mode, or a different library) in an integration test. AssertJ and JUnit are enough:

Source: JUnit User Guide and AssertJ documentation.