Apache POI para Java: guia completo com exemplos práticos

1. O que é Apache POI e para que serve?

Apache POI (Poor Obfuscation Implementation) é uma biblioteca Java de código aberto poderosa, projetada para criar, ler e modificar arquivos do Microsoft Office (Excel, Word, PowerPoint, Outlook). Ela permite que desenvolvedores manipulem documentos programaticamente sem precisar instalar o pacote Microsoft Office. A biblioteca oferece duas APIs principais: HSSF (Horrible Spreadsheet Format) para trabalhar com arquivos .xls (Excel 97-2003) e XSSF (XML Spreadsheet Format) para o formato moderno .xlsx (Excel 2007+). Para arquivos Word, os componentes equivalentes são: HWPF (para .doc) e XWPF (para .docx).

Por que usar isso? No desenvolvimento moderno, é comum precisar automatizar tarefas com documentos Office: gerar relatórios, importar dados de planilhas, criar modelos de contratos ou montar resumos analíticos complexos. O Apache POI resolve esses problemas, dando aos desenvolvedores Java controle total sobre a estrutura do documento: desde formatação de células e criação de gráficos no Excel até manipulação de tabelas, imagens e estilos no Word.

A biblioteca é mantida ativamente pela comunidade Apache Software Foundation, possui documentação extensa e é usada em grandes projetos corporativos. É compatível com Java 8 e versões superiores, tornando-se uma ferramenta versátil para a maioria das aplicações Java modernas, incluindo web services, aplicações desktop e sistemas de processamento de dados.

2. Instalação

O Apache POI é distribuído através do Maven Central Repository. Para adicioná-lo ao seu projeto, inclua as dependências no arquivo pom.xml (para Maven) ou build.gradle (para Gradle).

Maven

<!-- Dependência principal para trabalhar com Excel (.xls e .xlsx) -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.3.0</version>
</dependency>

<!-- Para trabalhar com documentos Word (.doc e .docx) -->
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-scratchpad</artifactId>
    <version>5.3.0</version>
</dependency>

Gradle

implementation 'org.apache.poi:poi-ooxml:5.3.0'
implementation 'org.apache.poi:poi-scratchpad:5.3.0'

Importante: A versão 5.3.0 é a atual no momento da escrita deste artigo. Recomenda-se verificar a versão mais recente no Maven Repository. Note também que poi-ooxml já inclui poi (módulo base) e poi-ooxml-lite (para trabalhar com formatos OOXML).

3. Início rápido: exemplo mínimo funcional

Vamos criar um arquivo Excel simples com uma linha de dados e salvá-lo no disco.

import org.apache.poi.ss.usermodel.*;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;

import java.io.FileOutputStream;
import java.io.IOException;

public class QuickStart {
    public static void main(String[] args) {
        // Cria uma nova pasta de trabalho (Workbook) para o formato .xlsx
        try (Workbook workbook = new XSSFWorkbook()) {
            // Cria uma planilha com o nome "Dados"
            Sheet sheet = workbook.createSheet("Dados");

            // Cria a primeira linha (índice 0)
            Row row = sheet.createRow(0);

            // Cria uma célula na coluna A (índice 0)
            Cell cell = row.createCell(0);
            cell.setCellValue("Olá, Apache POI!");

            // Cria uma célula na coluna B (índice 1) com valor numérico
            Cell cell2 = row.createCell(1);