Java interface changes for PDF Toolbox SDK

There are several changes in naming and behavior in the Java interface to bear in mind when migrating from the the 3-Heights® PDF Toolbox API to the PDF Toolbox SDK.

Namespaces

The company namespace of PDF Tools AG is com.pdf_tools, both in the 3-Heights® PDF Toolbox API and in the PDF Toolbox SDK.

In the 3-Heights® PDF Toolbox API, most interface elements reside in the namespace com.pdf_tools.pdf, except for the following type, which reside directly in com.pdf_tools:

• Point
• Rectangle
• Size
• ErrorCode
• ErrorCodeException
• FileStream
• MemoryStream
• Stream

The PDF Toolbox SDK introduces the following new namespaces:

Namespace	Area of usage
com.pdf_tools.fourheights.pdftoolbox	Base namespace
com.pdf_tools.fourheights.pdftoolbox.geometry	Geometric related
com.pdf_tools.fourheights.pdftoolbox.geometry.real	For floating point numbers
com.pdf_tools.fourheights.pdftoolbox.geometry.integer	For integer numbers
com.pdf_tools.fourheights.pdftoolbox.pdf	General PDF related
com.pdf_tools.fourheights.pdftoolbox.pdf.annotations	Annotation related
com.pdf_tools.fourheights.pdftoolbox.pdf.content	Page content related
com.pdf_tools.fourheights.pdftoolbox.Pdf.Forms	Form field related
com.pdf_tools.fourheights.pdftoolbox.pdf.navigation	Document navigation related

The Sdk class

License keys and product version

In the 3-Heights® PDF Toolbox API, the public methods setLicenseKey and getProductVersion of the common base class internal.NativeObject allows setting a license key and querying the version of the API.

In the PDF Toolbox SDK, this functionality has been moved to the class Sdk. Specifically:

• Sdk.initialize must be called to set a license key. See also License keys.
• Sdk.getVersion gets the API’s version number as a string.

The PDF Producer entry

In the 3-Heights® PDF Toolbox API, when creating a PDF, the Metadata object sets the PDF’s Producer entry via the method Metadata.setProducer.

In the PDF Toolbox SDK, the class pdf.Metadata has no method pdf.Metadata.setProducer. Instead, the Producer entry for all output PDFs is preconfigured as a string consisting of two parts:

1. The first part (the “base” part) is encoded in the license key. Hence, this part is determined when buying a license from Pdftools.
2. The second part (the “suffix” part) is configured when calling Sdk.initialize as an argument. It is recommended to use the suffix solely for version information.
   The assembled Producer entry can be obtained after calling Sdk.initialize using the method Sdk.getProducerFullName.

AutoCloseable implementation removed

In the PDF Toolbox SDK, the implementation of the AutoCloseable interface has been removed from all but the following classes:

• Document
• ContentGenerator
• TextGenerator
• Stream

Native resources are now released automatically when getting or appending a page.

Structs extend NativeBase

In the 3-Heights® PDF Toolbox API, interface elements documented as struct are independent Java classes.

In the PDF Toolbox SDK, these structs are still Java classes, but they now extend com.pdf_tools.fourheights.pdftoolbox.internal.NativeBase. As a consequence, an attempt to load the native library (if not already loaded) is done when constructing a struct. This is due to the static constructor in this base class.

Exceptions

In the PDF Toolbox SDK, the ErrorCodeException has been renamed to PdfToolboxException. The method ErrorCodeException.getCode has been removed and substituted by the following new classes, each extending PdfToolboxException:

• ConformanceException
• CorruptException
• LicenseException
• PasswordException
• UnknownFormatException
• UnsupportedFeatureException Instead of an ErrorCodeException with method ErrorCodeException.getErrorCodeErrorCode.IO, a java.io.IOException is generated.

OffsetDateTime

In the 3-Heights® PDF Toolbox API, class members that represent date and time have a type java.util.Calendar.

In the PDF Toolbox SDK, dates and times are represented by the type java.time.OffsetDateTime. This affects the following members:

• Methodpdf.FileReference.getModificationDate
• Methodspdf.Metadata.‹get|set›CreationDate
• Methodpdf.Metadata.‹get|set›ModificationDate
• Methodpdf.forms.SignatureField.getDate

Renaming

Some interface elements have been renamed. The following principles apply:

• Interface elements that include abbreviations are now written consistently in Pascal case. For example, RGB → Rgb, except for two-letter abbreviations, which are written as two capital letters, e.g. IO.
• Some abbreviations have been changed to full words, e.g. Char → Character.
• Some words that are repeated in the introduced namespace have been dropped, e.g. AnnotationPopup → pdf.annotations.Popup.
• Improved clarity, brevity, jargon, and technical correctness.

Affine transform objects should be initialized

In the 3-Heights® PDF Toolbox API, Transformation is a class.

In the PDF Toolbox SDK, this element has been renamed to geometry.real.AffineTransformation, and its type has changed to struct. Interface elements documented asstruct are still classes in Java, but they behave a little differently.

Specifically, default constructed geometry.real.AffineTransform objects are not valid. (A matrix with all values 0 is singular.) Default constructed geometry.real.AffineTransform objects should always be initialized with geometry.real.AffineTransform.getIdentity.

For example:

AffineTransform transform = AffineTransform.getIdentity();

Creation and copying methods

In the 3-Heights® PDF Toolbox API, most document-associated objects are created in an output document by static methods Document.create... and copied from an input document to an output document by static methods Document.copy.... For example, Document.createPage, Document.copyPage.

In the PDF Toolbox SDK, all these methods have been moved from the Document class to the class that is created or copied. For example, method Document.createPage → pdf.Page.create.

This affects the following classes:

• Page
• Image
• ImageMask
• Font
• Group
• ColorSpace
• Paint
• Text
• Metadata
• FileReference
• SubForm
• GeneralTextField
• CombTextField
• CheckBoxField
• RadioButtonField
• ListBoxField
• ComboBoxField
• NamedDestination
• OutlineItem
• Annotation
• Link
• FileAttachmentAnnotation
• FreeTextAnnotation
• StickyNoteAnnotation
• TextStampAnnotation
• CustomStampAnnotation
• CircleAnnotation
• SquareAnnotation
• LineAnnotation
• PolyLineAnnotation
• PolygonAnnotation
• FreeDrawingAnnotation
• ContentElement
• FormFieldNode

Constructors

In the 3-Heights® PDF Toolbox API, some document-associated objects are created by means of a constructor. For example, FitPageDestination.FitPageDestination.

In the PDF Toolbox SDK, most of these document-associated objects are now created and copied with static methods create and copy.

This affects the following classes:

• EmbeddedPdfLink
• FitHeightDestination
• FitPageDestination
• FitRectangleDestination
• FitWidthDestination
• LocationZoomDestination
• WebLink

In the PDF Toolbox SDK, the following classes (most of them not document-associated) have constructors:

• pdf.Encryption
• pdf.content.ContentExtractor
• pdf.content.ContentGenerator
• pdf.content.Fill
• pdf.content.PageCopyOptions
• pdf.content.PathGenerator
• pdf.content.Path
• pdf.content.Stroke
• pdf.content.TextGenerator
• pdf.content.Transparency
• pdf.navigation.OutlineCopyOptions

Unknown PDF conformance

In the 3-Heights® PDF Toolbox API, the Conformance enumeration has a value Conformance.UNKNOWN. The PDF Toolbox SDK enum pdf.Conformance has no such value. The handling of unknown (i.e. automatically upgrading) PDF conformance is now done as follows:

• In the method pdf.Document.create, the second argument pdf.Conformance is allowed to be null, where a null value has the same meaning as the removed value Conformance.UNKNOWN.
• The method pdf.Document.getConformance always returns the current conformance. For input documents, this is the claimed conformance. For output documents, this is either the explicit conformance set when creating, or (if created with null) the conformance the output PDF would have if closed now.

Copy options

In the 3-Heights® PDF Toolbox API, page copying and outline copying behavior is configurable by means of the CopyOptionenum.

In the PDF Toolbox SDK, this enum has been substituted by new classes:

• pdf.PageCopyOptionsUsed in methods pdf.Page.copy and pdf.Group.createFromPage.
• pdf.navigation.OutlineCopyOptionsUsed in method pdf.navigation.OutlineItem.copy.

Each copying configuration decision is reflected in a class member. Apart from boolean for on-off decisions, the following enumerations model possible choices:

• pdf.CopyStrategy
• pdf.RemovalStrategy
• pdf.NameConflictResolution
• pdf.forms.FormFieldCopyStrategy
• pdf.navigation.NamedDestinationCopyStrategy

This clarifies the copying behavior and allows sensible default values.

Color space classes

Class hierarchy
In the 3-Heights® PDF Toolbox API, there is a single class ColorSpace, which covers all types of color spaces.

In the PDF Toolbox SDK, the ColorSpaceType enumeration and the method ColorSpace.getType have been removed. Instead, there are the following new classes, all extending pdf.content.ColorSpace:

• pdf.content.CalibratedGrayColorSpace
• pdf.content.CalibratedRgbColorSpace
• pdf.content.DeviceCmykColorSpace
• pdf.content.DeviceGrayColorSpace
• pdf.content.DeviceRgbColorSpace
• pdf.content.IccBasedColorSpace
• pdf.content.IndexedColorSpace
• pdf.content.LabColorSpace
• pdf.content.NChannelColorSpace
• pdf.content.SeparationColorSpace

The 3-Heights® PDF Toolbox API color space type DeviceN now is subsumed by the more general pdf.content.NChannelColorSpace.

Device color spaces versus process color spaces
In the 3-Heights® PDF Toolbox API, the method Document.createDeviceColorSpace does not necessarily create a device color space, e.g., in case of PDF/A.

In the PDF Toolbox SDK, the enumeration DeviceColorSpaceType has been renamed to pdf.content.ProcessColorSpaceType. The class pdf.content.ColorSpace now has the following static method:

pdf.content.ColorSpaceCreateProcessColorSpace(pdf.DocumenttargetDocument, pdf.content.DeviceColorSpaceType type)

This method creates either a device color space, or, in case of PDF/A, a calibrated (grayscale or RGB) or an ICC-based(CMYK) color space.

Embedded/Associated/Attached files

In the 3-Heights® PDF Toolbox API, embedded files, associated files, and files contained in a FileAttachmentAnnotation are jointly listed in the method Document.getEmbeddedFiles.

In the PDF Toolbox SDK, embedded files, associated files, and files contained in file attachment annotations are treated separately. A pdf.Document now has two lists for appending:

• pdf.Document.getAssociatedFiles
• pdf.Document.getPlainEmbeddedFiles

The former method Document.getEmbeddedFiles has been renamed to pdf.Document.getAllEmbeddedFiles, a read-only list that contains embedded files and files contained in pdf.annotations.FileAttachment annotations. This list is equivalent to what a viewer normally lists in an embedded files pane. For example, the Attachments pane in the Adobe PDF viewer.

Annotations

In the PDF Toolbox SDK, the following annotation classes have been renamed for technical correctness:

• FreeDrawingAnnotation → pdf.annotations.InkAnnotation
• CircleAnnotation → pdf.annotations.EllipseAnnotation
• SquareAnnotation → pdf.annotations.RectangleAnnotation

The methods RadioButtenField.getCanToggleOff and RadioButtenField.setCanToggleOff have been removed. In most PDF viewers, there is no support for this feature.

Class hierarchy
In the 3-Heights® PDF Toolbox API, Widget and Link extend the base class Annotation.

In the PDF Toolbox SDK, the classes pdf.forms.Widget and pdf.navigation.Link have been separated from their former base class. Due to this separation:

• A pdf.Page now has the following lists:

  • pdf.Page.getAnnotations
  • pdf.Page.getLinks
  • pdf.Page.getFormFieldWidgets

• The following methods of pdf.annotations.Annotation have been replicated in pdf.forms.Widget and pdf.navigation.Link:

  • getBoundingBox
  • getHidden
  • getNoPrint

The intermediate base classes PolyDrawingAnnotation and ShapeDrawingAnnotation have been removed. All drawing annotations now directly extend the class pdf.annotations.DrawingAnnotation. Those drawing annotations that have a closed path (pdf.annotations.PolygonAnnotation, pdf.annotations.EllipseAnnotation, pdf.annotations.RectangleAnnotation) have methods getFill and setFill.

Class hierarchy comparison

3-Heights® PDF Toolbox (left)	PDF Toolbox SDK (right)

MaxLength in text fields

In the 3-Heights® PDF Toolbox API, the error behavior of the method TextField.setMaxLength depends on the actual underlying class: GeneralTextField allows null values, while CombTextField does not.

In the PDF Toolbox SDK, the methods TextField.getMaxLength and TextField.setMaxLength have been removedand replicated in the derived classes pdf.forms.CombTextField and pdf.forms.GeneralTextField, in the latter as a nullable Integer.

Unified paint creation

In the 3-Heights® PDF Toolbox API, there exist three methods for creating a Paint object:

• Document.createSolidPaint
• Document.createAlphaPaint
• Document.createBlendingPaint

In the PDF Toolbox SDK, these methods have been replaced by a single static method pdf.content.Paint.create. See also Creation and copying methods.

Separate inside rule from path

In the 3-Heights® PDF Toolbox API, the constructor Path.Path has an argument InsideRule rule.

In the PDF Toolbox SDK, this argument is dropped. Instead, the InsideRule now is specified in a new member of pdf.content.Fill when painting the path with pdf.content.ContentGenerator.paintPath, or it is specified ina method argument when clipping with pdf.content.ContentGenerator.clipWithPath. This removes ambiguity and allows a separated treatment of the inside rule for path filling and path clipping.

Path and text clipping operations

In the 3-Heights® PDF Toolbox API, the ContentGenerator supports simultaneous clipping and painting operations.

In the PDF Toolbox SDK, path and text clipping operations have been separated from path and text painting operations as follows:

• The argument boolean intersectClipPath has been removed from the method ContentGenerator.paintPath.

• The method TextGenerator.setRendering has been removed (see also Text generator), and its argument boolean intersectClipping has been dropped without a replacement.

• The new class pdf.content.ContentGenerator has two new methods for path and text clipping operations:

  • pdf.content.ContentGenerator.clipWithPath
  • pdf.content.ContentGenerator.clipWithText

To achieve the same effect of simultaneous clipping and painting, the painting operation has to precede the clipping operation.

Text generator

In the PDF Toolbox SDK, the method TextGenerator.setRendering has been substituted by two separate methods:

• pdf.content.TextGenerator.setFill
• pdf.content.TextGenerator.setStroke

Image size and image mask size

In the 3-Heights® PDF Toolbox API, Image and ImageMask have methods getWidth and getHeight.

In the PDF Toolbox SDK, these are substituted by methods pdf.content.Image.getSize and pdf.content.ImageMask.getSize, both of which have the new type geometry.integer.Size.

---

Reference

For all changes in the Java interface between 3-Heights® PDF Toolbox API and the PDF Toolbox SDK, see Java Reference.