iText 7.1 - Migration guide for Java

Tags: Javamigration guideiText 7.1Release

Migration Guide for Java

Introduction

This is a short migration guide to help you or your developers switch from 7.0.x to 7.1.0. This guide will broadly cover the breaks in the API. Please consult the breaking changes on the iText website for the full and detailed list of changes. All listing below are non-exhaustive and mainly cover the most important changes that you need to do or you need to take into account when moving to 7.1.0.

1. Updating the version using Maven / Gradle

Update the following dependencies in your project's pom.xml or build.gradle file:

  • Change the version of the iText-core modules from 7.0.x to 7.1.0.

  • Change the version of the iText add-on modules from 1.x.y to 2.0.0.

2.License keys and Licensed users

Together with 7.1.0, we are releasing v3.0.0 of our LicenseKey library. If you wish to use 7.1 under a commercial license, you'll need to use this version of the LicenseKey library. If you have been using v2.0, the only thing you'll have to change in your code is the dependency version of this library. You might also need to update your license-files as well.

3. Accessibility changes

  • In order to create a PDF/UA document, you need to explicitly call #addUAXmpMetadata for WriterProperties, otherwise PDF document won't be marked (and therefore recognized) as such.

  • The setRole() method on several layout elements has been moved to getAccessibilityProperties().setRole().

  • setRole() now takes a java string as argument. Standard role constants have found a home in com.itextpdf.kernel.pdf.tagging.StandardRoles

4. Moved packages, classes, fields and method

The following things have been moved from their old location to a new location.

Core

  • Everything in the package com.itextpdf.io.color has been moved to com.itextpdf.io.colors. Constants have moved to com.itextpdf.io.colors.ColorConstants

  • Everything in the package com.itextpdf.layout.border has been moved to com.itextpdf.layout.borders.

  • Constants from com.itextpdf.io.font.FontConstants has moved to com.itextpdf.io.font.constants package. Standard PDF font names moved to com.itextpdf.io.font.constants.StandardFonts.

  • com.itextpdf.io.font.FontConstants#notdef has moved to com.itextpdf.io.font.FontEncoding#NOTDEF.

  • All constants in com.itextpdf.io.font.FontNames have moved to FontMacStyleFlags, FontStretches and FontWeights.

  • The fields initialDocumentId and modifiedDocumentId and their accessors in com.itextpdf.kernel.pdf.PdfDocument have been moved to WriterProperties.

  • Several methods in the abstract class com.itextpdf.kernel.pdf.annot.PdfAnnotation have been moved to the specific annotation where they make sense (e.g. it's no longer possible to attempt to set borders on a pop-up annotation).

  • Several methods in the abstract class com.itextpdf.kernel.pdf.annot.PdfMarkupAnnotation have been moved to the specific annotation where they make sense (e.g. it's no longer possible to attempt to set borders on a highlight annotation).

  • The emptyArea field and its accessors in com.itextpdf.layout.layout.LayoutArea have been moved to RootLayoutArea.

  • The class com.itextpdf.forms.PdfSigFieldLockDictionary has been replaced by com.itextpdf.forms.PdfSigFieldLock.

Add-ons

pdfHTML

  • All jsoup classes and packages have moved from org.jsoup to com.itextpdf.html2pdf.jsoup.

  • Some constants in in com.itextpdf.html2pdf.css.CssConstants have moved to com.itextpdf.html2pdf.html.AttributeConstants.

5. Removed packages, classes, fields and methods

The following things have been removed from iText in 7.1.0

Core

  • Most constants in com.itextpdf.io.font.FontConstants have been removed. The rest was deprecated.

  • Some methods in com.itextpdf.kernel.font.PdfFont have been removed.

  • To fix inconsistencies, DRAW_MODE fields in com.itextpdf.kernel.pdf.IsoKey have been removed.

  • makeIndirect and copyTo methods belonging to classes that inherited from "PdfObject* have been removed.

  • Several methods and classes in com.itextpdf.kernel.pdf.tagging have been removed during tagging improvements.

  • Several methods in com.itextpdf.kernel that should not have been in use or were deprecated have been removed.

  • The height and width properties in com.itextpdf.layout.ElementPropertyContainer now only work with UnitValue, all methods that used float have been removed.

  • com.itextpdf.layout.element.Cell#add(java.lang.String) has been removed, use a BlockElement such as Paragraph instead.

  • A cleanup in com.itextpdf.layout has removed obsolete methods related to old rendering code.

6. Changed packages, classes, methods and fields

Core

  • com.itextpdf.io.font several methods changed name or argument lists to fix inconsistencies and bugs.

  • com.itextpdf.io.source.FileChannelRandomAccessSource no longer implements java.io.Serializable.

  • com.itextpdf.kernel.events.EventDispatcher no longer implements java.io.Serializable.

  • com.itextpdf.kernel.font.PdfFont the method containsGlyph(char) has been removed, use containsGlyph(int) instead.

  • com.itextpdf.kernel has had several methods change their return type to fix inconsistencies.

  • makeIndirect() and copyTo() methods belonging to classes that inherited from PdfObject have been removed, use PdfObject#copyTo() and PdfObject#makeIndirect() instead.

  • Return type of method com.itextpdf.kernel.pdf.PdfPage#removePage(int) has been changed to void due to change in functionality.

  • Classes in com.itextpdf.kernel.pdf.annot now return their own type instead of the supertype for layout-methods (e.g. setBorderStyle).

  • Changes in com.itextpdf.kernel.pdf.canvas.parser to support the new Counter mechanisms for Volume licenses.

  • Methods in com.itextpdf.kernel.pdf.colorspace.PdfShading that return an array now will all return a PdfArray.

  • Major changes in return types, argument lists, interface inheritance (and more) in com.itextpdf.kernel.pdf.tagging and com.itextpdf.kernel.pdf.tagutils to allow the improvements for tagged pdf.

  • Return type changes in com.itextpdf.layout to fix inconsistencies.

  • com.itextpdf.forms.fields.PdfFormField, inconsistency fixes.

  • com.itextpdf.signatures.PdfSigner, inconsistency fixes.

Change in counters logic

Previously counters had getCounter() method and were in a way responsible for creating and filtering themselfs based on class there were used in. Now ICounterFactory responsible for creating and filtering counters and the actual class that process read and write event now extends from ICounter.

  • CounterManager deals with registration of counters instead of CounterFactory (to avoid confusion with ICounterFactory interface).

  • For simple cases use SimpleCounterFactory.

  • NoOpCounter was removed since there is no point in registering counter that does nothing.

  • You'll have to unregister its ICounterFactory implementation to disable a counter.

  • Since now there could be multiple counters registered, classes extended from PdfDocument should override getCounters() method instead of getCounter().

7. Visibility changes

Core

  • com.itextpdf.io.font several classed and methods that should not have been used externally have been decreased in visibility from public to protected/private and from protected to package-private.

  • The constructors for com.itextpdf.kernel.pdf.PdfOutline have had their visibility reduced to package-private. To create them, use PdfDocument#getOutlines() instead.

  • In com.itextpdf.kernel.pdf.annot, the visibility of the constructors for the specific annotations have been made protected. To create such annotations, use PdfAnnotation#makeAnnotation() instead.

  • com.itextpdf.kernel.pdf.colorspace.PdfShading: several methods changed from public to protected.

  • com.itextpdf.layout.renderer: decrease in visibility for fields and methods not intended for public use.