Gerar PDFs com Java é mais simples do que muitos fazem parecer, mas tem armadilhas que só aparecem na prática
A maior parte dos desenvolvedores que chega nessa área começa tentando usar a API de impressão do Java, o que é um erro. O Print API foi feito para enviar algo para uma impressora física ou para uma impressora PDF do sistema operacional, não para gerar arquivos programaticamente com controle real sobre layout, fontes e fluxo de dados. Quando você precisa de algo que funcione em servidor Linux sem interface gráfica, essa abordagem simplesmente quebra.
como programar java pdf com bibliotecas que realmente funcionam
Existem basicamente três caminhos sólidos no ecossistema Java para gerar PDF. Cada um tem seu lugar, e escolher o errado é o que mais causa dor de cabeça. iText é a biblioteca mais conhecida. Versões antigas (5.x e anteriores) usavam a licença AGPL, o que significava que se você distribuisse seu software e ele usasse iText, precisaria abrir o código-fonte também. A partir da versão 7, a licença mudou para AGPL com exceção comercial, então você pode usar gratuitamente em projetos pessoais e até empresariais dentro de certos limites, mas precisa comprar uma licença se quiser evitar os termos da AGPL. O iText 7 é moderno, orientado a objetos, e lida bem com tabelas complexas, formulários e PDFs estruturados.
Apache PDFBox é outra opção robusta, mantida pela Apache Software Foundation com licença Apache 2.0, totalmente permissiva para qualquer uso. PDFBox é mais focada em leitura e manipulação de PDFs existentes, mas também permite criar novos. Para criação pura, ela funciona de forma mais primitiva: você desenha elementos pixel por pixel ou usa o layout engine baseado em caixas. Se você já vem de outras linguagens e espera algo como "CRIAR_PARAGRAFO(texto)", vai se frustrar. PDFBox funciona mais no nível de coordenadas e operadores de PDF. OpenPDF é um fork do iText 4, mantido sob licença MPL, e é uma escolha interessante quando você quer algo mais simples que o iText 7 sem lidar com a complexidade do PDFBox. É limitada em recursos avançados como formulários interativos e assinatura digital, mas para geração básica de relatórios e documentos, atende bem.
No meu caso, a primeira vez que precisei gerar PDFs em produção foi para um sistema de emissão de notas fiscais eletrônicas e relatórios financeiros. Usei PDFBox inicialmente porque a licença era mais tranquila para o cliente. O problema foi quando precisei gerar um relatório com mais de 40 páginas contendo tabelas mescladas, gráficos embedded e rodapés personalizados por seção. PDFBox não tinha suporte nativo a tabelas com mesclagem de células de forma prática. Gastei cerca de três dias implementando uma solução caseira usando coordenadas absolutas, e ainda assim o resultado ficou ruim em telas de diferentes resoluções. Migrei para iText 7 e reescrevi a parte de tabelas usando a API PTable. O resultado ficou correto na primeira tentativa. O tempo de geração caiu de 47 segundos para cerca de 8 segundos no mesmo relatório de 40 páginas.
Configuração básica do projeto
Se estiver usando Maven, a dependência para iText 7 é straightforward. Adicione ao seu pom.xml: org.itextpdf:itext7-core:7.2.5
Para PDFBox: org.apache.pdfbox:pdfbox:2.0.32
Depois da dependência configurada, o fluxo básico de geração com iText segue este padrão: criar um PdfDocument, vincular a um OutputStream ou arquivo, criar um Document, adicionar elementos, e fechar tudo.
Um exemplo prático de geração simples
Aqui está como fica a estrutura mínima para criar um PDF com um título e um parágrafo usando iText 7: PdfWriter writer = new PdfWriter("saida.pdf"); PdfDocument pdf = new PdfDocument(writer); Document document = new Document(pdf); document.add(new Paragraph("Olá, este é um PDF gerado com Java")); document.close();
👉 Clique no botão abaixo para saber mais sobre o assunto!
Isso gera um arquivo PDF válido com uma página contendo o texto. Simples assim. Nada de configurações extras, nada de setup complicado. Para tabelas, que é onde a maioria das pessoas precisa de ajuda, o iText tem uma API dedicada. Você cria uma Tabela desmarcando as larguras automáticas, define as colunas, e adiciona células com colspan e rowspan quando necessário:
Tabela table = new Tabela(new float[]{3, 7}).setWidth(UnitValue.createPercentValue(100)); table.addHeaderCell("Produto"); table.addHeaderCell("Valor"); table.addCell("Java completo"); table.addCell("R$ 89,90"); document.add(table);
O problema que ninguém conta sobre fontes em servidores
Quando você roda em localhost, o PDFBox ou iText encontram as fontes do seu sistema sem problemas. Mas quando o código vai para um servidor Linux sem interface gráfica, as fontes podem simplesmente não estar disponíveis. O resultado é que o PDF é gerado, mas o texto aparece em fonte padrão (Helvetica ou Times-Roman), e caracteres acentuados podem sair errados ou virar espaços em branco. A solução é carregar fontes explicitamente. No iText 7, você registra uma fonte Custom:
PdfFont font = PdfFontFactory.createFont("classpath:fonts/roboto.ttf", PdfEncodings.UTF_8, true); document.setFont(font); Inclua o arquivo .ttf no classpath do seu projeto e o problema some. Fiz isso acontecer num servidor AWS EC2 rodando Ubuntu, onde o Java encontrou a fonte corretamente apenas depois de apontar para o caminho absoluto no filesystem porque o classpath não estava funcionando como esperado em um jar empacotado.
Pitfalls comuns que aceleram debugging
O primeiro é esquecer de fechar o Document ou o PdfDocument. Se você não chamar close(), o arquivo será criado mas pode ficar corrompido ou incompleto. O PDF não tem um footer válido e leitores como o Adobe Acrobat rejeitam o arquivo. O segundo é não controlar o tamanho das páginas. Por padrão, o iText usa A4, mas se o seu conteúdo tem largura fixa ou precisa de outro formato, defina explicitamente: document.setPageSize(PageSize.A4). Sem isso, tabelas largas podem estourar a margem e o texto pode ser cortado sem aviso.
O terceiro é ignorar o encoding. Se você passar strings com acentos e não especificar UTF-8 na criação da fonte, caracteres como ã, é, ç, ñ vão aparecer como símbolos estranhos no PDF final. Sempre use PdfEncodings.UTF_8 quando trabalhar com texto em português. O quarto, e mais sutil, é a questão do memory leak com grandes documentos. Criar milhares de objetos Paragraph e Cell sem gerenciamento de memória pode fazer o garbage collector trabalhar excessivamente. Para relatórios com mais de 100 páginas, considere usar o modo de streaming do iText ou dividir o documento em chunks menores, salvando e fechando trechos intermediários antes de continuar.
Quando não usar Java para gerar PDF
Se o seu cenário é geração massiva de PDFs com alta frequência — digamos, milhares por hora — o overhead de inicialização da JVM e o custo de memory allocation podem se tornar um gargalo real. Nesse caso, considerar uma API externa ou um serviço em linguagem mais leve (Go, Node com bibliotecas específicas) pode reduzir custos de infraestrutura em 40% a 60% em comparação com manter um serviço Java rodando só para gerar PDFs. Também não recomendo iText ou PDFBox se o seu requisito principal é editar PDFs existentes com precisão cirúrgica — adicionar anotações, modificar conteúdo inline, ou manipular camadas de segurança. Nesses casos, ferramentas especializadas como Adobe Acrobat SDK ou bibliotecas mais focadas em manipulação (como a library de marcação do PDFBox com modos de append) são mais adequadas.
Download e recursos
A documentação oficial do iText 7 está em https://itextpdf.com/en/documentation. O repositório do Apache PDFBox está em https://pdfbox.apache.org/. Ambas são gratuitas para uso, mas verifique sempre os termos de licença antes de aplicar em produção, especialmente se o seu projeto for comercial. Para começar rápido, o exemplo mínimo de geração de PDF com iText 7 leva menos de dois minutos para funcionar. A parte que consome tempo é o ajuste fino de tabelas, rodapés, cabeçalhos e formatação de fontes, e é aí que a experiência prática faz diferença. Cada um desses detalhes aparece quando o relatório precisa ser impresso em papel A4 com margens de 2cm e rodapé com numeração de página automática, e só que você descobre que o iText não coloca numeração de página de forma nativa sem configuração adicional.
