PDFBox 3.0 Migration Guide

Work in progress! This is guide will be improved over time. If you believe there is a missing topic, open an issue or help us with a contribution to improve the guide.

This guide describes the updates in Apache PDFBox 3.0 release. Use the information provided to upgrade your PDFBox 2.x applications to PDFBox 3.0. It provides information about the new, deprecated and unsupported features in this release.

Java Versions

PDFBox 3.0 requires at least Java 8. Testing has been done up to Java 11.

Dependency Updates

All libraries on which PDFBox depends are updated to their latest stable versions:

• Bouncy Castle 1.68
• Apache Commons Logging 1.2

For test support the libraries are updated to

• JUnit 5.7
• JAI Image Core 1.4.0
• JAI JPEG2000 1.4.0
• JBIG ImageIO Plugin 3.0.3
• Apache Commons IO 2.8

General Changes for PDFBox 3.0

This section explains the fundamental differences between PDFBox 3.0 and 2.x releases.

Deprecated APIs and Components

All deprecated APIs and components from PDFBox 2.x have been removed in PDFBox 3.0. Deprecated APIs in PDPageContentStream have been kept but you are encouraged to replace them with the non deprecated calls as they are treated to be of internal use only.

Use Loader to get a PDF document

For loading a PDF PDDocument.load has been replaced with the Loader methods. The same is true for loading a FDF document.

When saving a PDF this will now be done in compressed mode per default. To override that use PDDocument.save with CompressParameters.NO_COMPRESSION.

PDFBox now loads a PDF Document incrementally reducing the initial memory footprint. This will also reduce the memory needed to consume a PDF if only certain parts of the PDF are accessed. Note that, due to the nature of PDF, uses such as iterating over all pages, accessing annotations, signing a PDF etc. might still load all parts of the PDF overtime leading to a similar memory consumption as with PDFBox 2.0.

The input file must not be used as output for saving operations. It will corrupt the file and throw an exception as parts of the file are read the first time when saving it.

Changes in Common Functions

Interactive Forms

When accessing AcroForms using PDDocumentCatalog.getAcroForm() a number of fix ups are applied aligning PDFBox with most of the default behaviour of Adobe Reader. If you'd like to bypass this use PDDocumentCatalog.getAcroForm(null).

The fix ups include

• setting default font resources if they are not already part of the AcroForm
• create form fields from orphaned widget annotations under certain conditions
• create the normal appearance stream under certain conditions

You can lookup the details in the org.apache.pdfbox.pdmodel.fixup package of the source distribution and also create your own fix up(s).

Changes in PDFBox App

The command line interface for the PDFBox App has been rewritten. As a result

• the individual commands have been changed
• passing input and output files have been changed from using parameters to using options/flags to reduce the ambiguity
• all commands now return an exit code
• all commands now support passing -h or --help to display usage information
• all commands now support passing -V or --version to display the version information