Upgrade PDFBox 2.0.36 -> 3.0.7 (#345)

Author: kwart

design-doc/3.0.0-openpdf3-vs-pdfbox3.md

@@ -0,0 +1,196 @@
+# Upgrade PDFBox 2.0.27 → 3.0.x
+
+## Context
+
+The project currently pins `pdfbox.version=2.0.27` in `pom.xml`. Signing itself
+is done by OpenPDF (fork of iText 2.1), not PDFBox — so the PDFBox dependency
+has a very narrow footprint:
+
+- **Main code (runtime):** one site in `jsignpdf/src/main/java/net/sf/jsignpdf/preview/Pdf2Image.java`
+  — `getImageUsingPdfBox()` uses `PDDocument.load(File, String)` +
+  `PDFRenderer.renderImageWithDPI(...)`. PDFBox is one of three rendering
+  strategies (`jpedal,pdfbox,pdfrenderer`) declared in `Constants.PDF2IMAGE_LIBRARIES_DEFAULT`
+  and `distribution/conf/conf.properties`.
+- **Test code only:**
+  - `jsignpdf/src/test/java/net/sf/jsignpdf/signing/SigningTestBase.java` —
+    builds a minimal unsigned PDF (`PDDocument`, `PDPage`, `PDPageContentStream`,
+    `PDType1Font.HELVETICA`).
+  - `jsignpdf/src/test/java/net/sf/jsignpdf/PdfExtraInfoTest.java` — builds
+    unprotected / owner-only / both-password PDFs (`StandardProtectionPolicy`,
+    `AccessPermission`, `PDType1Font.HELVETICA`).
+  - `jsignpdf/src/test/java/net/sf/jsignpdf/signing/validation/PdfSignatureValidator.java`
+    — validates signed output; uses `PDDocument.load(byte[])`/`load(File)`,
+    `getSignatureDictionaries()`, `PDAcroForm`, `PDSignatureField`,
+    `PDAnnotationWidget`, `PDFStreamParser`, COS traversal, `PDFont`.
+
+Nothing in the signing pipeline touches PDFBox. Migration risk is therefore
+scoped to **PDF page preview rendering** and **test fixtures / test
+validator**. This is a favorable shape for an upgrade.
+
+Upstream state (Apr 2026): PDFBox **3.0.7** is the current feature release;
+PDFBox **2.0.36** is still receiving maintenance patches. Both branches are
+active, so the upgrade is not time-critical — but 2.x will eventually be EOL.
+
+## Pros
+
+- **Active main branch.** New fixes (signature field handling, rendering
+  correctness, encryption parsers) land on 3.x first; 2.x gets a shrinking
+  subset of backports.
+- **Lower memory footprint for previews.** 3.0 parses PDFs on demand
+  (incremental parsing), so opening a large PDF just to render page 1 no
+  longer loads the entire object tree. This directly benefits the
+  JavaFX preview path.
+- **Cleaner IO boundary.** The new `pdfbox-io` module (`RandomAccessRead`,
+  `RandomAccessReadBufferedFile`, `RandomAccessReadMemoryMappedFile`) and
+  `StreamCacheCreateFunction` replace the old `MemoryUsageSetting` knob —
+  easier to configure correctly for a desktop app that opens one PDF at a
+  time.
+- **Dependency freshness.** 3.x tracks modern Bouncy Castle (1.75+ transitively,
+  `jdk18on` artifacts — the same flavour JSignPdf already uses; see
+  `pom.xml:51-59`). No more `bcprov-jdk15on` pulled in transitively alongside
+  our `bcprov-jdk18on`, which removes a long-standing enforcer-convergence
+  irritant.
+- **Deprecations gone.** 2.x carried ~8 years of deprecations. The 3.x API
+  surface is smaller and more predictable for future maintainers.
+- **Still Java 8 baseline.** No Java-floor impact — the project already
+  targets Java 11.
+
+## Cons / risks
+
+- **Breaking API changes touch every call site.** All three `PDDocument.load(...)`
+  forms are removed and become `Loader.loadPDF(...)`. `PDType1Font.HELVETICA`
+  (and the other 13 standard fonts) are no longer static singletons —
+  callers construct `new PDType1Font(Standard14Fonts.FontName.HELVETICA)`
+  instead. Impact here is small (6 files, ~8 lines) but non-zero.
+- **Compression default flip.** 3.0 saves compressed by default. Our test
+  fixtures save small PDFs and then re-sign them; this should be harmless
+  but means byte-for-byte output diffs vs. 2.x if anyone has baselined them.
+- **2.x is not dead yet.** 2.0.36 shipped in March 2026. Staying on 2.x
+  a bit longer is a legitimate option; the upgrade is "should", not "must".
+- **Distribution side-effects:**
+  - `distribution/linux/flatpak/maven-dependencies.json` must be regenerated
+    (see recent `chore(flatpak): regenerate maven-dependencies.json` commits).
+    The new `pdfbox-io` artifact and any transitive shifts must be captured.
+  - Shaded fat-jar contents change. Fat-jar size is similar (pdfbox 3 is
+    comparable to 2.x + fontbox), but the shade plugin's
+    `ServicesResourceTransformer` and manifest filters need re-verification.
+- **Preview rendering parity.** `PDFRenderer.renderImageWithDPI(pageIndex, dpi)`
+  is preserved, but subtle differences in font substitution, transparency,
+  or edge cases (e.g. forms XObjects inside signature appearances) are
+  possible. Needs a visual smoke test against the test corpus.
+- **Encrypted PDF handling.** `Loader.loadPDF(RandomAccessRead, String password)`
+  replaces `PDDocument.load(File, String)`. Behaviour for owner-only,
+  user-only, both-password, and wrong-password cases must match what
+  `PdfExtraInfoTest` asserts today — specifically that
+  `BadPasswordException` is still thrown from OpenPDF (which is what the
+  test expects), not from PDFBox, since PDFBox is only used in tests for
+  fixture creation. That should be unchanged, but worth re-running.
+- **Dependency convergence.** `maven-enforcer-plugin`'s convergence rule
+  will flag any transitive BC/logging version drift introduced by pdfbox 3.
+  Already-present overrides (`bcprov-jdk18on` 1.84, `commons-io` 2.21,
+  etc.) should cover this, but a clean `mvn -Pelease verify` is required.
+
+## Recommended actions (in order)
+
+1. **Bump the version property.**
+   `pom.xml:27` → `<pdfbox.version>3.0.7</pdfbox.version>` (latest stable at
+   time of writing; pin to a specific patch version, not a range).
+
+2. **Add `pdfbox-io` to `dependencyManagement`.**
+   In the root `pom.xml`, next to the existing `pdfbox` entry:
+   ```xml
+   <dependency>
+       <groupId>org.apache.pdfbox</groupId>
+       <artifactId>pdfbox-io</artifactId>
+       <version>${pdfbox.version}</version>
+   </dependency>
+   ```
+   Add it as a compile dependency in `jsignpdf/pom.xml` if it isn't pulled
+   transitively (it should be, but declaring it keeps the convergence rule
+   happy).
+
+3. **Rewrite the single main-code call site** in
+   `jsignpdf/src/main/java/net/sf/jsignpdf/preview/Pdf2Image.java`:
+   ```java
+   // was: tmpDoc = PDDocument.load(tmpFile, options.getPdfOwnerPwdStrX());
+   tmpDoc = Loader.loadPDF(tmpFile, options.getPdfOwnerPwdStrX());
+   ```
+   Keep the file-based overload so we don't lose the memory-mapped read
+   path. No changes needed to `PDFRenderer.renderImageWithDPI`.
+
+4. **Update test fixtures** in `SigningTestBase.java` and
+   `PdfExtraInfoTest.java`:
+   ```java
+   // was: cs.setFont(PDType1Font.HELVETICA, 12);
+   cs.setFont(new PDType1Font(Standard14Fonts.FontName.HELVETICA), 12);
+   ```
+   (Hoist the font instance to a `@BeforeClass` field if it starts to
+   matter — the standard 14 fonts are cheap to construct but no longer
+   free.)
+
+5. **Update the validator** in
+   `jsignpdf/src/test/java/net/sf/jsignpdf/signing/validation/PdfSignatureValidator.java`:
+   Replace both `PDDocument.load(fileBytes)` and `PDDocument.load(signedPdf)`
+   with `Loader.loadPDF(...)`. Everything downstream (`getSignatureDictionaries`,
+   `PDAcroForm`, `PDSignatureField`, `PDAnnotationWidget`, `PDFStreamParser`,
+   `PDFont.readCode`, `PDSimpleFont`) is carried over unchanged in 3.x.
+
+6. **Regenerate the flatpak manifest.**
+   Run the existing regeneration script (or `mvn` with the offline-prep
+   profile) that produces
+   `distribution/linux/flatpak/maven-dependencies.json`. Replace all
+   `pdfbox/2.0.27/*` and `fontbox/2.0.27/*` entries with `3.0.7` equivalents;
+   add `pdfbox-io/3.0.7/*` entries. Verify SHA-256 sums against Maven
+   Central.
+
+7. **Re-verify the shaded jar.**
+   `mvn -pl jsignpdf package` and inspect the resulting
+   `jsignpdf-*-jar-with-dependencies.jar` for:
+   - no split-package / service-loader regression (the `ServicesResourceTransformer`
+     should fold `org.apache.pdfbox.io.spi`-style service descriptors cleanly),
+   - expected size delta (< ~10% change either way),
+   - `META-INF/MANIFEST.MF` still has `Main-Class: net.sf.jsignpdf.Signer`.
+
+8. **Run the full test suite.**
+   `mvn verify`. Pay attention to `PdfExtraInfoTest` (password handling)
+   and any `signing/` tests that sign fixture PDFs generated by
+   `SigningTestBase`.
+
+9. **Manual smoke tests** (can't be covered by CI):
+   - Open a 200+ page PDF in the JavaFX UI; confirm preview still renders
+     (memory should be lower).
+   - Open a password-protected PDF, enter owner password, render preview.
+   - Open a PDF containing fonts that lean on font-substitution; visually
+     compare a page against the 2.x render.
+   - Sign a document and reopen the signed output — the JavaFX preview of
+     the signed page should match the preview of the unsigned page (i.e.
+     no rendering regression at the signature widget).
+
+10. **Decide on a follow-up (not part of this upgrade):** drop PDFBox from
+    the preview strategy list entirely. `Constants.PDF2IMAGE_LIBRARIES_DEFAULT`
+    already falls back through `jpedal` and `pdfrenderer`, so removing
+    `pdfbox` from the default would let us demote the runtime dependency to
+    `test`-scope and shrink the fat jar by ~8 MB. This is attractive but
+    orthogonal — track it separately once the 3.x bump is stable. (The test
+    validator still needs PDFBox at test-scope regardless.)
+
+## Scope explicitly NOT in this upgrade
+
+- Replacing OpenPDF's signing pipeline with PDFBox's `addSignature(...)` /
+  `saveIncrementalForExternalSigning(...)`. That would be a much larger
+  rewrite (CMS/PKCS#7 assembly, TSA integration, visible-signature layer
+  composition — all currently owned by OpenPDF). It is worth considering
+  on its own merits (OpenPDF is a fork of iText 2.1 from 2009, and PDFBox
+  is the more active signing implementation today), but is a separate
+  design doc.
+- Swapping the remaining renderers (`jpedal`, `pdfrenderer`) for PDFBox-only.
+  See action item 10.
+- Any change to the `pdf2image.libraries` default order or configuration
+  surface in `conf/conf.properties`.
+
+## Sources
+
+- [PDFBox 3.0 Migration Guide](https://pdfbox.apache.org/3.0/migration.html)
+- [PDFBox downloads / release status](https://pdfbox.apache.org/download.html)
+- [`Loader` javadoc (3.0.x)](https://javadoc.io/doc/org.apache.pdfbox/pdfbox/latest/)
+- [DeepWiki summary of the 3.0 migration](https://deepwiki.com/apache/pdfbox-docs/3.2-3.0-migration)