Repository navigation
Upgrading to 8
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
- Recompile against 8.0: it isn't binary compatible with 7.x, so don't drop the jars into a 7.x build.
- Removed deprecated API: if the compiler complains, the replacement is listed under API compatibility below.
- 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.
- Dependencies: TwelveMonkeys and JJ2000 are gone; drop them if you only added them for icepdf.
-
Log and title matching: the project is now written icepdf, so the startup log line reads
icepdf Core 8.0.0and the viewer window titles changed.
-
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)andStateManager.addChange(PObject, boolean): drop thetrue. Where you passedfalse(a change the library makes to repair a file, not a user edit), call the one-argument form insideStateManager.repairing(...). -
Redactor.burnRedactions(Document): useRedactor.redact(document, RedactionRequest.ofAnnotations()), or just save a document that carries redaction annotations. -
StateManager.isChange(),isNoChange()andhasChangedSinceLastSnapshot(): usehasUnsavedUserChanges()(the save prompt question) orhasWritableChanges(). -
SearchTerm.getTerms()and the token-list parameter of theSearchTermconstructors: the matcher has searched the whole term since this release's search rewrite.new SearchTerm(term, null, caseSensitive, wholeWord, ...)becomesnew SearchTerm(term, caseSensitive, wholeWord, ...).DocumentSearchControllerImpl.searchPhraseParseris gone. -
Pattern.getPaint(): a pattern is shared by every use, so its paint is built per use withgetPaint(GraphicsState), which is now the abstract method. -
ImageStream.setGraphicsTransformMatrix(write-only; where an image is drawn lives on itsImageReference) and the unusedSeparation.namedColorCache/cacheLockfields. - The
org.icepdf.core.views.page.text.preserveColumnssystem property: usereadingOrder(ysortfor the 7.4.x order). -
Library.getMappedFileByteBuffer(),setDocumentByteBuffer(ByteBuffer)andgetMappedFileByteBufferLock(): 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 throughDocument.writeToOutputStreamrather than reading the raw buffer.
Some low-level classes also changed. Code that subclasses
Annotation, implementsSignatureAppearanceCallback, readsFreeTextAnnotationfont sizes (nowfloat) or uses the parser,StringObjectorStateManager.Typeinternals should be recompiled and checked. The emptyPublicSecurityHandlerplaceholder class was removed, along with internal classes nothing in the examples used: the pre-7.0org.icepdf.core.util.Parser,BufferedMarkedInputStream,ByteDoubleArrayInputStream,RandomAccessFileInputStream,SeekableInputConstrainedWrapper,SoftLRUCacheandFloydSteinbergImageReference.GraphicsState.getClip()now returns aShapeinstead of anArea,TextSprite.getFontSize()returns afloat, and so doesAFM.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 addedcom.github.jai-imageio:jai-imageio-jpeg2000for icepdf can drop it; if both are on the class path, icepdf uses jpx-imageio. -
JavaFX viewer:
icepdf-viewer-fxneeds 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 toysortfor 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
Documentis 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 setorg.icepdf.core.document.mapFile=falseto 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=falseto always decode at full size. -
TwelveMonkeys ImageIO removed: core no longer brings
com.twelvemonkeys.imageio:imageio-tiffand its five supporting jars onto the class path, andmodule-infono 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=falseto go back to the image path.
- 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.
Project site · Javadoc · Releases · Discussions · Issues
Start
Use the library
Viewers
Configure and tune
Project