Office Files (Word and Excel with Apache POI)
|
This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production. The reference material consulted while preparing these pages is listed in the section bibliography. |
Business backends constantly exchange spreadsheets and Word documents with their users: a catalogue exported to Excel, a nightly loans report, a letter generated from a template, a product list uploaded by an operator. This section is a practical, example-driven guide to doing that on a Java server with Apache POI. Versions and dates are re-verified when each page is written and stated as of the date checked.
Running scenario: Bookshelf
Every page uses the same example, the back office of the Bookshelf store used by other sections, so readers can compare approaches. The files involved are:
-
books-inventory.xlsx: the catalogue export, with a styled header, number and date formats, totals formulas, an auto-filter, a frozen header row, a data-validation column and a chart. -
loans-report.xlsx: a large streaming export of every loan. -
loan-letter.docxandmonthly-report.docx: Word documents with headings, a table, an image, a header and footer and page numbers, generated from scratch and from a template. -
books-import.xlsx: a catalogue upload with header mapping, per-row validation and an annotated error workbook returned to the user. -
book-request-form.docx: a Word form from which tables and content controls are extracted.
No example uses real secrets, passwords or personal data; encryption examples read the password from configuration.
Export path and import path
The section is organised around two directions of data flow.
-
Export path. The server builds a workbook or a document from its own data and sends it to the user, or stores it: styles, formulas, layout, streaming large result sets and download endpoints.
-
Import path. The user uploads a file that the server must treat as untrusted input: type detection, reading cells and runs, event-based reading of large files, validation, error reporting and security limits.
Word and Excel are the focus. PowerPoint (HSLF and XSLF), Outlook (HSMF), Visio (HDGF and XDGF) and Publisher (HPBF) are POI components too; they are described only in one table on the introduction page.
Version baseline
Values checked on 2026-10-09 against Maven Central and the Apache POI website.
| Component | Version used in this section |
|---|---|
Apache POI |
5.5.1 (released 30 November 2025). Differences in the 6.0 line, which has not been released yet, are noted on each page. |
Apache XMLBeans |
5.4.1 |
spring-batch-excel |
0.3.0 (community extension, readers only) |
Spring Boot |
4.1.x, on Spring Framework 7 |
Jakarta EE |
11 (Servlet 6.1, RESTful Web Services 4.0, Validation 3.1) |
Java |
21 or later (POI 5.5.x itself needs Java 8; POI 6.0 is announced to need JDK 17) |
Choose your page
Pages
The outline covers foundations (component map, setup and file formats), Excel, Word, cross-cutting topics (text extraction, metadata, encryption and security) and server workflows (downloads, uploads, validation, batch jobs, testing and migration), and ends with a downloadable cheat sheet. Pages are listed in reading order.
Foundations
-
Introduction & Architecture: What Apache POI is and how it is organised.
-
Setup & Dependencies: Adding Apache POI 5.5.1 to a Java 21 project.
-
File Formats: OOXML & OLE2: The two container formats behind Excel and Word files and how Apache POI maps to them.
Excel
-
Spreadsheet Usermodel Basics: The Apache POI spreadsheet usermodel for Excel.
-
Cell Styles, Fonts & Formats: How Apache POI styles cells.
-
Dates, Numbers & DataFormatter: Serial dates, DateUtil, DataFormatter and numbers stored as text.
-
Formulas & Evaluation: How Apache POI writes, reads and calculates Excel formulas.
-
Sheet Layout & Printing: How to control the layout of an Excel sheet with Apache POI.
-
Data Validation & Conditional Formatting: Data validation and conditional formatting in Apache POI spreadsheets.
-
Tables, Named Ranges & Pivot Tables: Excel tables, named ranges and pivot tables.
-
Images, Charts, Comments & Hyperlinks: Adding pictures, charts, cell comments, hyperlinks and embedded objects to Excel workbooks with Apache POI.
-
Templates & Modifying Workbooks: How to start from a designed Excel template with Apache POI instead of building every cell in code.
-
Streaming Writes with SXSSF: How to export hundreds of thousands of rows to .xlsx with Apache POI SXSSF.
-
Streaming Reads: Event & SAX APIs: Reading very large Excel files with Apache POI without loading them into memory.
-
Legacy .xls with HSSF: When the legacy Excel 97-2003 format is still needed and how to work with it in Apache POI.
Word
-
Word Documents with XWPF: Create, read and format Word .docx files with Apache POI XWPF.
-
Word Tables, Lists & Images: Tables, numbered and bulleted lists and pictures in Word documents with Apache POI XWPF.
-
Word Headers, Footers, Sections & Fields: Headers, footers, page numbers, sections, fields and table of contents.
-
Word Templates & Placeholder Replacement: How to fill a Word template with Apache POI when XWPF has no template or mail-merge API.
-
Word Charts & Embedded Objects: Charts and embedded objects in Word .docx files with Apache POI.
-
Legacy .doc with HWPF: What Apache POI can and cannot do with the legacy Word 97-2003 format.
Cross-cutting topics
-
Text Extraction & Apache Tika: Pull plain text and metadata out of Word and Excel files with Apache POI.
-
Document Properties & Metadata: Read, write and stamp document metadata with Apache POI.
-
Encryption, Signing & Protection: Password-protect, read and sign Office files with Apache POI.
-
Security & Untrusted Files: How to accept Word and Excel files from users with Apache POI without exposing the server.
Server import and export workflows
-
Exporting Reports from a Server: How to turn a database query into an Excel or Word download on a Java server with Apache POI.
-
Importing Data from Excel: Import an uploaded Excel workbook into a Java server with Apache POI.
-
Importing Data from Word: How to read structured data from uploaded Word files with Apache POI.
-
Batch Import & Export with Spring Batch: Importing and exporting Excel files in Spring Batch jobs with Apache POI.
-
Performance, Memory & Threading: How to keep Apache POI fast and its memory flat on a server.
-
Testing Office Documents: How to test code that writes and reads Word and Excel files with Apache POI.
-
What’s Changed & Migration: What changed from 3.x to 5.5, what to expect from 6.0, and outdated idioms.
-
Cheat Sheet (PDF): A downloadable one-page printable PDF that summarises the Office Files section.
Bibliography
The pages of this section are written against the official documentation listed here, verified on 2026-10-09 against the
versions stated in the version baseline above. Each page lists the subset it used under its own == References.
Apache POI
-
Apache POI home, news and security advisories, download, changes and versioning policy.
-
Spreadsheet (HSSF, XSSF and SXSSF): index, quick guide, how-to, converting, formula, formula evaluation, evaluation developer guide, user-defined functions, examples, limitations and ExcelAnt.
-
Word (XWPF and HWPF): index, XWPF quick guide, HWPF quick guide and document overview.
-
Configuration and logging.
-
FAQ, related projects and case studies.
Server integration
-
Spring MVC: ResponseEntity, asynchronous requests and multipart forms.
-
Spring Javadoc: StreamingResponseBody, ContentDisposition and MultipartFile.
-
Jakarta EE: Servlet 6.1, RESTful Web Services 4.0 and Validation 3.1.
Standards and limits
-
ISO/IEC 29500-1 (the site blocks automated checks; open it in a browser).