Skip to content

Upgrading to 8

Patrick Corless edited this page Nov 3, 2026 · 2 revisions

What to check when moving from 7.x. Most applications that use Document, Page, rendering, signing and the Swing viewer's SwingController/SwingViewBuilder only need a recompile. 8.0 is a major version because some low-level classes changed and a few defaults changed behaviour.

On this page: Checklist · Details · Dependency changes

Checklist

  1. Recompile against 8.0: it isn't binary compatible with 7.x, so don't drop the jars into a 7.x build.
  2. Removed deprecated API: if the compiler complains, the replacement is listed under API compatibility below.
  3. Behaviour changes: text reading order, memory-mapped files, memory budgets and reduced image decode now default on. Each has a system property to go back to the 7.x behaviour.
  4. Dependencies: TwelveMonkeys and JJ2000 are gone; drop them if you only added them for icepdf.
  5. Log and title matching: the project is now written icepdf, so the startup log line reads icepdf Core 8.0.0 and the viewer window titles changed.

Details

  • Font cache: the first launch after upgrading rescans the system fonts once (a few seconds) to pick up TrueType/OpenType collections (.ttc/.otc), which are now used for font substitution, notably for CJK text. Later launches use the cache as before.

  • API compatibility (why 8.0): 8.0 is not binary compatible with 7.x: recompile against it rather than dropping the jars into a 7.x build. Most top-level code (Document, Page, rendering, signing, and the viewer's SwingController/SwingViewBuilder) compiles unchanged, but the major version is used to remove API that was deprecated or had become dead:

    • Page.addAnnotation(Annotation, boolean), Annotation.resetAppearanceStream(AffineTransform, boolean) and StateManager.addChange(PObject, boolean): drop the true. Where you passed false (a change the library makes to repair a file, not a user edit), call the one-argument form inside StateManager.repairing(...).
    • Redactor.burnRedactions(Document): use Redactor.redact(document, RedactionRequest.ofAnnotations()), or just save a document that carries redaction annotations.
    • StateManager.isChange(), isNoChange() and hasChangedSinceLastSnapshot(): use hasUnsavedUserChanges() (the save prompt question) or hasWritableChanges().
    • SearchTerm.getTerms() and the token-list parameter of the SearchTerm constructors: the matcher has searched the whole term since this release's search rewrite. new SearchTerm(term, null, caseSensitive, wholeWord, ...) becomes new SearchTerm(term, caseSensitive, wholeWord, ...). DocumentSearchControllerImpl.searchPhraseParser is gone.
    • Pattern.getPaint(): a pattern is shared by every use, so its paint is built per use with getPaint(GraphicsState), which is now the abstract method.
    • ImageStream.setGraphicsTransformMatrix (write-only; where an image is drawn lives on its ImageReference) and the unused Separation.namedColorCache / cacheLock fields.
    • The org.icepdf.core.views.page.text.preserveColumns system property: use readingOrder (ysort for the 7.4.x order).
    • Library.getMappedFileByteBuffer(), setDocumentByteBuffer(ByteBuffer) and getMappedFileByteBufferLock(): the document's bytes are now internal (Library.getDocumentSource(), in a package core does not export), so a later release can read documents lazily over HTTP without another break. Save through Document.writeToOutputStream rather than reading the raw buffer.

    Some low-level classes also changed. Code that subclasses Annotation, implements SignatureAppearanceCallback, reads FreeTextAnnotation font sizes (now float) or uses the parser, StringObject or StateManager.Type internals should be recompiled and checked. The empty PublicSecurityHandler placeholder class was removed, along with internal classes nothing in the examples used: the pre-7.0 org.icepdf.core.util.Parser, BufferedMarkedInputStream, ByteDoubleArrayInputStream, RandomAccessFileInputStream, SeekableInputConstrainedWrapper, SoftLRUCache and FloydSteinbergImageReference. GraphicsState.getClip() now returns a Shape instead of an Area, TextSprite.getFontSize() returns a float, and so does AFM.getAvgWidth(), which was always 0 before.

  • JPEG 2000: core now depends on com.github.pcorless:jpx-imageio, so JPXDecode images render without adding anything. Applications that added com.github.jai-imageio:jai-imageio-jpeg2000 for icepdf can drop it; if both are on the class path, icepdf uses jpx-imageio.

  • JavaFX viewer: icepdf-viewer-fx needs Java 17 and is built against JavaFX 22, the newest JavaFX that runs on Java 17. Core and the Swing viewer still run on Java 11. The JavaFX 22 line no longer receives updates, so applications on JDK 23 or later should declare JavaFX 25 LTS themselves; the viewer runs on it unchanged. The viewer-fx README's "Java and JavaFX versions" section has the details.

  • Text extraction: the default reading order is now column-aware (org.icepdf.core.views.page.text.readingOrder=xycut). Set it to ysort for the 7.4.x ordering.

  • Memory-mapped files: a document opened from a file of at least 64 MB (or a sixteenth of the max heap, whichever is smaller) is now memory-mapped rather than copied into the heap. While the Document is open, the file must not be overwritten in place; on Windows it can't be replaced at all until the document is disposed. The Swing and JavaFX viewers already save to a temporary file and move it over the original. Applications that write over the open file themselves should dispose the document first, or set org.icepdf.core.document.mapFile=false to restore the old heap copy.

  • Memory budgets: image decodes, the decoded-image cache and the system-font cache are now capped at fractions of the max heap (a quarter, an eighth and a sixteenth). They scale with -Xmx, and each can be set explicitly (see the system properties page).

  • Reduced image decode: images larger than 16 MB decoded (4 MB for JPEG 2000) that are drawn smaller than their full size are decoded at the drawn resolution with a box filter. Set org.icepdf.core.images.reducedDecode=false to always decode at full size.

  • TwelveMonkeys ImageIO removed: core no longer brings com.twelvemonkeys.imageio:imageio-tiff and its five supporting jars onto the class path, and module-info no longer requires them. icepdf never read TIFF files through ImageIO, so rendering is unaffected. If your application reads or writes TIFF with ImageIO and relied on icepdf to bring in the TwelveMonkeys plug-in, either add it yourself or use the TIFF plug-in built into the JDK (Java 9+). The JDK plug-in is what the TIFF capture example now uses.

  • Tiny stencil masks: stencil-mask images of up to 4096 samples are now drawn directly instead of through the image pipeline. Set org.icepdf.core.stencilMask.fill=false to go back to the image path.

Dependency changes

  • Apache FontBox 3.0.6 → 3.0.8
  • Bouncy Castle 1.83 → 1.86
  • TwelveMonkeys ImageIO 3.13.1 → removed (6 jars, about 620 KB); icepdf's own CCITT decoder replaces it
  • Apache Commons Logging 1.3.5 → 1.4.0
  • JPEG 2000: jai-imageio-jpeg2000 1.4.0 (JJ2000, viewer applications only) → jpx-imageio 0.1.0 (core dependency)
  • New: OpenJFX 22.0.2 (JavaFX viewer only; use 25 LTS on JDK 23+)
  • jbig2-imageio stays on 3.0.4: 3.0.5 fails some embedded JBIG2 streams

The full list of changes is in the 8.0.0 release notes.

Clone this wiki locally